Pourquoi un hook ajouté dans functions.php ne se déclenche-t-il jamais, alors que le même code fonctionne parfaitement une fois déplacé dans un plugin ? Cette question revient régulièrement chez les développeurs qui découvrent que le thème et les extensions ne partagent pas le même moment de chargement dans le cycle d’exécution de WordPress.
Symptôme
Un développeur veut modifier le comportement d’une extension tierce en s’accrochant à l’un de ses hooks, directement depuis functions.php du thème enfant. Le code s’exécute sans erreur, mais l’effet attendu n’apparaît jamais : l’extension semble ignorer complètement le code ajouté.
// Dans functions.php du thème enfant
add_action( 'monextension_avant_rendu', 'monthème_personnaliser_rendu' );
function monthème_personnaliser_rendu() {
echo '<p class="mention-legale">Mentions obligatoires</p>';
}
Rien ne s’affiche. Aucune erreur, aucun avertissement. Le hook monextension_avant_rendu semble ne jamais se déclencher, alors même que l’extension est bien active et fonctionne par ailleurs correctement.
Diagnostic
Le cycle de chargement de WordPress suit un ordre précis : les extensions actives sont chargées en premier, via le hook plugins_loaded, avant que le thème ne soit initialisé via after_setup_theme puis init. Si l’extension déclenche son hook personnalisé très tôt, par exemple directement lors de son chargement initial plutôt que sur une action tardive comme init ou wp, ce hook peut déjà avoir été exécuté au moment où functions.php du thème est lu.
// Dans le fichier principal de l'extension, exécuté avant le thème
do_action( 'monextension_avant_rendu' ); // Déclenché trop tôt pour un thème
Ajouter un add_action() après qu’un do_action() a déjà été exécuté ne produit strictement aucun effet : WordPress ne rejoue jamais un hook déjà passé. C’est une confusion fréquente chez les développeurs qui pensent, à tort, que l’ordre du code source détermine l’ordre d’exécution, alors que c’est l’ordre de chargement des fichiers qui prime.
Correctif
Deux approches permettent de résoudre ce type de situation, selon le hook réellement disponible dans l’extension concernée.
- Si l’extension propose aussi un hook plus tardif équivalent (souvent le cas pour les extensions bien conçues), l’utiliser à la place, quitte à adapter légèrement le comportement recherché.
- Vérifier, en inspectant le code source de l’extension, à quel moment précis du cycle son hook personnalisé se déclenche réellement, plutôt que de supposer un comportement.
// Si l'extension déclenche aussi ce hook plus tard, sur wp_footer par exemple
add_action( 'wp_footer', 'monthème_personnaliser_rendu' );
Dans les cas où aucun hook tardif équivalent n’existe, la seule option reste de contacter l’auteur de l’extension ou de recourir à une extension additionnelle capable d’agir plus tôt dans le cycle, ce qui dépasse le cadre d’une simple modification de thème.
Prévention
Pour éviter de perdre du temps sur ce type de diagnostic, quelques réflexes à adopter systématiquement :
- Avant d’utiliser un hook d’extension inconnu, chercher dans son code source le moment exact où il est déclenché.
- Privilégier les hooks natifs de WordPress (
init,wp,wp_footer) quand l’extension les respecte, plutôt que ses hooks personnalisés les plus précoces. - Tester systématiquement un nouveau hook avec un simple
error_log()avant d’y ajouter une logique complexe, pour confirmer qu’il se déclenche effectivement.
Un outil de débogage listant les hooks exécutés à chaque requête reste le moyen le plus rapide de confirmer ce genre de diagnostic, plutôt que de multiplier les hypothèses sans preuve.
En résumé
Un hook qui ne se déclenche jamais depuis functions.php n’est presque jamais un problème de syntaxe : c’est un problème de timing entre le chargement des extensions et celui du thème. Comprendre cette distinction évite de perdre un temps précieux à chercher une erreur là où il n’y en a pas.
