Composer PHP : installer des paquets, autoload des classes

Composer est le gestionnaire de paquets de PHP. Lancez composer require vendor/package dans le dossier de votre projet : Composer télécharge la bibliothèque dans vendor/, l'enregistre dans composer.json, et vous la chargez, avec tout ce que vous avez installé, en une ligne, require __DIR__ . '/vendor/autoload.php';.

composer require monolog/monolog

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

use Monolog\Logger;
use Monolog\Handler\StreamHandler;
use Monolog\Level;

$log = new Logger('app');
$log->pushHandler(new StreamHandler(__DIR__ . '/app.log', Level::Warning));
$log->warning('Disk almost full', ['free' => '2%']);

Pas d'include pour chaque fichier : l'autoloader charge Logger, StreamHandler et tout ce qu'ils utilisent la première fois que chaque classe est nécessaire. Les paquets viennent de Packagist, le registre public que Composer consulte par défaut.

Installer Composer

Composer a d'abord besoin de PHP sur votre machine (voir installer PHP).

Windows : téléchargez et lancez Composer-Setup.exe depuis getcomposer.org. Il trouve votre php.exe et ajoute composer au PATH. Ouvrez ensuite un nouveau terminal.

macOS avec Homebrew :

brew install composer

Linux : le paquet de votre distribution (sudo apt install composer sur Debian et Ubuntu) fonctionne mais est souvent une version plus ancienne. L'installateur officiel donne la version actuelle :

php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');"
php composer-setup.php
php -r "unlink('composer-setup.php');"
sudo mv composer.phar /usr/local/bin/composer

La page de téléchargement de getcomposer.org montre aussi une ligne qui vérifie le hash de l'installateur avant de l'exécuter ; copiez les commandes depuis cette page pour avoir le hash actuel. Vérifiez ensuite que tout fonctionne :

composer --version

composer.json et composer.lock

composer init pose quelques questions et écrit composer.json, ou composer require le crée au premier paquet. Un exemple typique :

{
    "name": "acme/shop",
    "require": {
        "php": ">=8.2",
        "monolog/monolog": "^3.0",
        "vlucas/phpdotenv": "^5.6"
    },
    "require-dev": {
        "phpunit/phpunit": "^11.0"
    },
    "autoload": {
        "psr-4": {
            "App\\": "src/"
        }
    }
}

• require liste ce dont le projet a besoin pour s'exécuter, y compris la version de PHP.
• require-dev liste les outils réservés au développement (tests, analyse statique). composer require --dev phpunit/phpunit y ajoute un paquet, et composer install --no-dev les ignore sur les serveurs de production.
• autoload indique à Composer où vivent vos propres classes (voir plus bas).

À côté, Composer écrit composer.lock avec la version exacte de chaque paquet installé, y compris les paquets dont dépendent vos paquets. Committez les deux fichiers. Ne committez pas vendor/ : ajoutez-le à .gitignore, car composer install le reconstruit à partir du fichier lock.

composer install ou composer update

composer install          # install exactly what composer.lock says
composer update           # pick the newest allowed versions, rewrite composer.lock
composer update monolog/monolog   # update one package only
composer remove monolog/monolog   # uninstall and remove from composer.json
composer outdated         # list packages with newer versions available

Lancez composer install après avoir cloné un projet et à chaque déploiement : tout le monde reçoit les mêmes versions, celles qui ont été testées. Lancez composer update seulement quand vous voulez mettre à jour, puis testez et committez le nouveau composer.lock. Lancer update sur un serveur de production installe des versions que personne n'a testées.

Contraintes de version : ^ et ~

composer require vendor/package sans version choisit la dernière version stable et écrit une contrainte ^ pour elle, ce qui est en général ce que vous voulez.

Autoloader vos propres classes avec PSR-4

PSR-4 est la convention qui associe un namespace à un dossier : avec "App\\": "src/", la classe App\Text\Slug se trouve dans src/Text/Slug.php. Après avoir ajouté la section autoload, lancez :

composer dump-autoload

L'autoloader de Composer est une fonction enregistrée avec spl_autoload_register(), que PHP appelle chaque fois que le code utilise une classe pas encore chargée. Ce bloc écrit deux fichiers de classes et enregistre son propre petit autoloader PSR-4, pour que vous voyiez la correspondance fonctionner. Ajoutez un troisième fichier de classe et utilisez-le.

<?php
// Two class files, laid out the PSR-4 way
is_dir('src/Text') || mkdir('src/Text', 0777, true);

file_put_contents('src/Greeter.php', <<<'PHP'
<?php
namespace App;

class Greeter
{
    public function hello(string $name): string
    {
        return "Hello, $name";
    }
}
PHP);

file_put_contents('src/Text/Slug.php', <<<'PHP'
<?php
namespace App\Text;

class Slug
{
    public static function from(string $title): string
    {
        return trim(preg_replace('/[^a-z0-9]+/', '-', strtolower($title)), '-');
    }
}
PHP);

// What vendor/autoload.php does for "App\\": "src/"
spl_autoload_register(function (string $class): void {
    $prefix = 'App\\';
    if (!str_starts_with($class, $prefix)) {
        return;
    }
    $file = __DIR__ . '/src/' . str_replace('\\', '/', substr($class, strlen($prefix))) . '.php';
    echo "autoload: $class => ", substr($file, strlen(__DIR__) + 1), "\n";
    if (is_file($file)) {
        require $file;
    }
});

echo (new App\Greeter())->hello('Ada'), "\n";
echo App\Text\Slug::from('Composer & PSR-4, Explained'), "\n";
echo App\Text\Slug::from('Loaded once, used twice'), "\n";

L'autoloader s'exécute une fois par classe : le second appel à Slug::from() n'affiche aucune ligne autoload:, car la classe est déjà chargée. Dans un vrai projet, vous n'écrivez jamais cette fonction vous-même ; vendor/autoload.php enregistre la version de Composer, qui gère aussi les paquets de vendor/. Les namespaces sont présentés sur la page des namespaces.

Erreurs fréquentes

• Class "Monolog\Logger" not found. Le script n'a pas fait require 'vendor/autoload.php', ou le chemin est faux. Utilisez __DIR__ . '/vendor/autoload.php' pour que le chemin ne dépende pas du dossier courant.
• Votre propre classe est introuvable après l'avoir ajoutée à autoload. Lancez composer dump-autoload, et vérifiez que le chemin du fichier correspond exactement au namespace, majuscules et minuscules comprises : App\Text\Slug doit être src/Text/Slug.php, et les serveurs Linux traitent src/text/slug.php comme un fichier différent.
• Your requirements could not be resolved to an installable set of packages. Deux paquets demandent des versions incompatibles de quelque chose, souvent de PHP lui-même. Le message liste le conflit ; composer why-not vendor/package 2.0 explique ce qui bloque une version.
• composer n'est pas reconnu. Le terminal a été ouvert avant l'installation, ou le dossier n'est pas dans votre PATH. Ouvrez un nouveau terminal, ou appelez directement php composer.phar.