Autoload PSR-4 en PHP : mappage namespace–répertoire

PHP PSR-4 est une norme d'autoload qui permet de charger vos classes depuis le bon fichier en se basant uniquement sur leur nom, sans jamais appeler require à la main. Son idée centrale tient en une phrase : vous liez un préfixe de namespace à un répertoire de base, et les segments de namespace restants correspondent directement au chemin du dossier. Dans cet article, nous abordons les règles de PSR-4, sa configuration via composer.json et la résolution des erreurs courantes du quotidien, le tout avec des exemples réels.

Pourquoi l'autoload est-il nécessaire ?

Aux débuts de PHP, il fallait inclure manuellement le fichier de chaque classe avant de l'utiliser. Dans un projet de taille moyenne, le haut de chaque fichier se remplissait de dizaines de lignes require_once, et déplacer un seul fichier obligeait à mettre à jour les chemins un par un. L'autoload supprime cette douleur : la première fois que PHP rencontre une classe non définie, il déclenche une fonction de rappel enregistrée (l'autoloader) et charge le fichier concerné à la volée.

Le cœur de ce mécanisme est la fonction spl_autoload_register(). PSR-4 est un contrat partagé qui définit comment l'autoloader enregistré auprès de cette fonction doit se comporter. La norme a été publiée par le PHP-FIG (Framework Interop Group), et aujourd'hui presque tout l'écosystème moderne, dont Laravel, Symfony et Guzzle, la respecte. Ainsi, différentes bibliothèques peuvent partager un seul autoloader, et déduire un chemin de fichier à partir d'un nom de classe devient totalement déterministe.

La règle fondamentale de PSR-4

Selon PSR-4, un nom de classe pleinement qualifié comporte trois parties : un préfixe de namespace, des namespaces intermédiaires et le nom de la classe. Prenons un exemple. Supposons que vous définissiez ce mappage : le préfixe App\ est lié au répertoire src/. Alors :

• la classe App\Mailer → src/Mailer.php
• la classe App\Services\Invoice → src/Services/Invoice.php
• App\Http\Controllers\HomeController → src/Http/Controllers/HomeController.php

Le mécanisme est simple : le préfixe de namespace (ici App\) est remplacé par le répertoire de base (src/) ; chaque séparateur de namespace restant (\) devient un séparateur de répertoire (/) ; et .php est ajouté à la fin. Trois points méritent attention :

• Le mappage est sensible à la casse. Le fichier de App\Mailer doit être Mailer.php, pas mailer.php. Cela compte surtout sur les serveurs Linux ; macOS/Windows pardonnent en local, mais cela casse en production.
• Le nom du fichier doit être exactement identique au nom de la classe qu'il contient.
• Le préfixe doit correspondre à un répertoire de base ; le préfixe lui-même n'est pas un nom de dossier, il pointe directement vers ce dossier.

Configurer PSR-4 avec composer.json

En pratique, vous n'écrivez pas votre propre autoloader à la main ; vous utilisez celui que Composer génère. Il vous suffit d'ajouter votre mappage PSR-4 à la section autoload de composer.json :

{
    "autoload": {
        "psr-4": {
            "App\\": "src/"
        }
    }
}

Notez que l'antislash est échappé dans le JSON (App\\). Vous pouvez aussi définir plusieurs préfixes ; séparer le code applicatif du code de test est courant :

{
    "autoload": {
        "psr-4": {
            "App\\": "src/"
        }
    },
    "autoload-dev": {
        "psr-4": {
            "Tests\\": "tests/"
        }
    }
}

Ici, autoload-dev n'intervient qu'en développement ; lorsqu'on installe pour la production avec composer install --no-dev, le namespace de test n'est pas chargé. Après avoir ajouté ou modifié un mappage, vous devez régénérer la carte d'autoload :

composer dump-autoload

Cette commande actualise les cartes sous vendor/composer/. Vous ne devez l'exécuter que lorsque vous ajoutez un nouveau préfixe PSR-4 ou modifiez la structure des namespaces ; ajouter une nouvelle classe à un namespace existant ne nécessite aucun dump, car PSR-4 déduit le fichier du chemin.

Utilisation : un point d'entrée d'une seule ligne

Une fois le mappage prêt, dans le point d'entrée de votre projet (par exemple public/index.php), il vous suffit d'inclure l'autoloader généré par Composer :

require __DIR__ . '/../vendor/autoload.php';

use App\Services\Invoice;
use App\Mailer;

$invoice = new Invoice();
$mailer  = new Mailer();

Désormais, vos propres classes comme tous les paquets installés se chargent dès que leur nom est référencé. Le fichier de la classe doit lui-même commencer par une déclaration de namespace ; par exemple src/Services/Invoice.php ressemble à ceci :

<?php

namespace App\Services;

class Invoice
{
    public function total(): float
    {
        return 0.0;
    }
}

La ligne namespace App\Services; doit être parfaitement cohérente avec la place du fichier dans le mappage PSR-4. Une incohérence est la source la plus fréquente de l'erreur « Class not found ».

La différence entre psr-4, classmap et files

Composer prend en charge trois stratégies d'autoload différentes, et savoir quand utiliser chacune vous facilite la vie :

• psr-4 : Mappe un namespace vers un répertoire et déduit le fichier du chemin. Le choix par défaut pour le code moderne ; ajouter une nouvelle classe ne nécessite aucun dump.
• classmap : Analyse les dossiers indiqués et écrit le chemin direct de chaque classe dans une carte. Pratique pour le code hérité (legacy) qui ne suit pas la convention de namespace, mais il exige dump-autoload à chaque ajout de classe.
• files : Charge sans condition, à chaque requête, des fichiers contenant des définitions de fonctions (et non des classes). Généralement utilisé pour des fonctions utilitaires globales.

Pour la plupart des projets, psr-4 suffit. classmap et files interviennent surtout lors de l'intégration de bibliothèques anciennes, sans namespace.

Optimisation de l'autoload en production

PSR-4 est flexible, mais cette flexibilité a un petit coût : à l'exécution, PHP calcule le chemin du fichier à partir du nom de la classe et vérifie l'existence du fichier sur le disque. En production, vous pouvez accélérer cela en le précalculant :

composer dump-autoload --optimize

Cette commande (forme courte -o) analyse toutes les classes PSR-4 et les convertit en classmap, éliminant les recherches de fichiers à l'exécution. Vous utilisez généralement cette combinaison à l'étape de déploiement :

composer install --no-dev --optimize-autoloader

Une réserve : une classmap optimisée est statique. Si vous ajoutez un nouveau fichier de classe en production, la nouvelle classe ne sera pas trouvée tant que vous ne relancez pas le dump. C'est pourquoi le drapeau d'optimisation est destiné au déploiement, et non à l'environnement de développement.

Questions fréquentes

J'ai une erreur « Class not found », où dois-je regarder ?

Vérifiez trois choses d'abord : la déclaration namespace du fichier est-elle cohérente avec le mappage PSR-4, le nom du fichier est-il exactement identique au nom de la classe, casse comprise, et le répertoire de base dans composer.json est-il correct. Si vous avez ajouté un nouveau préfixe, n'oubliez pas d'exécuter composer dump-autoload. Si l'erreur n'apparaît qu'en production, c'est presque toujours une différence de casse ; le système de fichiers Linux est sensible à la casse.

Quelle est la différence entre PSR-4 et PSR-0 ?

PSR-0 est la norme la plus ancienne et plus stricte : elle interprète les underscores (_) du namespace comme des séparateurs de répertoire et reflète l'intégralité du préfixe dans la structure des dossiers. PSR-4, en revanche, mappe le préfixe directement vers un répertoire de base, ce qui permet des structures de dossiers plus plates et plus propres. PSR-0 est désormais obsolète ; préférez toujours PSR-4 dans les nouveaux projets.

Dois-je exécuter dump-autoload pour chaque nouvelle classe ?

Non. Comme PSR-4 déduit le fichier du namespace, ajouter une nouvelle classe à un mappage existant ne nécessite aucune commande supplémentaire ; la classe fonctionne immédiatement. dump-autoload n'est nécessaire que lorsque vous ajoutez un nouveau préfixe PSR-4, utilisez une classmap ou optimisez pour la production.

La configuration de l'autoload de votre projet PHP est-elle devenue confuse ? Si vous avez besoin d'aide pour l'organisation des namespaces, les erreurs « class not found », la migration de code hérité vers PSR-4 ou l'architecture propre d'un projet basé sur Laravel/Symfony, contactez-moi — posons ensemble votre base de code sur des fondations solides.