Pendant le développement d'un thème ou d'une extension, le mode débogage pourra vous faire sauver un temps précieux en permettant notamment l'affichage ou la journalisation d'informations qui ne doivent pas être vues lorsque le site sera en production.
Lorsque vous installez WordPress, le mode débogage est désactivé par défaut. Vous pouvez vérifier ce fait dans le fichier wp-config.php :
define( 'WP_DEBUG', false );
Sans le mode débogage, vous ne verrez pas les différents avertissements de WordPress. Vous ne serez pas non plus avertis si vous utilisez une fonction obsolète (deprecated).
Comme ces informations sont importantes pour tout développeur, il est important d'activer le mode débogage pendant le développement local de votre site.
De plus, si votre site plante alors que le mode débogage n'est pas activé, vous ne verrez qu'une page blanche avec le message « Une erreur critique est survenue sur votre site. ». Aucune trace de ce qui a causé cette erreur. Pas très utile pour déboguer le programme.
Par défaut, lorsque vous activez le mode débogage, les erreurs et avertissements sont affichés à l'écran. Je vous propose de modifier ce comportement afin que les messages de WordPress soient enregistrés dans un fichier journal (log file) et ne soient pas affichés à l'écran.
Ceci évitera que votre site devienne difficile à utiliser lorsqu'il ne plante pas mais que le code génère des avertissements.
Pour configurer votre site de la sorte, vous devez remplacer dans le fichier wp-config.php la ligne define( 'WP_DEBUG', false ); par les lignes suivantes.
// Active (true) ou désactive (false) le mode débogage
define( 'WP_DEBUG', true );
// Pendant le débogage, lorsqu'une erreur est rencontrée, n'affiche pas de message d'erreur à l'écran.
// Plutôt, WordPress enverra un codes d'état HTTP 500 au navigateur.
define( 'WP_DEBUG_DISPLAY', false );
// Pendant le débogage, WordPress enregistrera les messages d'erreur dans un fichier daté situé un niveau au-dessous de la racine du site Web.
// Note : si la constante était simplement initialisée à true, les messages seraient enregistrés dans le fichier wp-content/debug.log donc visibles à partir du nom de domaine.
define( 'WP_DEBUG_LOG', dirname(__FILE__, 2) . '/debug-' . date('Y-m-d') . '.log' );
// En production (lorsque WP_DEBUG est à false), n'affiche pas les erreurs à l'écran.
@ini_set( 'display_errors', '0' );
Quand vous mettrez votre site en ligne, vous n'aurez qu'à changer la ligne define( 'WP_DEBUG', true ); pour define( 'WP_DEBUG', false );. Les autres lignes pourront être laissées telles quelles sans affecter le bon fonctionnement du site.
Avant WordPress 5.1, la constante WP_DEBUG_LOG ne pouvait être initialisée qu'à true ou à false. Maintenant, nous avons le choix entre utiliser une valeur booléenne ou encore une chaîne qui représente le chemin et le nom du fichier journal à utiliser.
Dans le cas où la constante de débogage est initialisée à true plutôt qu'à un chemin, les messages d'erreur et d'avertissement sont enregistrés dans le fichier wp-content/debug.log.
Ce comportement ouvre un important trou de sécurité pour les sites WordPress en ligne si la constante WP_DEBUG est laissée à true.
En effet, si le serveur HTTP n'est pas correctement configuré, n'importe qui pourra voir le contenu de ce fichier en entrant l'URL https://mondomaine.com/wp-content/debug.log.
Heureusement, en initialisant la constante WP_DEBUG_LOG à l'aide d'une chaîne qui représente le chemin et le nom du fichier journal à utiliser, il est désormais facile de déplacer le fichier journal de WordPress en dehors du dossier racine du site Web.
Une technique intéressante consiste à spécifier le chemin du fichier journal à l'aide de la fonction dirname() combinée à la constante __FILE__ qui représente le fichier actuel (ici : wp-config.php). En utilisant la valeur 2 comme second paramètre, on obtient le dossier situé un niveau plus haut que celui du fichier actuel, soit le dossier parent de la racine du site Web.
De plus, dans cet extrait de code, la date du jour est automatiquement ajoutée au nom du fichier.
Ainsi, si la racine du site Web est le dossier /chemin/monsite, le fichier journal sera enregistré dans un fichier au format /chemin/debug-aaaa-mm-jj.log.
define( 'WP_DEBUG_LOG', dirname(__FILE__, 2) . '/debug-' . date('Y-m-d') . '.log' );
Important : que ce soit pendant le développement local ou sur le site en production, le chemin spécifié pour initialiser la constante WP_DEBUG_LOG doit exister sur le serveur HTTP. Le fichier journal pourra être créé par le système mais rien ne se produira si le dossier n'existe pas.
Parfois, il pourrait être préférable d'utiliser un autre dossier. Par exemple, si vous développez localement avec Devilbox sous Windows ou sous Mac, vous pourriez utiliser un chemin du genre /shared/httpd/monsite/dev.
Le problème, c'est que ce chemin n'existera pas sur le serveur de production. Vous pouvez donc mettre à profit votre constante HEBERGEMENT_LOCAL.
Avec le code qui suit, le chemin pourra être différent sur le serveur de développement et sur le serveur de production. Et dans tous les cas, le fichier journal ne pourra pas être consulté à partir de l'URL du site Web et ce, même si une erreur survenait sur le site de production alors que la constante de débogage est à true.
// Pendant le débogage, WordPress enregistrera les messages d'erreur dans le fichier cité.
// Note : si la constante est simplement initialisée à true, les messages seront enregistrés dans le fichier wp-content/debug.log.
if ( HEBERGEMENT_LOCAL ) {
define( 'WP_DEBUG_LOG',dirname(__FILE__, 2) . '/dev/debug-' . date('Y-m-d') . '.log' );
} else {
define( 'WP_DEBUG_LOG', dirname(__FILE__, 2) . '/debug-' . date('Y-m-d') . '.log' );
}
Lorsque vous développez une fonctionnalité dans un thème ou dans une extension, il peut arriver que le navigateur affiche une page blanche ou encore une page qui indique que la page ne fonctionne pas. Il peut également arriver que les résultats attendus ne soient pas au rendez-vous.
Prenez l'habitude de consulter régulièrement le fichier debug.log. Si vous avez bien configuré votre fichier wp-config.php pour le débogage, vous y retrouverez tous les message d'avertissement et les messages d'erreur qui auraient normalement été affichés à l'écran.
Par défaut, sous Windows, le fichier journal s'ouvrira avec le bloc notes. Le problème avec ce logiciel, c'est qu'il ne permet pas de rafraîchir le contenu d'un fichier une fois qu'il a été ouvert. Vous seriez continuellement obligés de fermer puis de réouvrir votre fichier journal.
Vous devriez ouvrir le fichier journal à l'aide de Geany.
Plutôt que d'utiliser les fameux echo pour afficher les valeurs de nos variables à l'écran, il est possible de créer une fonction qui enregistrera les informations désirées dans le fichier debug.log.
Voici le code de cette fonction1. Si elle est définie comme une méthode de la classe d'une extension, elle pourra s'appeler simplement log_debug. Par contre, si elle est définie directement dans un fichier de fonctions du thème, comme functions.php ou un de ses sous-fichiers, il faudra ajouter un préfixe devant son nom pour assurer qu'il soit unique ( ex : function monprefixe_log_debug() ).
Je vous montre ici la fonction à ajouter dans un thème enfant.
/**
* Enregistre une information de débogage dans le fichier debug.log.
* @author Christiane Lagacé <christiane.lagace@hotmail.com>
* Inspiré de http://wp.smashingmagazine.com/2011/03/08/ten-things-every-wordpress-plugin-developer-should-know/
*
* Utilisation : monprefixe_log_debug( 'test' );
*/
function monprefixe_log_debug( $message ) {
if ( is_array( $message ) || is_object( $message ) ) {
error_log( 'Message de débogage: ' . print_r( $message, true ) );
} else {
error_log( 'Message de débogage: ' . $message );
}
}
Le travail avec un fichier journal peut parfois être fastidieux. Ce fichier se remplit vite lors du débogage et il faut prendre soin de le vider régulièrement. C'est pourquoi certains programmeurs préfèrent afficher les informations de débogage à l'écran.
Si vous avez déjà travaillé avec PHP sans utiliser WordPress, il y a fort à parier que vous avez déjà codé une fonction qui permet d'afficher un message de débogage. Il ne vous restera plus qu'à l'adapter pour WordPress.
Important : afin d'éviter l'affichage d'informations sensibles, la fonction ne doit rien afficher lorsque le site est en production.
Voici ce à quoi votre fonction, codée dans functions.php, pourrait ressembler :
/**
* Affiche une information de débogage à l'écran, seulement si WP_DEBUG est à true.
* @author Christiane Lagacé <christiane.lagace@hotmail.com>
*
* Utilisation : monprefixe_echo_debug( 'test' );
* Suppositions critiques : le style .debug doit définir l'apparence du texte
*/
function monprefixe_echo_debug( $message ) {
if ( WP_DEBUG === true ) {
if ( ! empty( $message ) ) {
echo '<span class="debug">';
if ( is_array( $message ) || is_object( $message ) ) {
echo '<pre>';
print_r( $message ) ;
echo '</pre>';
} else {
echo $message ;
}
echo '</span>';
}
}
}
Avant même de songer à afficher un message dans un fichier journal ou à l'écran, vous devriez installer et configurer un éditeur qui contient un débogueur, comme PhpStorm, et y créer un projet pour votre site WordPress.
Vous aurez ainsi accès à toutes les fonctionnalités de débogage d'un tel outil : points d'arrêt, exécution pas à pas, consultation de la valeur des variables, etc.
Il existe des extensions qui facilitent la vie des développeurs WordPress, par exemple :
1. « Ten Things Every WordPress Plugin Developer Should Know ». Cmashing magazine. http://wp.smashingmagazine.com/2011/03/08/ten-things-every-wordpress-plugin-developer-should-know/
▼Publicité
