# « Fatal error: Class not found » après un renommage de dossier de thème

> Diagnostiquer un écran blanc causé par un autoload cassé après le renommage d'un répertoire de thème, sans mise à jour du chemin dans composer.json.

- Auteur : WordPress Développement
- Publié le : 2023-11-21
- Mis à jour le : 2023-11-21
- Catégorie : Thèmes
- URL : https://www.wpmoderne.fr/themes/fatal-error-class-not-found-renommage-dossier-theme/

## L’essentiel

- Le renommage du dossier ne suffit jamais seul
- Le chemin autoload de composer.json reste figé
- Régénérer le vidage d'autoload après chaque déplacement

`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/"
        }
    }
}
```

> L'essentiel à retenir : Le renommage du dossier ne suffit jamais seul ; Le chemin autoload de composer.json reste figé ; Régénérer le vidage d'autoload après chaque déplacement

## 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-v1
```

Le 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 -o
```

L'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.php` ré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.