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

Die Aktivierung von Tracy ist einfach. Fügen Sie einfach diese beiden Codezeilen ein, vorzugsweise direkt nach dem Laden der Bibliothek (wie require 'vendor/autoload.php') und bevor eine Ausgabe an den Browser gesendet wird:

use Tracy\Debugger;

Debugger::enable();

Das erste, was Sie auf der Website sehen werden, ist eine Tracy-Leiste.

(Wenn Sie nichts sehen, bedeutet das, dass Tracy im Produktionsmodus läuft. Aus Sicherheitsgründen ist Tracy nur auf localhost sichtbar. Sie können die Ausführung von Tracy im Entwicklungsmodus erzwingen, indem Sie die Debugger::Development als ersten Parameter der Methode enable() übergeben).

Bei enable() wird die Fehlerberichtsebene auf E_ALL geändert.

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

Um Rechtschreibfehler bei der Zuweisung zu einem Objekt zu erkennen, verwenden wir die Eigenschaft Nette\SmartObject.

Produktionsmodus und Fehlerprotokollierung

Wie Sie sehen können, ist Tracy ziemlich wortgewandt. In einer Entwicklungsumgebung ist dies zu begrüßen, aber auf einem Produktionsserver würde es zu einer Katastrophe führen. Alle Debugging-Informationen können dort nicht angezeigt werden. Daher verfügt Tracy über eine automatische Umgebungserkennung und Protokollierungsfunktion. Anstatt sich selbst anzuzeigen, speichert Tracy Informationen in einer Protokolldatei und zeigt dem Besucher eine für den Benutzer verständliche Server-Fehlermeldung an:

Der Produktionsausgabemodus unterdrückt alle Debugging-Informationen, die über dump() ausgegeben werden, und natürlich alle von PHP erzeugten Fehlermeldungen. Selbst wenn Sie also dump($obj) im Quellcode vergessen, müssen Sie sich auf Ihrem Produktionsserver keine Gedanken darüber machen. Es wird nichts zu sehen sein.

Der Ausgabemodus wird durch den ersten Parameter von Debugger::enable() festgelegt. Sie können entweder eine Konstante Debugger::Production oder Debugger::Development angeben. Eine andere Möglichkeit besteht darin, den Entwicklungsmodus so einzustellen, dass er aktiviert wird, wenn von einer bestimmten IP-Adresse mit einem bestimmten Wert des Cookies tracy-debug auf die Anwendung zugegriffen wird. Die dafür verwendete Syntax lautet cookie-value@ip-address.

Wird er nicht angegeben, wird der Standardwert Debugger::Detect verwendet. In diesem Fall erkennt das System einen Server anhand der IP-Adresse. Der Produktionsmodus wird gewählt, wenn eine Anwendung über eine öffentliche IP-Adresse aufgerufen wird. Eine lokale IP-Adresse führt zum Entwicklungsmodus. In den meisten Fällen ist es nicht notwendig, den Modus einzustellen. Der Modus wird korrekt erkannt, wenn Sie die Anwendung auf Ihrem lokalen Server oder im Produktionsmodus starten.

Im Produktionsmodus zeichnet Tracy automatisch alle Fehler und Ausnahmen in einem Textprotokoll auf. Wenn Sie nichts anderes angeben, wird es in log/error.log gespeichert. Diese Fehlerprotokollierung ist äußerst nützlich. Stellen Sie sich vor, dass alle Benutzer Ihrer Anwendung eigentlich Betatester sind. Sie leisten kostenlos Spitzenarbeit bei der Fehlersuche und Sie wären dumm, wenn Sie ihre wertvollen Berichte unbemerkt in den Papierkorb werfen würden.

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
}

Ein Verzeichnis für die Fehlerprotokollierung kann über den zweiten Parameter der Methode enable() festgelegt werden:

Debugger::enable(Debugger::Detect, __DIR__ . '/mylog');

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 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.2
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: