Erste Schritte mit Tracy

Die Bibliothek Tracy ist eine nützliche tägliche Helferin für PHP-Programmierer. Sie hilft Ihnen:

  • Fehler schnell zu erkennen und zu beheben
  • Fehler zu protokollieren
  • Variablen auszugeben
  • die Ausführungszeit von Skripten und Datenbankabfragen zu messen
  • den Speicherbedarf zu überwachen

PHP ist eine Sprache, die wie geschaffen ist, um schwer aufzudeckende Fehler zu produzieren, da sie Entwicklern erhebliche Freiheit lässt. Umso wertvoller ist das Debugging-Werkzeug Tracy. Unter den Diagnosewerkzeugen für PHP stellt es die absolute Spitze dar.

Wenn Sie heute zum ersten Mal auf Tracy treffen, dann glauben Sie mir, Ihr Leben wird sich in das vor Tracy und das mit ihr teilen. Willkommen im besseren Teil!

Installation

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

composer require tracy/tracy

Sie können auch das gesamte Paket als Datei tracy.phar herunterladen.

Verwendung

Tracy aktivieren wir durch Aufruf der Methode Tracy\Debugger::enable() so früh wie möglich am Anfang des Programms, bevor irgendeine Ausgabe gesendet wird:

use Tracy\Debugger;

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

Debugger::enable();

Das Erste, was Ihnen auf der Seite auffallen wird, ist die Tracy Bar in der rechten unteren Ecke. Wenn Sie sie nicht sehen, kann das bedeuten, dass Tracy im Produktionsmodus läuft. Tracy ist nämlich aus Sicherheitsgründen nur auf Localhost sichtbar. Um zu testen, ob es funktioniert, können Sie es vorübergehend in den Entwicklungsmodus umschalten, indem Sie den Parameter Debugger::enable(Debugger::Development) verwenden.

Tracy Bar

Die Tracy Bar ist ein schwebendes Panel, das in der rechten unteren Ecke der Seite angezeigt wird. Wir können es mit der Maus verschieben, und nach dem Neuladen der Seite merkt es sich seine Position.

Zur Tracy Bar können weitere nützliche Panels hinzugefügt werden. Viele davon finden Sie in den Add-ons, oder Sie können Ihre eigenen schreiben.

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

Debugger::$showBar = false;

Visualisierung von Fehlern und Ausnahmen

Sie wissen sicher gut, wie PHP Fehler meldet: Es gibt etwas Ähnliches in den Quellcode der Seite aus:

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

oder bei einer nicht abgefangenen 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/Presentation/Sign/SignPresenter.php(21): App\Forms\SignFormFactory->create()
#3 /sandbox/vendor/nette/component-model/src/ComponentModel/Container.php(181): App\Presentation\Sign\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

Sich in einer solchen Ausgabe zu orientieren, ist nicht gerade einfach. Wenn wir Tracy einschalten, werden Fehler oder Ausnahmen in einer völlig anderen Form angezeigt:

Die Fehlermeldung schreit förmlich. Wir sehen einen Teil des Quellcodes mit der hervorgehobenen Zeile, in der der Fehler aufgetreten ist, und die Information Call to undefined method Nette\Http\User::isLogedIn() erklärt verständlich, um welchen Fehler es sich handelt. Die gesamte Seite ist außerdem interaktiv, wir können uns zu weiteren Details durchklicken. Probieren Sie es aus.

Und wissen Sie was? Auf diese Weise fängt und zeigt es auch fatale Fehler an. Ohne die Notwendigkeit, irgendeine Erweiterung zu installieren.

Fehler wie ein Tippfehler im Variablennamen oder der Versuch, eine nicht existierende Datei zu öffnen, erzeugen Meldungen der Ebene E_NOTICE oder E_WARNING. Diese können in der Seitengrafik leicht übersehen werden, oder sie sind möglicherweise gar nicht sichtbar (außer durch einen Blick in den Seitencode).

Oder sie können wie Fehler angezeigt werden:

Debugger::$strictMode = true; // alle Fehler anzeigen
Debugger::$strictMode = E_ALL & ~E_DEPRECATED & ~E_USER_DEPRECATED; // alle Fehler außer Deprecation-Meldungen

Anmerkung: Tracy ändert nach der Aktivierung die Fehlerberichterstattungsebene auf E_ALL. Wenn Sie diesen Wert ändern möchten, tun Sie dies nach dem Aufruf von enable().

Entwicklungs- vs. Produktionsmodus

Wie Sie sehen, ist Tracy ziemlich gesprächig, was in einer Entwicklungsumgebung geschätzt werden kann, während es auf einem Produktionsserver ein regelrechtes Unglück verursachen würde. Dort dürfen nämlich keine Debugging-Informationen ausgegeben werden. Tracy verfügt daher über eine automatische Umgebungserkennung, und wenn das Beispiel auf einem Live-Server ausgeführt wird, wird der Fehler statt angezeigt zu werden protokolliert, und der Besucher sieht nur eine benutzerfreundliche Meldung:

Der Produktionsmodus unterdrückt die Anzeige aller Debugging-Informationen, die wir mit dump() ausgeben, und natürlich auch aller Fehlermeldungen, die PHP generiert. Wenn Sie also irgendwo im Code ein dump($obj) vergessen haben, brauchen Sie sich keine Sorgen zu machen, auf dem Produktionsserver wird nichts ausgegeben.

Wie funktioniert die automatische Moduserkennung? Der Modus ist Entwicklung, wenn die Anwendung auf Localhost ausgeführt wird (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 wir den Entwicklungsmodus auch in anderen Fällen aktivieren möchten, beispielsweise für Programmierer, die von einer bestimmten IP-Adresse zugreifen, geben wir diese als Parameter der Methode enable() an:

Debugger::enable('23.75.345.200'); // ein Array von IP-Adressen kann ebenfalls angegeben werden

Wir empfehlen auf jeden Fall, die IP-Adresse mit einem Cookie zu kombinieren. Im Cookie tracy-debug speichern wir ein geheimes Token, z.B. secret1234, und aktivieren auf diese Weise den Entwicklungsmodus nur für Programmierer, die von einer bestimmten IP-Adresse zugreifen und das erwähnte Token im Cookie haben:

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

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

Wenn Sie das Nette Framework verwenden, sehen Sie nach, wie Sie den Modus dafür einstellen, und dieser wird dann auch für Tracy verwendet.

Fehlerprotokollierung

Im Produktionsmodus protokolliert Tracy automatisch alle Fehler und abgefangenen Ausnahmen in einem Textprotokoll. Damit die Protokollierung stattfinden kann, müssen wir den absoluten Pfad zum Protokollverzeichnis in der Variablen $logDirectory festlegen oder als zweiten Parameter der Methode enable() übergeben:

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

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

Wenn wir eine eigene Nachricht oder eine von Ihnen abgefangene Ausnahme protokollieren müssen, verwenden wir dazu die Methode log():

Debugger::log('Ein unerwarteter Fehler ist aufgetreten'); // Textnachricht

try {
	kritischeOperation();
} catch (Exception $e) {
	Debugger::log($e); // auch eine Ausnahme kann protokolliert werden
	// oder
	Debugger::log($e, Debugger::ERROR); // sendet auch eine E-Mail-Benachrichtigung
}

Wenn Sie möchten, dass Tracy PHP-Fehler wie E_NOTICE oder E_WARNING mit detaillierten Informationen (HTML-Bericht) protokolliert, setzen Sie Debugger::$logSeverity:

Debugger::$logSeverity = E_NOTICE | E_WARNING;

Für einen echten Profi ist das Fehlerprotokoll eine wichtige Informationsquelle, und er möchte sofort über jeden neuen Fehler informiert werden. Tracy kommt ihm dabei entgegen, sie kann nämlich über einen neuen Eintrag im Protokoll per E-Mail informieren. Wohin E-Mails gesendet werden sollen, bestimmen wir mit der Variablen $email:

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

Wenn Sie das gesamte Nette Framework verwenden, können Sie dies und Weiteres in der Konfigurationsdatei einstellen.

Damit Ihr E-Mail-Postfach jedoch nicht überflutet wird, sendet sie immer nur eine Nachricht und erstellt die Datei email-sent. Der Entwickler überprüft nach Erhalt der E-Mail-Benachrichtigung das Protokoll, korrigiert die Anwendung und löscht die Überwachungsdatei, wodurch der E-Mail-Versand wieder aktiviert wird.

Öffnen im Editor

Bei der Anzeige der Fehlerseite können Sie auf Dateinamen klicken, und diese öffnen sich in Ihrem Editor mit dem Cursor in der entsprechenden Zeile. Es ist auch möglich, Dateien zu erstellen (Aktion create file) oder Fehler darin zu korrigieren (Aktion fix it). Damit dies funktioniert, müssen Sie nur den Browser und das System konfigurieren.

Unterstützte PHP-Versionen

Tracy kompatibel mit PHP
Tracy 2.10 – 3.0 PHP 8.0 – 8.4
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 letzte Patch-Version.

Ports

Dies ist eine Liste inoffizieller Ports für andere Frameworks und CMS: