Une classe par fichier (PSR-4)

Tout ce chapitre converge vers un petit bloc de JSON. Vos classes ont un espace de noms, vos fichiers les importent avec use, src/ reflète l’arborescence des espaces de noms, et pourtant rien n’a encore dit à Composer que tout cela est lié. PSR-4 est la règle publiée qui fait correspondre un espace de noms à un répertoire sur le disque. Elle vient du PHP-FIG, le groupe qui coordonne ce genre de conventions dans tout l’écosystème.

La règle, précisément

PSR-4 travaille sur des préfixes. Vous dites à Composer : « toute classe dont le nom commence par ce préfixe vit sous ce répertoire, et le reste du nom forme le reste du chemin ». Dans composer.json :

{
    "name": "you/your-project",
    "autoload": {
        "psr-4": {
            "App\\": "src/"
        }
    }
}

Avec cette correspondance, App\Models\Product se résout en trois gestes. Retirez le préfixe App\ : Models\Product. Remplacez les barres obliques inverses par des barres obliques et ajoutez .php : Models/Product.php. Placez le répertoire de base devant : src/Models/Product.php. C’est tout l’algorithme. Aucune configuration par classe, aucune liste de fichiers à entretenir, une règle appliquée à chaque fois.

Warning

Notez la double barre oblique inverse dans "App\\". C’est une chaîne JSON, une barre oblique inverse littérale doit donc être échappée. Facile à oublier, et Composer vous le dira sans détour (un chemin d’autoload qui ne se résout pas) si ça vous arrive.

Brancher le tout

Si vous avez lancé composer init dans Hello, Composer!, ajoutez le bloc autoload à la main dans votre composer.json existant. Puis demandez à Composer d’en tenir compte :

$ composer dump-autoload
Generating autoload files
Generated autoload files

Cela régénère les fichiers de vendor/composer/, dont la table PSR-4 entrevue dans Paquets et chargement automatique. Dès lors, require 'vendor/autoload.php' trouve vos propres classes App\ exactement comme il trouvait déjà Termwind.

Essayez : lancez le point d’entrée de la section précédente. Il affiche 74. Ajoutez ensuite une nouvelle classe sous src/, utilisez-la depuis le même script, et relancez. Rien d’autre à faire.

Quand le relancer

L’autoloader PSR-4 résout les chemins par une règle, pas à partir d’une liste figée, si bien que dans la plupart des installations une nouvelle classe au bon endroit est trouvée immédiatement. Malgré tout, relancer composer dump-autoload après avoir ajouté des classes est une habitude qui vaut le coup. Certaines procédures de déploiement construisent une table de classes optimisée (composer dump-autoload --optimize, ou automatiquement avec composer install --no-dev sur un serveur de production) qui échange la règle à la volée contre de la vitesse, et cette table ne connaît que les classes qui existaient au moment où elle a été générée. Si vous ajoutez src/Models/Discount.php et que PHP ne trouve soudain plus App\Models\Discount, composer dump-autoload est la première chose à essayer. Ça ne coûte rien.

Vérifier votre travail

Composer remarque aussi quand fichiers et espaces de noms ne concordent plus : une faute de frappe dans une ligne namespace, une classe enregistrée dans le mauvais dossier :

$ composer dump-autoload
Generating autoload files
Warning: Ambiguous class resolution, "App\Models\Product" was found in
both "src/Models/Product.php" and "src/Models/product.php", the first
will be used.
Generated autoload files

C’est tout le système, et le meilleur est le peu de place qu’il prend dans vos journées. Donnez un espace de noms à la classe, placez le fichier là où l’espace de noms l’indique, et l’autoloader (cette ligne écrite dans Hello, Composer! et jamais retouchée depuis) la trouve. À partir d’ici, chaque exemple multi-fichiers de ce livre suppose exactement cette organisation : un dossier src/, un espace de noms App\, et un seul require auquel on n’en ajoute jamais un second.