Warning: include(/home/client42/public_html/wp-content/themes/mon-enfant/inc/customisations.php): failed to open stream: No such file or directory. Ce message apparaît dans les logs juste après un déploiement d’un thème enfant fonctionnant parfaitement en local, sur un serveur de préproduction chez un hébergeur différent. Le fichier existe pourtant bel et bien à cet endroit sur le nouveau serveur… mais pas exactement à ce chemin.
Symptôme : ça marche en local, plus ailleurs
Le fichier functions.php du thème enfant contenait une ligne de ce type, écrite lors d’un dépannage rapide un vendredi soir :
require_once '/home/client42/public_html/wp-content/themes/mon-enfant/inc/customisations.php';
Ce chemin absolu correspondait exactement à l’arborescence du serveur de production d’origine. En local, sous un environnement Docker ou Local WP, ou sur un serveur de préproduction chez un autre hébergeur, cette arborescence n’existe simplement pas : pas de dossier /home/client42, un nom d’utilisateur système différent, une racine web ailleurs. Le fichier ne peut pas être trouvé, quelle que soit sa présence réelle sur le disque.
Diagnostic : différencier thème enfant et thème parent
La confusion vient souvent d’un mélange entre deux fonctions proches mais distinctes de l’API WordPress :
get_stylesheet_directory()retourne toujours le chemin absolu du thème actif, c’est-à-dire le thème enfant s’il y en a un.get_template_directory()retourne le chemin absolu du thème parent, celui qui contient lestyle.cssdéclaré via l’en-têteTemplate:.
Un développeur pressé, cherchant à inclure un fichier situé dans le thème enfant, tape parfois un chemin en dur plutôt que de chercher la bonne fonction, en particulier si le code a été copié-collé depuis un ancien projet où le chemin fonctionnait par coïncidence.
Correctif : reconstruire le chemin dynamiquement
La correction consiste à remplacer systématiquement toute chaîne de chemin en dur par une composition à partir des fonctions natives :
require_once get_stylesheet_directory() . '/inc/customisations.php';
Si le fichier appartient en réalité au thème parent (cas fréquent dans un thème enfant qui n’ajoute que des surcouches), la fonction à utiliser change :
require_once get_template_directory() . '/inc/fonctions-communes.php';
Pour les besoins côté navigateur (chemins d’assets, pas de fichiers PHP), les équivalents URL existent également : get_stylesheet_directory_uri() et get_template_directory_uri(), à ne jamais confondre avec leurs homologues de chemin serveur.
Vérifier avant de blâmer le serveur
Face à ce type d’erreur, le réflexe le plus rapide consiste à afficher temporairement les chemins réellement résolus, plutôt que de suspecter d’emblée une mauvaise configuration serveur ou des droits de fichiers incorrects :
error_log( 'Chemin stylesheet : ' . get_stylesheet_directory() );
error_log( 'Chemin template : ' . get_template_directory() );
Comparer ces valeurs avec le chemin en dur qui posait problème permet de confirmer immédiatement le diagnostic, sans perdre de temps à explorer des pistes serveur qui n’ont rien à voir avec la cause réelle.
Prévention : un grep avant chaque mise en production
Une recherche systématique dans le code du thème avant chaque déploiement sur un nouvel environnement permet de détecter ce type de piège avant qu’il ne remonte en production :
grep -rn "/home/" wp-content/themes/mon-enfant/
grep -rn "public_html" wp-content/themes/mon-enfant/
Sur nos projets, cette recherche fait désormais partie de la checklist de recette avant toute migration de thème vers un nouvel hébergement.
Le cas des chemins stockés en base de données
Un piège voisin, plus difficile à repérer par une simple recherche dans les fichiers du thème, concerne les chemins absolus enregistrés dans des options ou des métadonnées via update_option() ou update_post_meta(), par exemple pour mémoriser l’emplacement d’un fichier de cache généré par le thème. Ces valeurs survivent à un export-import de base de données et continuent de pointer vers l’ancien serveur, alors que le code source du thème, lui, a bien été corrigé. Une recherche dans un export SQL de la base, avec le même motif que celui utilisé sur les fichiers, permet de vérifier qu’aucune valeur de ce type ne s’est glissée dans les tables wp_options ou wp_postmeta.
Pourquoi ce piège reste fréquent
Ce type d’erreur survit particulièrement bien aux changements d’équipe : le chemin en dur, ajouté dans l’urgence par une personne qui a depuis quitté le projet, ne se révèle qu’au moment précis du changement d’environnement, parfois des mois ou des années plus tard. Sur un thème enfant en maintenance depuis plusieurs années, il n’est pas rare de découvrir plusieurs occurrences de ce motif accumulées par différents développeurs successifs, chacun ayant reproduit le même raccourci sans le savoir.
En résumé
Un chemin de fichier codé en dur dans un thème enfant fonctionne tant que l’environnement de destination reproduit exactement l’arborescence d’origine, ce qui n’arrive presque jamais entre le poste de développement, la préproduction et la production. Utiliser systématiquement get_stylesheet_directory() et get_template_directory() évite ce piège une fois pour toutes, quel que soit l’hébergeur final.
