Formation PUB020 : WordPress, 2020 Programmation WordPress

15.2 Mode débogage


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é. Vous pouvez vérifier ce fait dans le fichier wp-config.php :

fichier wp-config.php

define( 'WP_DEBUG',  false );

▼Publicité Le texte se poursuit plus bas

Activer et configurer le mode débogage

Sans le mode débogage, vous ne verrez pas les 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, vous devez remplacer dans le fichier wp-config.php la ligne define( 'WP_DEBUG', false ); par les lignes suivantes :

fichier wp-config.php

// 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.
// 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'erreurs dans le fichier wp-content\debug.log.
define( 'WP_DEBUG_LOG', true );
 
// En production (lorsque WP_DEBUG est à false), n'affiche pas les erreurs à l'écran.
@ini_set( 'display_errors', '0' );

Consulter le fichier debug.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'erreurs 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.

Prenez également l'habitude de vider le fichier journal régulièrement afin de retrouver plus facilement l'information qui vient d'y être ajoutée.

Enregistrer nos propres messages dans debug.log

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 mais seulement si la constante WP_DEBUG est à true. Cette fonction n'aura aucun effet quand on n'est plus en débogage.

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, il faudra ajouter un préfixe devant son nom pour assurer qu'il soit unique ( ex : function monprefixe_log_debug() ).

Je vous monter ici la fonction à ajouter dans un thème enfant.

Fichier functions.php du thème enfant

/**
 * Enregistre une information de débogage dans le fichier debug.log, seulement si WP_DEBUG est à true
 *
 * Utilisation : monprefixe_log_debug( 'test' );
 * Inspiré de http://wp.smashingmagazine.com/2011/03/08/ten-things-every-wordpress-plugin-developer-should-know/
 *
 * @author Christiane Lagacé <christianelagace.com>
 *
 */
function monprefixe_log_debug( $message ) {
    if ( WP_DEBUG === true ) {
        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 );
        }
    }
}

Supprimer le fichier debug.log avant de procéder à une mise en ligne

Le fichier debug.log est placé dans le dossier wp-content sous la racine de votre site Web. Il est donc possible de l'afficher à partir de votre nom de domaine avec un URL du genre https://mondomaine.com/wp-content/debug.log.

Aussi, il est important de vider son contenu ou encore de détruire ce fichier avant de procéder à la mise en ligne sans quoi son contenu pourrait donner des indices précieux aux utilisateurs malveillants.

Afficher nos messages de débogage à l'écran sans risque de les oublier une fois le site en production

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.

Voici ce à quoi votre fonction, codée dans functions.php, pourrait ressembler :

Fichier functions.php

/**
 * Affiche une information de débogage à l'écran, seulement si WP_DEBUG est à true
 *
 * Utilisation : monprefixe_echo_debug( 'test' );
 * Suppositions critiques : le style .debug doit définir l'apparence du texte
 *
 * @author Christiane Lagacé <christianelagace.com>
 *
 */
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>';
        }
    }
}

Débogage avec votre éditeur

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 VS Code, 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.

Extensions pour aider au débogage

Il existe des extensions qui facilitent la vie des développeurs WordPress, par exemple :

Sources

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/

Veuillez noter que le contenu de cette fiche vous est partagé à titre gracieux, au meilleur de mes connaissances et sans aucune garantie.
Par Christiane Lagacé
Dernière révision le 15 septembre 2021
Merci de partager !

Site fièrement hébergé chez A2 Hosting.

Soumettre