Erste Schritte mit Tracy

Die Tracy-Bibliothek ist ein nützliches Hilfsmittel für PHP-Programmierer. Sie hilft Ihnen dabei:

  • Fehler schnell zu erkennen und zu korrigieren
  • Fehler zu protokollieren
  • Variablen auszulagern
  • die Ausführungszeit von Skripten/Abfragen zu messen
  • Speicherverbrauch anzeigen

PHP ist eine perfekte Sprache, um kaum erkennbare Fehler zu machen, weil sie Programmierern große Flexibilität bietet. Tracy\Debugger ist deshalb besonders wertvoll. Er ist ein ultimatives Werkzeug unter den Diagnosewerkzeugen.

Wenn Sie Tracy zum ersten Mal treffen, glauben Sie mir, Ihr Leben wird sich in ein Leben vor Tracy und ein Leben mit ihr aufteilen. Willkommen zum guten Teil!

Installation und Anforderungen

Der beste Weg, Tracy zu installieren, ist, das neueste Paket herunterzuladen oder Composer zu verwenden:

composer require tracy/tracy

Alternativ können Sie auch das gesamte Paket oder die Datei tracy.phar herunterladen.

Verwendung

Tracy wird durch den Aufruf der Methode `Tracy\Debugger::enable()' so früh wie möglich zu Beginn des Programms aktiviert, bevor irgendeine Ausgabe gesendet wird:

use Tracy\Debugger;

require 'vendor/autoload.php'; // alternativ tracy.phar

Debugger::enable();

Das erste, was Ihnen auf der Seite auffällt, ist die Tracy-Leiste in der unteren rechten Ecke. Wenn Sie sie nicht sehen, kann das bedeuten, dass Tracy im Produktionsmodus läuft. Das liegt daran, dass Tracy aus Sicherheitsgründen nur auf localhost sichtbar ist. Um zu testen, ob es funktioniert, können Sie es mit dem Parameter Debugger::enable(Debugger::Development) vorübergehend in den Entwicklungsmodus versetzen.

Tracy Bar

Die Tracy-Leiste ist ein schwebendes Panel. Sie wird in der rechten unteren Ecke einer Seite angezeigt. Sie können sie mit der Maus verschieben. Sie merkt sich ihre Position nach dem Neuladen der Seite.

Sie können der Tracy Bar weitere nützliche Panels hinzufügen. Sie können interessante in Addons finden oder Ihre eigenen erstellen.

Wenn Sie die Tracy Bar nicht anzeigen möchten, setzen Sie:

Debugger::$showBar = false;

Visualisierung von Fehlern und Ausnahmen

Sicherlich wissen Sie, wie PHP Fehler meldet: Im Quellcode der Seite steht etwas Ähnliches:

Parse error:  syntax error, unexpected '}' in HomePresenter.php on line 15

oder nicht gefangene Ausnahme:

Fatal error:  Uncaught Nette\MemberAccessException: Call to undefined method Nette\Application\UI\Form::addTest()? in /sandbox/vendor/nette/utils/src/Utils/ObjectMixin.php:100
Stack trace:
#0 /sandbox/vendor/nette/utils/src/Utils/Object.php(75): Nette\Utils\ObjectMixin::call(Object(Nette\Application\UI\Form), 'addTest', Array)
#1 /sandbox/app/forms/SignFormFactory.php(32): Nette\Object->__call('addTest', Array)
#2 /sandbox/app/presenters/SignPresenter.php(21): App\Forms\SignFormFactory->create()
#3 /sandbox/vendor/nette/component-model/src/ComponentModel/Container.php(181): App\Presenters\SignPresenter->createComponentSignInForm('signInForm')
#4 /sandbox/vendor/nette/component-model/src/ComponentModel/Container.php(139): Nette\ComponentModel\Container->createComponent('signInForm')
#5 /sandbox/temp/cache/latte/15206b353f351f6bfca2c36cc.php(17): Nette\ComponentModel\Co in /sandbox/vendor/nette/utils/src/Utils/ObjectMixin.php on line 100

Es ist nicht so einfach, durch diese Ausgabe zu navigieren. Wenn Sie Tracy aktivieren, werden sowohl Fehler als auch Ausnahmen in einer völlig anderen Form angezeigt:

Die Fehlermeldungen schreien förmlich. Sie können einen Teil des Quellcodes mit der hervorgehobenen Zeile sehen, in der der Fehler aufgetreten ist. Eine Meldung erklärt den Fehler deutlich. Die gesamte Website ist interaktiv, versuchen Sie es.

Und wissen Sie was? Fatale Fehler werden auf die gleiche Weise erfasst und angezeigt. Es ist nicht nötig, eine Erweiterung zu installieren (klicken Sie für ein Live-Beispiel):

Fehler wie ein Tippfehler in einem Variablennamen oder der Versuch, eine nicht existierende Datei zu öffnen, erzeugen Berichte der Stufe E_NOTICE oder E_WARNING. Diese können leicht übersehen werden und/oder in einem grafischen Layout einer Webseite völlig versteckt sein. Überlassen Sie Tracy die Verwaltung dieser Meldungen:

Oder sie können wie Fehler angezeigt werden:

Debugger::$strictMode = true; // display all errors
Debugger::$strictMode = E_ALL & ~E_DEPRECATED & ~E_USER_DEPRECATED; // all errors except deprecated notices

Hinweis: Wenn Tracy aktiviert ist, wird die Fehlerberichtsebene auf E_ALL geändert. Wenn Sie dies ändern wollen, tun Sie dies nach dem Aufruf von enable().

Entwicklungs- vs. Produktionsmodus

Wie Sie sehen können, ist Tracy recht gesprächig, was in der Entwicklungsumgebung durchaus zu begrüßen ist, während es auf dem Produktionsserver zu einer Katastrophe führen würde. Das liegt daran, dass dort keine Debugging-Informationen angezeigt werden sollten. Tracy verfügt daher über eine Umgebungserkennung, und wenn das Beispiel auf einem Live-Server ausgeführt wird, wird der Fehler protokolliert und nicht angezeigt, und der Besucher sieht nur eine benutzerfreundliche Meldung:

Der Produktionsmodus unterdrückt die Anzeige aller Debugging-Informationen, die mit dump() gesendet werden, und natürlich auch alle von PHP generierten Fehlermeldungen. Wenn Sie also einige dump($obj) im Code vergessen haben, brauchen Sie sich keine Sorgen zu machen, auf dem Produktionsserver wird nichts angezeigt.

Wie funktioniert die automatische Modus-Erkennung? Der Modus ist Entwicklung, wenn die Anwendung auf localhost läuft (d.h. IP-Adresse 127.0.0.1 oder ::1) und kein Proxy vorhanden ist (d.h. sein HTTP-Header). Andernfalls läuft sie im Produktionsmodus.

Wenn Sie den Entwicklungsmodus in anderen Fällen aktivieren möchten, z. B. für Entwickler, die von einer bestimmten IP-Adresse aus zugreifen, können Sie ihn als Parameter der Methode enable() angeben:

Debugger::enable('23.75.345.200'); // Sie können auch eine Reihe von IP-Adressen angeben

Wir empfehlen unbedingt, die IP-Adresse mit einem Cookie zu kombinieren. Speichern Sie ein geheimes Token, z.B. secret1234, im Cookie tracy-debug, und aktivieren Sie auf diese Weise den Entwicklungsmodus nur für Entwickler, die von einer bestimmten IP-Adresse aus zugreifen und das genannte Token im Cookie haben:

Debugger::enable('secret1234@23.75.345.200');

Sie können den Entwicklungs-/Produktionsmodus auch direkt mit den Konstanten Debugger::Development oder Debugger::Production als Parameter der Methode enable() einstellen.

Wenn Sie das Nette Framework verwenden, sehen Sie sich an, wie Sie den Modus dafür einstellen, der dann auch für Tracy verwendet wird.

Fehlerprotokollierung

Im Produktionsmodus protokolliert Tracy automatisch alle Fehler und Ausnahmen in einem Textprotokoll. Damit die Protokollierung erfolgt, müssen Sie den absoluten Pfad zum Protokollverzeichnis in der Variablen $logDirectory angeben oder ihn als zweiten Parameter an die Methode enable() übergeben:

Debugger::$logDirectory = __DIR__ . '/log';

Die Fehlerprotokollierung ist äußerst nützlich. Stellen Sie sich vor, dass alle Benutzer Ihrer Anwendung eigentlich Betatester sind, die kostenlos erstklassige Arbeit bei der Fehlersuche leisten, und Sie wären dumm, ihre wertvollen Berichte unbemerkt in den Mülleimer zu werfen.

Wenn Sie Ihre eigenen Meldungen oder abgefangenen Ausnahmen protokollieren müssen, verwenden Sie die Methode log():

Debugger::log('Unexpected error'); // text message

try {
	criticalOperation();
} catch (Exception $e) {
	Debugger::log($e); // log exception
	// or
	Debugger::log($e, Debugger::ERROR); // also sends an email notification
}

If you want Tracy to log PHP errors like E_NOTICE or E_WARNING with detailed information (HTML report), set Debugger::$logSeverity:

Debugger::$logSeverity = E_NOTICE | E_WARNING;

Für einen echten Profi ist das Fehlerprotokoll eine wichtige Informationsquelle, und er oder sie möchte über jeden neuen Fehler sofort informiert werden. Tracy hilft ihm dabei. Sie ist in der Lage, für jeden neuen Fehlereintrag eine E-Mail zu versenden. Die Variable $email gibt an, wohin diese E-Mails zu senden sind:

Debugger::$email = 'admin@example.com';

Wenn Sie das gesamte Nette Framework verwenden, können Sie diese und andere Einstellungen in der Konfigurationsdatei vornehmen.

Um Ihr E-Mail-Postfach vor Überflutung zu schützen, sendet Tracy nur eine Nachricht und erstellt eine Datei email-sent. Wenn ein Entwickler die E-Mail-Benachrichtigung erhält, überprüft er das Protokoll, korrigiert seine Anwendung und löscht die Überwachungsdatei email-sent. Dadurch wird der E-Mail-Versand wieder aktiviert.

Öffnen von Dateien im Editor

Wenn die Fehlerseite angezeigt wird, können Sie auf Dateinamen klicken und sie werden in Ihrem Editor geöffnet, wobei der Cursor auf der entsprechenden Zeile steht. Es können auch Dateien erstellt werden (Aktion create file) oder Fehler in ihnen behoben werden (Aktion fix it). Hierfür müssen Sie den Browser und das System konfigurieren.

Unterstützte PHP-Versionen

Tracy ist kompatibel mit PHP
Tracy 2.10 – 3.0 PHP 8.0 – 8.3
Tracy 2.9 PHP 7.2 – 8.2
Tracy 2.8 PHP 7.2 – 8.1
Tracy 2.6 – 2.7 PHP 7.1 – 8.0
Tracy 2.5 PHP 5.4 – 7.4
Tracy 2.4 PHP 5.4 – 7.2

Gilt für die neuesten Patch-Versionen.

Ports

Dies ist eine Liste von inoffiziellen Portierungen auf andere Frameworks und CMS: