Strauss : isoler les dépendances de vos plugins WordPress sans collision de namespaces

Le problème : quand deux plugins se marchent dessus

WordPress fait tourner tous ses plugins dans le même processus PHP. Conséquence directe : si votre plugin et un autre embarquent chacun une version différente de la même bibliothèque Composer, PHP lève une erreur fatale au chargement. C'est le problème classique de collision de dépendances, et il concerne n'importe quel plugin sérieux dès qu'il s'appuie sur des packages tiers.

La solution historique s'appelle Mozart : l'outil préfixe les namespaces de votre dossier vendor/ pour les rendre uniques à votre plugin. Mais Mozart accumule depuis quelques années des lacunes connues. C'est là qu'intervient Strauss, son fork communautaire, aujourd'hui recommandé par défaut.

Source originale : Strauss: The Better Mozart for WordPress Plugin Dependency Isolation — dev.to

Ce que Strauss améliore concrètement

Voici les points de friction de Mozart que Strauss résout :

Deux points méritent d'être soulignés pour un usage en production :

• La conformité des licences : Mozart pouvait altérer les en-têtes de fichiers de manière problématique. Strauss préserve les fichiers de licence et les commentaires d'en-tête, ce qui est indispensable si vous distribuez votre plugin publiquement (GPL, MIT, etc.).
• Le mode non-destructif : Mozart pouvait supprimer des fichiers source lors du préfixage. Strauss ne touche qu'aux copies, ce qui évite les mauvaises surprises en CI.

Intégration en 3 étapes : PHAR, scripts Composer, CI

1. Installer Strauss via PHAR

La méthode recommandée est d'embarquer le PHAR directement dans le projet pour ne pas polluer les dépendances Composer :

mkdir bin && touch bin/.gitkeep

Ajoutez bin/strauss.phar à votre .gitignore :

bin/strauss.phar

2. Câbler les scripts Composer

Dans composer.json, ajoutez les scripts suivants :

{
  "scripts": {
    "prefix-namespaces": [
      "sh -c 'test -f ./bin/strauss.phar || curl -o bin/strauss.phar -L -C - https://github.com/BrianHenryIE/strauss/releases/latest/download/strauss.phar'",
      "@php bin/strauss.phar",
      "@composer dump-autoload"
    ],
    "post-install-cmd": ["@prefix-namespaces"],
    "post-update-cmd": ["@prefix-namespaces"]
  }
}

Ainsi, chaque composer install ou composer update déclenche automatiquement le téléchargement du PHAR (si absent) puis le préfixage. Le dump-autoload final régénère l'autoloader avec les namespaces préfixés.

3. Configurer la cible dans composer.json

Strauss fonctionne en zéro config pour un cas simple, mais vous pouvez affiner via la clé extra.strauss :

{
  "extra": {
    "strauss": {
      "target_directory": "/vendor-prefixed",
      "namespace_prefix": "MonPlugin\\Vendor\\",
      "classmap_prefix": "MonPlugin_",
      "packages": [
        "guzzlehttp/guzzle"
      ]
    }
  }
}

• target_directory : dossier de sortie des fichiers préfixés (à ne pas confondre avec vendor/).
• namespace_prefix : le préfixe appliqué à tous les namespaces détectés.
• packages : liste explicite des packages à isoler (utile pour ne pas préfixer vos propres dépendances de dev).

Éviter les régressions : tester en staging

L'intégration de Strauss introduit une transformation de code. Sans filet de sécurité, une mise à jour de dépendance peut casser silencieusement le préfixage. Voici le minimum à mettre en place.

En local / staging, vérifiez que le dossier préfixé est bien généré après un composer install :

composer install
ls vendor-prefixed/

En CI (GitHub Actions, GitLab CI…), ajoutez une étape dédiée :

- name: Install dependencies
  run: composer install --no-interaction

- name: Check prefixed vendor exists
  run: test -d vendor-prefixed && echo "OK" || exit 1

Avec PHPUnit, si votre plugin embarque des tests, assurez-vous que les classes préfixées sont bien chargées en ajoutant vendor-prefixed/ à l'autoload de test :

{
  "autoload-dev": {
    "psr-4": {
      "MonPlugin\\Tests\\": "tests/"
    }
  }
}

Strauss bénéficie lui-même d'une couverture PHPUnit complète, ce qui donne confiance dans la stabilité de l'outil entre les versions — contrairement à Mozart.

Conclusion

Si vous développez ou maintenez des plugins WordPress qui embarquent des dépendances Composer, la migration de Mozart vers Strauss est un investissement court (quelques minutes) pour un gain de robustesse significatif : préfixage des constantes et des fonctions globales, préservation des licences, comportement non-destructif et meilleure couverture de tests.

Les trois commandes clés à retenir :

# 1. Préparer le dossier
mkdir bin && touch bin/.gitkeep

# 2. Lancer le préfixage manuellement
composer run prefix-namespaces

# 3. Vérifier le résultat
ls vendor-prefixed/

Testez d'abord en staging, vérifiez votre dossier vendor-prefixed/ et branchez la vérification en CI : vous éviterez les collisions de namespaces en production sans sacrifier la conformité des licences.