PHP Composer : guide pratique de gestion des dépendances

PHP Composer est la colonne vertébrale du développement PHP moderne : un gestionnaire de dépendances qui télécharge les bibliothèques dont votre projet a besoin, gère leurs versions et charge automatiquement vos classes. Ce que NPM fait pour JavaScript, Composer le fait pour PHP. Dans ce guide, nous couvrons tout ce qu'il vous faut au quotidien — de l'installation de Composer à l'ajout de paquets avec require, en passant par la logique de composer.lock et l'autoload PSR-4 — avec des exemples réels et fonctionnels.

Qu'est-ce que Composer et pourquoi en avez-vous besoin ?

Autrefois, utiliser une bibliothèque PHP signifiait télécharger des fichiers à la main et les inclure un par un avec require. Cette approche était source d'erreurs et transformait les mises à jour de version en cauchemar. Composer résout trois problèmes fondamentaux :

Résolution des dépendances : il trouve automatiquement les autres paquets dont un paquet a besoin (ainsi que leurs dépendances) et installe des versions compatibles.
Gestion des versions : vous définissez quelles versions sont acceptables, et Composer choisit la meilleure qui respecte cette règle.
Autoload : il charge vos classes et vos paquets par leur nom, sans que vous ayez à inclure chaque fichier manuellement.

Les paquets sont récupérés depuis un dépôt central appelé Packagist (packagist.org). Tout l'écosystème — Laravel, Symfony, Guzzle, PHPUnit — y est distribué.

Installation et premier projet

Vous pouvez installer Composer selon votre système d'exploitation : un script d'installation officiel pour Linux/macOS et un installateur prêt à l'emploi pour Windows. Pour vérifier l'installation :

composer --version

Au démarrage d'un nouveau projet, vous pouvez lancer un assistant interactif ou générer directement un composer.json :

composer init

Cette commande demande le nom du paquet, la description, la licence et les premières dépendances, puis crée un fichier composer.json à la racine. Ce fichier est la carte d'identité de votre projet ; dépendances, règles d'autoload et métadonnées y sont stockées.

Installer des paquets : require et install

La façon la plus directe d'ajouter un paquet est la commande require. Par exemple, pour installer le client HTTP populaire Guzzle :

composer require guzzlehttp/guzzle

Cela télécharge le paquet, l'ajoute à composer.json, met à jour composer.lock et le place dans le dossier vendor/. Vous pouvez aussi fixer une contrainte de version :

composer require guzzlehttp/guzzle:^7.5

Ajoutez les outils nécessaires uniquement en développement (bibliothèques de test, analyseurs de code) avec --dev ; ils sont exclus des installations de production :

composer require --dev phpunit/phpunit

Lorsque vous clonez un projet, vous utilisez install pour installer ses dépendances. Cette commande lit les versions exactes de composer.lock et les installe à l'identique :

composer install

Sur un serveur de production, la combinaison courante pour ignorer les dépendances de développement et optimiser l'autoload est :

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

composer.json contre composer.lock

Confondre le rôle de ces deux fichiers est la source de confusion la plus fréquente. composer.json décrit votre intention : « n'importe quelle version 7.x de Guzzle convient ». composer.lock enregistre la réalité actuelle : « Guzzle 7.8.1 a été installé, exactement ». Une section require typique ressemble à ceci :

{
    "require": {
        "php": "^8.2",
        "guzzlehttp/guzzle": "^7.5",
        "monolog/monolog": "^3.0"
    },
    "require-dev": {
        "phpunit/phpunit": "^11.0"
    }
}

Le sens des opérateurs de version est crucial :

^7.5 — 7.5 et plus, mais inférieur à 8.0. L'opérateur « autoriser les mises à jour compatibles » le plus courant.
~7.5 — 7.5 et plus, mais inférieur à 7.6 (versions correctives uniquement).
7.5.* — n'importe quel correctif de la série 7.5.

Règle d'or : ajoutez toujours composer.lock au contrôle de version (Git). Ainsi, toute l'équipe et le serveur de production installent les mêmes versions, ce qui évite les problèmes du type « ça marchait sur ma machine ».

Quand utiliser update ou install ?

La distinction entre les deux est au cœur de la gestion des dépendances. composer install reste fidèle au fichier de verrouillage et ne change aucune version. composer update met à jour les paquets vers les versions compatibles les plus récentes autorisées par composer.json et réécrit composer.lock :

composer update

Si vous ne voulez mettre à jour qu'un seul paquet, nommez-le :

composer update monolog/monolog

N'exécutez jamais composer update sur un serveur de production. Comme cette commande change les versions, elle peut provoquer des ruptures inattendues en environnement live. Faites la mise à jour en local, testez-la, validez le nouveau composer.lock, et n'exécutez que composer install sur le serveur.

Autoload : vos propres classes avec PSR-4

La fonctionnalité la plus puissante de Composer est l'autoload. Pour que Composer charge aussi vos propres classes, ajoutez un mappage PSR-4 à composer.json. Cela lie un préfixe de namespace à un dossier :

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

Ce mappage signifie : la classe App\Services\Mailer est recherchée dans src/Services/Mailer.php. Après avoir ajouté le mappage, vous devez régénérer la carte d'autoload :

composer dump-autoload

Désormais, une seule ligne au point d'entrée de votre projet suffit. En incluant l'autoloader généré par Composer, vos propres classes et tous les paquets sont chargés automatiquement :

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

use App\Services\Mailer;

$mailer = new Mailer();

Pour la performance en production, l'option --optimize-autoloader (ou -o) précalcule la correspondance classe-fichier, éliminant les recherches dans le système de fichiers à l'exécution.

Automatisation avec les scripts Composer

La section scripts dans composer.json vous permet de définir des raccourcis pour les commandes que vous lancez souvent :

{
    "scripts": {
        "test": "phpunit",
        "check": [
            "@php -l src/",
            "phpunit"
        ]
    }
}

Vous les exécutez avec composer test ou composer check. Des hooks d'événement comme post-install-cmd servent aussi à déclencher des tâches automatiques après l'installation — la génération d'une clé par Laravel après l'installation en est un exemple.

Questions fréquentes

Dois-je versionner composer.lock dans Git ?

Oui, absolument. Dans les projets d'application, composer.lock doit toujours être versionné ; cela garantit que chaque développeur et le serveur de production installent exactement les mêmes versions. Ce n'est que si vous développez une bibliothèque (un paquet) destinée à d'autres qu'il est courant de ne pas versionner composer.lock.

J'obtiens une erreur « Class not found » — pourquoi ?

La cause la plus fréquente est une carte d'autoload obsolète. Si vous avez ajouté un nouveau namespace PSR-4 ou renommé des fichiers/dossiers, lancez composer dump-autoload. Assurez-vous aussi que le namespace correspond exactement au chemin du fichier et au nom de la classe, casse comprise.

Quelle est la différence entre require et require-dev ?

require contient les paquets dont l'application a besoin pour fonctionner dans tous les environnements. require-dev contient les outils nécessaires uniquement pendant le développement (PHPUnit, analyse statique, débogueurs). En production, composer install --no-dev ignore ces dépendances de développement, ce qui rend l'installation plus légère et plus sûre.

La gestion des dépendances de votre projet PHP est-elle devenue un casse-tête ? Si vous avez besoin d'aide pour la configuration de Composer, l'autoload, les conflits de versions ou une architecture propre pour un projet Laravel/Symfony, contactez-moi — bâtissons ensemble des fondations solides pour votre projet.