PHP Fatal error: Uncaught Error: Class "Theme\Blocks\Register" not found — ce message est apparu sur l’écran blanc d’un site en pleine mise en production, juste après qu’un collègue a renommé le dossier du thème de theme-client-v1 à theme-client pour nettoyer l’arborescence avant livraison. Rien d’autre n’avait changé dans le code.
Ce genre d’erreur, je le rencontre régulièrement sur des thèmes qui utilisent Composer pour organiser leurs classes PHP maison plutôt que de tout charger via de simples require dispersés. Voici la démarche de diagnostic suivie, du symptôme jusqu’à la prévention.
Symptôme : un écran blanc juste après un renommage anodin
Le thème utilisait un composer.json maison déclarant un espace de noms PSR-4 pointant vers le dossier inc/ du thème, avec un chemin absolu généré au moment de l’installation initiale des dépendances. Le renommage du dossier parent n’avait, en apparence, aucun rapport avec cette configuration — et c’est justement ce qui rend l’erreur trompeuse.
{
"autoload": {
"psr-4": {
"Theme\\": "inc/"
}
}
}
Diagnostic : le fichier autoload généré contient des chemins absolus
La déclaration psr-4 de composer.json est relative, mais le fichier réellement chargé par WordPress — vendor/autoload.php — s’appuie sur vendor/composer/autoload_psr4.php, qui contient lui des chemins absolus, calculés au moment de l’exécution de composer install. Un simple renommage de dossier via l’explorateur de fichiers ou une commande mv ne régénère jamais ce fichier automatiquement.
cat vendor/composer/autoload_psr4.php
// 'Theme\\' => array($baseDir . '/inc'),
// $baseDir pointait encore vers /var/www/theme-client-v1Le chemin figé dans ce fichier généré référençait encore l’ancien nom de dossier. Résultat : dès qu’une classe du namespace Theme\\ était appelée, l’autoloader cherchait un répertoire qui n’existait plus.
Correctif : régénérer l’autoload, pas seulement réinstaller
La correction ne nécessite pas de réinstaller les dépendances depuis zéro : la commande composer dump-autoload suffit à recalculer les chemins absolus en fonction de l’emplacement actuel du projet.
cd /var/www/theme-client
composer dump-autoload -oL’option -o (pour --optimize) génère en plus une carte de classes statique, plus rapide à charger en production qu’une résolution PSR-4 dynamique à chaque requête — un gain non négligeable sur un thème qui déclare plusieurs dizaines de classes.
Vérifier avant de redéployer
- Confirmer que
vendor/composer/autoload_psr4.phpréférence bien le nouveau chemin après régénération. - Vérifier qu’aucun chemin absolu n’est codé en dur ailleurs dans le thème, notamment dans un fichier de configuration oublié.
- Tester le site sur un environnement de préproduction identique avant la mise en production finale.
Prévention : ne jamais versionner vendor/ avec des chemins figés
Sur ce projet, le dossier vendor/ était versionné dans le dépôt du thème, ce qui a aggravé le problème : le chemin absolu obsolète a été poussé sur le serveur de production sans que la commande de régénération ne soit relancée. Depuis, j’exclus systématiquement vendor/ du contrôle de version pour ce type de thème, et j’ajoute une étape composer install --no-dev --optimize-autoloader au script de déploiement, exécutée à chaque mise en production plutôt qu’en local.
Un dossier
vendor/versionné avec des chemins absolus est une source de bogues silencieuse : le code fonctionne parfaitement tant que personne ne renomme ou ne déplace le projet, puis casse d’un coup sans qu’aucune ligne n’ait été modifiée à la main.
En résumé
Un « Fatal error: Class not found » après un renommage de dossier n’a presque jamais de rapport avec le code PHP lui-même : la cause se trouve dans les chemins absolus figés par Composer au moment de l’installation. La commande composer dump-autoload -o, lancée depuis le nouvel emplacement, résout le problème en quelques secondes — à condition de l’intégrer au script de déploiement plutôt que de la découvrir en urgence après un renommage.
