Afficher le contenu des variables

Tout développeur connaît la fonction var_dump, qui affiche des informations détaillées sur une variable. Malheureusement, sa sortie n'a aucune mise en forme HTML et se fond en une seule ligne, sans parler des problèmes d'échappement HTML. En pratique, il est nécessaire de remplacer var_dump par une fonction plus commode. Cette fonction, c'est dump().

$arr = [10, 20.2, true, null, 'hello'];

dump($arr);
// ou Debugger::dump($arr);

produit la sortie :

Vous pouvez remplacer le thème clair par défaut par un thème sombre :

Debugger::$dumpTheme = 'dark';

Vous pouvez aussi changer la profondeur d'imbrication à l'aide de Debugger::$maxDepth, la longueur des chaînes affichées avec Debugger::$maxLength et le nombre d'éléments de tableau ou d'objet affichés avec Debugger::$maxItems. Naturellement, des valeurs plus basses accélèrent le rendu.

Debugger::$maxDepth = 2; // par défaut : 15
Debugger::$maxLength = 50; // par défaut : 150
Debugger::$maxItems = 50; // par défaut : 100

La fonction dump() peut aussi afficher l'endroit d'où elle a été appelée et, pour les objets, le chemin du fichier où leur classe est définie. Cela se règle par la propriété Debugger::$showLocation :

Debugger::$showLocation = true; // affiche l'information sur l'emplacement
Debugger::$showLocation = false; // la masque

Pour un contrôle plus fin, appelez directement Tracy\Dumper::dump() et passez l'option Dumper::LOCATION réglée sur Dumper::LOCATION_CLASS (seulement là où les classes sont définies) ou Dumper::LOCATION_SOURCE (aussi l'endroit d'où dump() a été appelée).

Des alternatives pratiques à dump() sont dumpe() (dump & exit) et bdump(). Cette dernière nous permet d'afficher les valeurs des variables dans un panneau de la Tracy Bar. C'est très pratique, car les dumps sont séparés de la mise en page et nous pouvons en plus leur donner un titre.

bdump([2, 4, 6, 8], 'nombres pairs jusqu\'à dix');
bdump([1, 3, 5, 7, 9], 'nombres impairs jusqu\'à dix');

Utiliser Tracy\Dumper directement

Derrière dump() se cache la classe Tracy\Dumper, que vous pouvez aussi utiliser directement. Contrairement à dump(), elle ne dépend pas de Debugger et tire tous ses réglages d'un tableau d'options, ce qui la rend pratique pour les scripts autonomes, les outils CLI, ou dès que vous avez besoin du dump sous forme de chaîne. Comme les réglages viennent du tableau et non de Debugger, les valeurs par défaut diffèrent légèrement : la profondeur est de 7 au lieu de 15, par exemple.

Les méthodes renvoient le dump sous forme de chaîne :

use Tracy\Dumper;

$html = Dumper::toHtml($var, [Dumper::DEPTH => 3]);  // HTML pour le navigateur
$text = Dumper::toText($var);                         // texte brut, par exemple pour un journal
$ansi = Dumper::toTerminal($var);                     // texte avec couleurs ANSI pour le terminal

Ou affichez la variable directement avec Dumper::dump(), qui choisit automatiquement la sortie HTML ou terminal selon l'environnement :

Dumper::dump($var, [Dumper::DEPTH => 3]);

La sortie HTML a besoin d'une petite feuille de style et d'un script. Quand vous faites un dump en dehors d'une application équipée de Tracy (c'est-à-dire sans Debugger::enable()), affichez-les une fois dans le head de la page à l'aide de Dumper::renderAssets(). Dumper::dump() le fait toute seule, mais pas toHtml().

Options

La sortie se règle par un tableau d'options passé à toutes les méthodes ci-dessus :

Les options COLLAPSE, COLLAPSE_COUNT et THEME ne s'appliquent qu'à la sortie HTML interactive.

L'option SCRUBBER masque les valeurs sensibles du dump ; voir Scrubber personnalisé pour un exemple complet.

Par exemple, pour obtenir un dump compact sans les hachages des objets :

echo Dumper::toText($var, [Dumper::HASH => false]);

Les couleurs ANSI utilisées par toTerminal() peuvent être personnalisées via Dumper::$terminalColors.

Rendu personnalisé des objets

Par défaut, le dumper rend un objet en énumérant ses propriétés. Ce n'est parfois pas la vue la plus utile : un PhpToken, par exemple, affiche son type sous forme d'identifiant numérique au lieu d'un nom lisible. Vous pouvez apprendre au dumper comment rendre une classe particulière en enregistrant un exporteur dans Dumper::$objectExporters :

use Tracy\Dumper;

Dumper::$objectExporters[PhpToken::class] = function (PhpToken $token, Dumper\Value $value): void {
	$value->value = $token->getTokenName() . ' ' . $token->text;
};

L'exporteur reçoit l'objet et un objet Tracy\Dumper\Value décrivant la façon dont il sera affiché. Affecter une valeur à $value->value remplace l'en-tête (par défaut le nom de la classe) par votre propre texte, si bien qu'au lieu d'une liste de propriétés vous obtenez une étiquette compacte et lisible. Le réglage s'applique à tout dump de cette classe, même aux objets imbriqués dans des tableaux ou d'autres objets. Vous pouvez sinon passer des exporteurs pour un seul appel via l'option Dumper::OBJECT_EXPORTERS de Tracy\Dumper::dump().