mpWebDebug bar, die Web Debug Toolbar zum Debuggen von PHP Projekten

Jeder PHP Entwickler muss spätestens bei Variablen, deren Wert unbekannt ist oder bei Problemen während der Entwicklung die Anwendung Debuggen.

Hat das Projekt eine bestimmte Größe erreicht, ist das Debuggen eine nicht zu unterschätzende Möglichkeit, das Verhalten der Applikation zu beobachten, und kann die die Entwicklungszeit erheblich verkürzen.

Wer eine moderne IDE wie z. B. Eclipse verwendet, kann mit dem PDT-Plugin und Xdebug (Ist in PDT integriert), oder dem Zend Executable Debugger die Applikation auf professionell debuggen. Dazu gehört das setzen von Haltepunkten (Breakpoints), Inspizieren von Daten über den Variablenexplorer, das schrittweise Abarbeiten des Codes, sowie die Möglichkeit zum Modifizieren von Variablen.

Es gibt auch eine andere Art des Debuggens, das Verwenden von PHP eigenen Funktionen (var_dump(), print_r()). Eingesetzt in Webanwendungen, erhält man dadurch zwar auch wichtige Informationen, diese können aber, verteilt über die Webseite, das Layout der Ausgabe zerstören. Es geht aber auch anders, und zwar in Form von formatierter Ausgabe der Debuginformationen. Mein persönlicher Favorit dabei ist die Web Debug Toolbar des symfony Frameworks. Eine kleine Toolbar, die rechts Oben auf den Webseiten erscheint, und bei Klick aufklappt um dann alle wichtigen Informationen (Variablen, Konfiguration, Logs, Meldungen, usw.) zur Applikation liefert.


Klasse mpDebug

Inspiriert von der Web Debug Toolbar habe ich die Klasse mpDebug erstellt, die während der Verarbeitung einer Seite, über die Methoden übergebene Variablen sammelt und am Ende die Information zu den Variablen ausgeben kann. Die Ausgabe ist eine kleine Debugbar (mpWebDebug bar, siehe Screenshot 1), die im Browserfenster oben links erscheint. Bei Bedarf kann man die mpWebDebug bar mit einem Klick aufklappen, dann erscheint eine Liste mit Debuginformationen, die zur Laufzeit gesammelt wurden (Screenshot 2).

  • Screenshot: mpWebDebug bar
    Screenshot 1
  • Screenshot: mpWebDebug bar geöffnet
    Screenshot 2
  • Screenshot: mpWebDebug bar Debugbeispiel
    Screenshot 3


Features

  • Einfaches Debuggen von PHP-Variablen
  • Aktivieren/Deaktivieren der Ausgabe
  • Formatierte Ausgabe der Debuginformationen
  • Zerstört das Layout nicht
  • Keine Addons/Plugins für Browser nötig
  • Funktioniert bei allen modernen Browsern, die JavaScript 1.5 und CSS 2.0 unterstützen

Installation

Die Installation ist denkbar einfach. Die Datei class.mpdebug.php in ein Ordner kopieren, und die Klasse per include_once/require_once einbinden. Die Klasse sollte eingebunden werden, bevor eine Ausgabe an den Client rausgeht, die Erklärung dazu kommt später.

Nach dem Einbinden, sollte auch gleich die Konfiguration gesetzt werden.
// ggf. den Pfad zum Ordner angeben
require_once('class.mpdebug.php');

// Instanz des mpDebug Objektes holen
$mpDebug = mpDebug::getInstance();

// Konfiguration setzen
$options = array(
    'enable'                    => true,
    'ressource_urls'            => array('/path_to_logs/error.txt'),
    'dump_super_globals'        => array('$_GET', '$_POST', '$_COOKIE', '$_SESSION'),
    'ignore_empty_superglobals' => true,
    'max_superglobals_size'     => 512,
    'magic_word'                => 'foobar',
    'user_func'                 => 'myUserFunc'
);
$mpDebug->setConfig($options);

Beschreibung der Konfiguration

enable (bool):
Flag zum Aktivieren von mpDebug.

ressource_urls (array):
Liste von Pfaden zu Dateien, zu denen am Ende der mpWebDebug bar verlinkt werden soll. Das kann z. B. eine Errorlog sein oder eine Protokolldatei sein, dessen Inhalt wichtig sein kann. (optional)

dump_super_globals (array):
Liste von PHP Superglobalen, deren Inhalt ausgegeben werden soll. Es können alle Superglobale angegeben werden. Außnahme ist $GLOBALS, die eine Referenz zur jeder im globalen Bereich zur Verfügng stehenden Variable hat - das kann viel sein. Per default wird immer der Inhalt von $_GET, $_POST, $_COOKIE und $_SESSION ausgegeben. Soll keine Superglobale ausgegeben werden, kann ein leeres array zugewiesen werden. (optional)

Die Ausgabe von Superglobalen $_POST und $_SESSION ist aus Sicherheitsgründen auf max. 512 KB große Inhalte beschränkt.

ignore_empty_superglobals (bool):
Flag um leere Superglobale nicht auszugeben.

max_superglobals_size (int):
Maximale Größe in KB für die auszugebenden Superglobalen $_POST und $_SESSION. Nur Superglobale $_POST und $_SESSION, deren Inhalt kleiner als die angegenene Größe ist, werden ausgegeben.

magic_word (string):
Definition eines "magischen Wortes", um z. B. ein per default deaktiviertes Debugging zu umgehen, überschreibt die Option 'enable'. Das kann z. B. auf einer Liveumgebung sinnvoll sein, um auf einfache Weise auf die gewünschten Informationen zu kommen.
HINWEIS:
Auf einer Liveumgebung hat eine Debugausgabe nichts verloren, sollte es dennoch eingesetzt werden, ist die Verwendung eines "magischen Wortes" ratsam, das nicht so leicht erraten werden kann.
Aktiviert wird das Debugging, durch das Hinzufügen des Parameters and die URL, z. B.

http://domain/mypage.php?magic_word={my_magic_word}

Wurde der korrekte Wert für 'magic_word' übergeben, wird ein temporäres Cookie gesetzt und die Ausgabe des mpWebDebug bars ist für eine Stunde aktiviert (oder bis das Browserfenster geschlossen wird).
Wird diese Option verwendet, muss die Klasse vor der Ausgabe von Inhalten an den Client eingebunden werden, weil das Setzen von Cookies einen header an den Client sendet. (optional)

user_func (string):
Die zweite Möglichkeit, ein deaktiviertes Debugging zu umgehen, überschreibt auch die Option 'enable'. Hierbei kann der Name einer Funktion angegeben werden, dessen Rückgabewert (bool) dann die Aktivierung des Debuggings übernimmt. Beispiele:

// IP-Ueberpruefung, nur zur Veranaschaulichung gedacht, Beispiel ist nicht sicher.
function myUserFunc() {
    return ($_SERVER['REMOTE_ADDR'] == '66.249.72.19') ? true : false;
}

// Beispiel mit Ueberpruefung der Usergruppe
function myUserFunc() {
    $group = UserGroup::getInstance();
    return ($group->isMember(UserGroup::ADMIN)) ? true : false;
}

Beispiele zur Verwendung

// Beispiel Text
$foo = 'Text';
$mpDebug->addDebug($foo, 'Content of foo');

// Beispiel Array
$bar = array('win', 'nix', 'apple');
$mpDebug->addDebug($bar, 'win, nix and apple', __FILE__, __LINE__);

// Beispiel Objekt
class User {
    const MR  = 'Mr.';
    const MRS = 'Mrs.';
    private $firstname;
    private $lastname;
    private $gender;
    function __construct($firstname, $lastname, $gender){
        $this->firstname = $firstname;
        $this->lastname  = $lastname;
        $this->gender    = ($gender == self::MR) ? self::MR : self::MRS;
    }
    function greet() {
        return 'Hi ' . $this->gender . ' ' . $this->lastname;
    }
}

$user = new User('John O.', 'Public', User::MR);
$mpDebug->addDebug($user, 'User object');

// Beispiel text 2
$greet = $user->greet();
$mpDebug->addDebug($greet, 'Greet user');

// Am Ende der Seite ausgeben. Parameter true liefert debug zurueck, false gibt sie direkt aus
echo $mpDebug->getResults(false);

Die Ausgabe der Debuginformationen sollte am Ende der Seite noch vor dem schließenden Body-Tag geschehen. Es funktioniert zwar auch, wenn die Debuginfos nach dem schließenden html-Tag ausgegeben werden, besser ist die Ausgabe vor dem schließenden Body-Tag.

Weitere Beispiele sind ab der Version 0.9 in der mitgelieferten example1.php und example2.php enthalten.


Changelog

  • 2008-12-26 (Version 0.9.1)
    • added: Configuration for max size of debuggable superglobals
  • 2008-08-30 (Version 0.9)
    • changed: Port to PHP5
    • changed: Usage of singleton pattern instead creating a instance in global scope
    • added: New method to get CSS/JS code of mpWebDebug bar
  • 2008-05-30 (Version 0.8)
    • bugfix: id-Attributes starting with numeric value
    • added: Enable debugging with magic word
    • added: Control enabling with userdefined function
  • 2008-05-17 (Version 0.7)
    • added: Setting of configuration
    • added: Check size of superglobals
    • added: Output of variables with state "is_null", "empty" and "!isset"
    • changed: Redesign of JavaScript Code
  • 2007-02-13
    • First release

Liste anderer Debugtools für PHP


Download

Dateiname Dateityp Beschreibung Größe
 mpWebDebug_bar_0.9.1.zip zip 453 KB
 mpWebDebug_bar_0.9.zip zip 235 KB
 mpWebDebug_bar_0.8.zip zip 230 KB

Ältere Downloads anzeigen