Débogage de WordPress

Le débogage de code PHP est une étape incontournable pour tout projet, mais WordPress est livré avec des systèmes de débogage spécifiques conçus pour simplifier le processus ainsi que pour standardiser le code au niveau du cœur, des extensions et des thèmes. Cette page décrit les différents outils de débogage de WordPress et comment être plus productif dans votre développement tout en augmentant la qualité et l’interopérabilité de votre code.

Pour les non programmeurs ou les utilisateurs lambda, ces options peuvent être utilisées pour afficher une information détaillée sur chaque erreur.

WP_DEBUG

WP_DEBUG est une constante PHP (une variable globale permanente) qui peut être utilisée pour activer le mode « debug » dans WordPress. Elle est supposée être positionnée sur false par défaut et est généralement définie à true dans le fichier wp-config.php des copies de développement de WordPress.

define( 'WP_DEBUG', true );
define( 'WP_DEBUG', false );

Note : Les valeurs true et false dans l’exemple ne sont pas entourées d’apostrophes (') car il s’agit de valeurs booléennes (vrai/faux). Si vous mettez les constantes à 'false', elles seront interprétées comme vraies car les guillemets convertissent leur valeur en chaîne de caractères plutôt qu’en booléen.

Il n’est pas conseillé d’utiliser WP_DEBUG ou les autres outils de débogage sur des sites en production ; ils sont destinés à effectuer des essais en local et sur des sites de test.

Erreurs, avertissements et notifications liés à PHP

L’activation de WP_DEBUG entraînera l’affichage de toutes les erreurs, notifications et avertissements liés à PHP. Cela correspond à modifier le comportement de PHP qui n’affiche par défaut que les erreurs fatales et/ou affiche un écran blanc de la mort lorsque des erreurs apparaissent.

L’affichage de toutes les notifications et avertissements de PHP entraîne souvent des messages d’erreur pour des choses qui ne semblent pas être cassées, mais qui ne respectent tout simplement pas les conventions de validation des données appropriées à l’intérieur de PHP. Ces avertissements sont faciles à corriger une fois que le code concerné a été identifié, et le code qui en résulte est presque toujours plus résistant aux bogues et plus facile à maintenir.

Fonctions et arguments obsolètes

L’activation de WP_DEBUG entraînera également des notifications concernant les fonctions et arguments obsolètes de WordPress qui sont utilisés sur votre site. Il s’agit de fonctions ou d’arguments de fonctions qui n’ont pas encore été supprimés du code de base, mais qui devraient l’être dans un avenir proche. Les avis d’obsolescence indiquent souvent la nouvelle fonction qui devrait être utilisée à la place.

WP_DEBUG_LOG

WP_DEBUG_LOG est un compagnon de WP_DEBUG qui fait que toutes les erreurs sont également enregistrées dans un fichier journal nommé debug.log. C’est très utile si vous voulez passer en revue toutes les notifications après coup ou si vous avez besoin de voir les notifications générées hors écran (par exemple lors d’une requête AJAX ou une exécution de wp-cron).

Notez que cela vous permet d’écrire dans un fichier journal en utilisant la fonction error_log() intégrée à PHP, qui peut être utile par exemple lors du débogage d’événements Ajax.

Lorsque WP_DEBUG_LOG est réglé sur true, le journal est enregistré dans le fichier wp-content/debug.log dans l’arborescence WordPress de votre site. À la place de true, vous pouvez fournir un chemin de fichier valide pour que le fichier debug.log soit enregistré ailleurs (c’est le réglage conseillé pour renforcer la sécurité de votre site).

define( 'WP_DEBUG_LOG', true );
-ou-
define( 'WP_DEBUG_LOG', '/tmp/wp-errors.log' );

Note : pour que WP_DEBUG_LOG puisse faire quoi que ce soit, WP_DEBUG doit être activé (réglé sur true). N’oubliez pas que vous pouvez désactiver WP_DEBUG_DISPLAY indépendamment.

WP_DEBUG_DISPLAY

WP_DEBUG_DISPLAY est un autre compagnon de WP_DEBUG qui contrôle si les messages de débogage sont affichés ou non au sein du code HTML des pages. La valeur par défaut est true, ce qui affiche les erreurs et les avertissements au fur et à mesure qu’ils sont générés. Si vous réglez cette option sur false, toutes les erreurs seront masquées. Cette dernière option devrait être utilisée en conjonction avec WP_DEBUG_LOG afin que les erreurs puissent être examinées plus tard.

define( 'WP_DEBUG_DISPLAY', false );

Note : pour que WP_DEBUG_DISPLAY puisse faire quoi que ce soit, WP_DEBUG doit être activé (réglé sur true). N’oubliez pas que vous pouvez contrôler WP_DEBUG_LOG indépendamment.

SCRIPT_DEBUG

SCRIPT_DEBUG est une constante apparentée qui va forcer WordPress à utiliser les versions « dev » des fichiers CSS et JavaScript de base plutôt que les versions minifiées qui sont chargées en temps normal. Cette constante est utile lorsque vous testez des modifications apportées à des fichiers .js ou .css intégrés. La valeur par défaut est false.

define( 'SCRIPT_DEBUG', true );

SAVEQUERIES

L’activation de la constante SAVEQUERIES enregistre les requêtes de la base de données dans un tableau et ce tableau peut être affiché pour faciliter l’analyse de ces requêtes. La constante définie comme true entraîne la sauvegarde de chaque requête, le temps d’exécution de cette requête et la fonction qui l’a appelée.

define( 'SAVEQUERIES', true );

Le tableau est stocké dans la variable globale $wpdb->queries.

REMARQUE : Cela aura un impact sur les performances de votre site, assurez-vous donc de la désactiver lorsque vous ne déboguez pas.

Example de wp-config.php pour le débogage

Le code suivant, inséré dans votre fichier wp-config.php, enregistrera toutes les erreurs, notifications et avertissements dans un fichier appelé debug.log dans le répertoire wp-content. Il masquera également les erreurs afin qu’elles ne perturbent pas l’affichage des pages.

// Active le mode WP_DEBUG
define( 'WP_DEBUG', true );

// Active l’enregistrement dans le fichier /wp-content/debug.log
define( 'WP_DEBUG_LOG', true );

// Désactive l’affichage des erreurs et des avertissements
define( 'WP_DEBUG_DISPLAY', false );
@ini_set( 'display_errors', 0 );

// Utiliser les versions en développement des fichiers JS et CSS de base (seulement nécessaire si vous modifiez ces fichiers de base)
define( 'SCRIPT_DEBUG', true );

NOTE : Vous devez insérer ceci AVANT la mention /* That's all, stop editing! Happy publishing. */ dans le fichier wp-config.php.

Extensions de débogage

Il existe de nombreuses extensions de débogage pour WordPress qui affichent plus d’informations sur les « internals » (notamment sur les filtres et points d’accroche ou hooks en anglais), soit pour un composant spécifique, soit pour un contexte plus général. En voici quelques exemples :

Ressources externes

Traduit par Frédéric Momméja
Relu par Jenny Dupuy & Sébastien SERRE
Dernière mise à jour le 09 mai 2020