Débogage et journalisation

Lors du développement de thèmes et de plugins, il est souvent nécessaire d'afficher des informations de débogage. Grav dispose de puissantes capacités de débogage via une variété de fonctionnalités :

Barre de débogage.

Grav est livré avec un excellent outil pour faciliter cet effort appelé via une Barre de Débogage. Cette fonctionnalité est désactivée par défaut, mais peut être activée globalement ou pour votre environnement de développement uniquement via le fichier de configuration system.yaml :

1 | debugger:
2 |   enabled: true             # Enable Grav debugger and following settings
3 |   provider: debugbar        # Set provider to debugbar
4 |   shutdown:
5 |      close_connection: true  # Close the connection before calling onShutdown(). false for debugging

La barre de débogage PHP fournit toujours un temps de traitement global ainsi que l'utilisation de la mémoire, mais elle comporte désormais plusieurs onglets qui fournissent des informations plus détaillées.

Le premier onglet est pour les messages et vous pouvez l'utiliser pour aider à déboguer votre processus de développement Grav en publiant des informations sur cet onglet à partir de votre code.

En plus des informations sur les requêtes, les exceptions et la configuration, vous pouvez également voir une ventilation détaillée de la synchronisation Grav dans le panneau Chronologie :

Commande de vidage pour PHP.

Si vous essayez de déboguer du PHP, par exemple un plugin personnalisé que vous développez, et que vous souhaitez examiner rapidement un objet ou une variable, vous pouvez utiliser la puissante commande dump(). Cela accepte pratiquement toutes les variables PHP valides et affichera les résultats dans un affichage bien formaté et colorisé dans votre navigateur.

Par exemple, vous pouvez facilement vider une variable ou un objet PHP :

dump($myvariable);

et voir les résultats dans votre navigateur :

Vous pouvez également vider des variables dans l'onglet Messages de la barre de débogage en utilisant la syntaxe :

$this->grav['debugger']->addMessage($myvariable)

Commande de vidage pour Twig.

Vous pouvez également afficher les variables Twig à partir de vos modèles Twig. Cela se fait de la même manière, mais les résultats sont affichés dans le panneau Messages de la barre de débogage. Cette fonctionnalité est désactivée par défaut, mais peut être activée globalement ou pour votre environnement de développement uniquement via le fichier de configuration system.yaml:

1 | twig:
2 |   debug: true              # Enable Twig debugger

Par exemple, vous pouvez facilement vider une variable ou un objet Twig :

1 | {{ dump(page.header) }}

et voir les résultats dans la barre de débogage :

Il est possible de générer plusieurs commandes de vidage en même temps, mais il peut être difficile de les distinguer. Ajoutez du texte statique comme ceci :

1 | {{ dump('page.header output:',page.header) }}

Dump à la console du navigateur depuis Twig.

Pour afficher des variables avant qu'une page ne soit renvoyée par Grav ou dans le cas où aucune actualisation de page ne se produit, comme lors de l'utilisation d'AJAX, il existe une autre alternative. En utilisant une seule ligne de Javascript, n'importe quelle variable peut être affichée dans la console développeur de votre navigateur, par exemple :

<script> console.log({{ page.header|json_encode|raw }}) </script>

Examinez ensuite la valeur dans la console du navigateur :

Affichage d'erreurs.

Notre nouvelle page d'affichage des erreurs fournit des informations détaillées, des backtraces et même des blocs de code pertinents. Cela permet d'isoler, d'identifier et de résoudre plus rapidement les erreurs critiques. Par défaut dans Grav, ceux-ci sont désactivés par défaut, vous devrez donc les activer pour profiter de cette gestion des erreurs utile pour le développement :

1 | errors:
2 |   display: true

Pour les environnements de production, vous pouvez désactiver la page d'erreur détaillée avec quelque chose de plus subtil en configurant les options d'erreurs dans votre fichier user/config/system.yaml et compter sur les erreurs enregistrées dans le fichier :

1 | errors:
2 |   display: false
3 |   log: true

Enregistrement.

La possibilité de consigner des informations est souvent utile, et encore une fois, Grav nous fournit une fonctionnalité de journalisation simple et puissante. Utilisez l'une des syntaxes suivantes :

1 | $this->grav['log']->info('My informational message');
2 | $this->grav['log']->notice('My notice message');
3 | $this->grav['log']->debug('My debug message');
4 | $this->grav['log']->warning('My warning message');
5 | $this->grav['log']->error('My error message');
6 | $this->grav['log']->critical('My critical message');
7 | $this->grav['log']->alert('My alert message');
8 | $this->grav['log']->emergency('Emergency, emergency, there is an emergency here!');

Tous vos messages seront ajoutés au fichier /logs/grav.log.