# Composer contre inclusion manuelle : gérer les dépendances PHP d’une extension

> Autoload, conflits de version, poids du dossier vendor : comparatif concret entre Composer et l'inclusion manuelle de bibliothèques tierces dans une extension WordPress.

- Auteur : Clément Hadrot
- Publié le : 2024-10-03
- Mis à jour le : 2024-10-03
- Catégorie : Extensions
- URL : https://wpmoderne.dev.wordpress-developpement.fr/extensions/composer-vs-inclusion-manuelle-dependances-php/

## L’essentiel

- Composer simplifie mais expose au conflit de version entre extensions
- Mozart permet de préfixer les dépendances pour éviter les collisions
- L'inclusion manuelle reste défendable pour une seule petite bibliothèque

Dès qu'une extension WordPress a besoin d'une bibliothèque tierce — un client HTTP plus robuste que `wp_remote_get()`, une bibliothèque de génération de PDF, un parseur CSV avancé — la question de la gestion des dépendances se pose inévitablement. Composer, standard incontesté de l'écosystème PHP moderne, entre alors en tension avec une contrainte propre à WordPress : plusieurs extensions actives sur le même site peuvent embarquer chacune leur propre copie de la même bibliothèque, à des versions différentes, sans qu'aucun mécanisme natif ne les isole les unes des autres.

Cet article compare les approches disponibles, de l'inclusion manuelle la plus simple jusqu'au préfixage automatisé avec des outils comme Mozart, avec les compromis réels de chacune.

## Le problème central : l'absence d'isolation entre extensions

Contrairement à un projet Symfony ou Laravel qui contrôle l'intégralité de son environnement d'exécution, une extension WordPress partage le même processus PHP que toutes les autres extensions actives du site. Si deux extensions embarquent chacune Guzzle (une bibliothèque HTTP très répandue) à des versions incompatibles, la première chargée « gagne », et la seconde peut se retrouver à utiliser une version de l'API qu'elle n'attend pas, provoquant des erreurs difficiles à diagnostiquer car elles n'apparaissent que sur des sites où les deux extensions coexistent.

## Composer sans précaution : le risque

```
{
    "require": {
        "guzzlehttp/guzzle": "^7.0"
    },
    "autoload": {
        "psr-4": { "Acme\\MonExtension\\": "src/" }
    }
}
```

```
require_once __DIR__ . '/vendor/autoload.php';

use GuzzleHttp\Client;

$client = new Client();
$response = $client->get( 'https://api.exemple.fr/produits' );
```

Ce code fonctionne parfaitement en isolation, mais dès qu'une autre extension active sur le même site embarque également Guzzle à une version différente, l'une des deux classes `GuzzleHttp\Client` chargée en premier détermine le comportement pour les deux extensions, indépendamment de la version que chacune déclare réellement dans son propre `composer.json`.

> L'essentiel à retenir : Composer simplifie mais expose au conflit de version entre extensions ; Mozart permet de préfixer les dépendances pour éviter les collisions ; L'inclusion manuelle reste défendable pour une seule petite bibliothèque

## Le préfixage automatisé avec Mozart

L'outil Mozart, largement adopté par les auteurs d'extensions distribuées sur WordPress.org, résout ce problème en réécrivant automatiquement le namespace de chaque dépendance lors du build, rendant chaque copie strictement unique à l'extension qui l'embarque.

```
{
    "require": {
        "guzzlehttp/guzzle": "^7.0"
    },
    "require-dev": {
        "coenjacobs/mozart": "^0.7"
    },
    "extra": {
        "mozart": {
            "dep_namespace": "Acme\\MonExtension\\Dependencies\\",
            "dep_directory": "/src/Dependencies/",
            "classmap_prefix": "AcmeMonExtension_"
        }
    }
}
```

```
# Génère une copie de Guzzle sous le namespace Acme\MonExtension\Dependencies\
vendor/bin/mozart compose
```

Après ce traitement, le code de l'extension utilise `Acme\MonExtension\Dependencies\GuzzleHttp\Client` plutôt que `GuzzleHttp\Client`. Même si dix extensions embarquent chacune leur propre copie préfixée de Guzzle, elles ne peuvent plus jamais entrer en collision, chacune vivant dans son propre namespace isolé. Le coût : un dossier `vendor` plus volumineux (chaque extension embarque sa propre copie complète plutôt qu'une copie potentiellement partagée) et une étape de build supplémentaire à intégrer au processus de publication.

## L'inclusion manuelle : encore défendable dans certains cas

Pour une bibliothèque unique et de taille réduite, sans dépendances transitives complexes, une inclusion manuelle directe dans le dossier de l'extension reste une option raisonnable, à condition de renommer manuellement le namespace ou d'utiliser un préfixe de fonction si la bibliothèque n'utilise pas les namespaces.

```
// lib/csv-parser/parser.php, copié manuellement et renommé
namespace Acme\MonExtension\Vendor\CsvParser;

class Parser {
    // ...
}
```

Cette approche perd l'avantage majeur de Composer : la gestion automatisée des mises à jour de sécurité de la bibliothèque. Une bibliothèque copiée manuellement doit être surveillée et mise à jour à la main, un processus qui échoue en pratique dès que l'attention de l'équipe se porte ailleurs pendant quelques mois.

## Comparatif de synthèse

| Approche | Risque de collision | Effort de mise en place | Maintenance des mises à jour |
| --- | --- | --- | --- |
| Composer sans préfixage | Élevé sur sites à nombreuses extensions | Faible | Facile (composer update) |
| Composer avec Mozart | Nul | Moyen (configuration du build) | Facile, isolé de façon fiable |
| Inclusion manuelle renommée | Nul si renommage rigoureux | Faible au départ | Manuelle, risque d'oubli |

> Notre position sur les extensions destinées à un usage large, y compris hors de notre contrôle direct : Composer avec Mozart est devenu le standard par défaut dès qu'une dépendance non triviale entre en jeu. Le coût de configuration initial se rentabilise dès la première collision évitée avec une autre extension du même site.

## En résumé

Composer reste l'outil de référence pour gérer les dépendances PHP, mais son usage nu expose au risque réel de collision de version entre extensions cohabitant sur un même site WordPress. Le préfixage automatisé, via un outil comme Mozart, élimine ce risque au prix d'une étape de build supplémentaire, largement justifiée pour toute extension destinée à une distribution large plutôt qu'à un usage strictement interne et maîtrisé.