Le problème

Notre boutique en ligne tient dans un monorepo piloté par moon. Les services Symfony order, stock et shipping partagent deux bibliothèques internes : app-contracts pour les contrats de messages, app-test pour les tests.

Chaque bibliothèque y est déclarée deux fois. Le dependsOn du moon.yml place le service dans le graphe des projets, dont moon déduit l'ordre des tâches et les projets affectés. Le composer.json l'installe : une entrée dans require ou require-dev, et un dépôt de type path qui indique à Composer où la trouver.

Rien ne relie ces deux déclarations. moon déduit des dépendances d'un package.json, mais pour PHP, il se limite à classer les projets et ne lit pas composer.json. Les deux listes dérivent, dans les deux sens.

Une dépendance installée, mais absente du graphe. shipping exige app/test dans son composer.json, mais son moon.yml ne cite pas app-test. Une pull request qui modifie la classe de base des tests ne relance pas ceux de shipping. La casse apparaît plus tard, dans une pull request qui n'y est pour rien.

Une dépendance exigée, mais inutilisée. Un service n'utilise plus une bibliothèque, et son moon.yml ne la cite plus. Son composer.json l'exige encore : elle reste installée avec ses propres dépendances, et leurs failles remontent dans l'audit du service.

Des dépôts à recopier. Composer ne lit les dépôts que dans le composer.json racine, jamais dans ceux des dépendances. Si app/test exigeait app/contracts, chaque service devrait déclarer le dépôt de app/contracts, même sans l'exiger lui-même.

Une bibliothèque de test née de copies

Avant app-test, chaque service avait sa copie du navigateur de test et de la classe de base de ses tests fonctionnels. Les copies avaient divergé : seul order rechargeait l'utilisateur authentifié et savait remplacer un service par un mock, seul stock portait les annotations PHPStan.

Regrouper ces classes dans une bibliothèque met fin à la divergence. Mais elle ajoute une dépendance interne de plus, déclarée à deux endroits.

Les options

Déclarer aux deux endroits, et contrôler en CI

  • Ce qu'elle règle : l'outillage ne change pas. Un script compare dependsOn à require et require-dev, et fait échouer la CI à la moindre différence.
  • Ce qu'elle coûte : deux modifications pour chaque dépendance, et un script qui doit connaître les scopes, les dépôts et les dépendances transitives. Il signale l'écart sans le corriger.

Générer moon.yml depuis composer.json

  • Ce qu'elle règle : Composer reste la référence, comme package.json pour les dépendances implicites des projets JavaScript.
  • Ce qu'elle coûte : moon n'infère rien pour PHP, il faut un plugin qui étende le graphe des projets. Et composer.json ignore les dépendances qui ne sont pas des paquets, comme un Dockerfile partagé. Une partie de dependsOn reste donc écrite à la main.

Générer composer.json depuis moon.yml

  • Ce qu'elle règle : dependsOn devient la seule déclaration. Un plugin de toolchain moon écrit require, require-dev et les dépôts, comme la toolchain JavaScript de moon synchronise les package.json.
  • Ce qu'elle coûte : un plugin WASM à installer, à épingler et à suivre à chaque montée de version de moon. composer.lock reste à mettre à jour avec Composer.

Un dépôt par bibliothèque, publié sur un registre privé

  • Ce qu'elle règle : chaque bibliothèque a de vraies versions, publiées sur Private Packagist ou sur un dépôt Satis. Chaque service monte de version à son rythme.
  • Ce qu'elle coûte : modifier une bibliothèque et ses services demande plusieurs pull requests et une publication. Les bibliothèques sortent du graphe du monorepo, et un service n'est plus testé contre leur dernière version.

Notre recommandation

Une dépendance interne se déclare dans moon.yml, et seulement là. Un plugin de toolchain moon écrit la partie Composer.

Le graphe des projets décide déjà quoi tester, comme dans notre article sur les pipelines CI pilotés par moon. En faire la seule déclaration supprime l'écart, au lieu de le détecter. Composer garde ce qu'il fait bien : résoudre les versions et écrire le lock.

Une seule déclaration, dans moon.yml : moon écrit composer.json et choisit les tests composer.json écrit par la synchronisation require: app/contracts require-dev: app/test repositories: path un dépôt par bibliothèque à la main composer.lock mis à jour par Composer, pas par la synchronisation composer update app/test commande affichée par moon dans un avertissement Graphe des projets : ce que moon relance moon.yml (service order) la seule déclaration dependsOn: - app-contracts - id: app-test scope: development synchronisation toolchain composer (WASM) moon sync projects et avant chaque tâche dependsOn app-test modifié order stock shipping affectés : tests relancés Sans synchronisation : deux déclarations qui divergent Installée mais hors du graphe : modifier app-test ne relance pas les tests de shipping . Exigée mais inutilisée : la bibliothèque reste installée, avec ses dépendances, et auditée.

Le scope choisit la section

Une entrée de dependsOn porte un scope : production par défaut, development, build ou peer. moon s'en sert pour synchroniser les projets, et le plugin les applique à Composer :

  • production et peer vont dans require ;
  • development va dans require-dev : c'est le cas de app-test ;
  • build est ignoré, faute d'équivalent dans Composer.

Retirer une entrée de dependsOn retire le paquet de require, de require-dev et des dépôts. Une bibliothèque exigée seulement par une autre reçoit son dépôt, sans entrer dans require : aucun dépôt n'est à recopier. Seuls les paquets du monorepo sont gérés : symfony/console et les contraintes déjà écrites ne bougent pas.

Le lock reste à Composer

Le plugin modifie des manifestes, il ne lance ni PHP ni Composer. Quand un composer.json change, moon affiche un avertissement avec la commande à lancer : composer update suivi des paquets modifiés. Nommer les paquets compte : un composer update sans argument monterait toutes les dépendances du service.

Des tâches affectées par leurs dépendances

dependsOn relie les projets, mais ce sont les entrées d'une tâche qui la rendent affectée. L'entrée project://^ désigne tous les projets de dependsOn, quel que soit leur scope. Une modification de app-test relance ainsi les tests de order, stock et shipping.

Les compromis assumés

Un plugin hors de moon. moon n'a pas de toolchain PHP officielle : le plugin est un fichier WASM tiers. moon prévient que son API de plugins est expérimentale et peut casser hors des versions majeures. Après chaque montée de version de moon, nous lançons moon sync projects et relisons le diff.

Un lock mis à jour à la main. La synchronisation n'écrit que composer.json. En CI, composer validate échoue si composer.lock n'est plus à jour avec lui.

Des fichiers modifiés par moon run. La synchronisation tourne avant chaque tâche. Ajouter une ligne à dependsOn puis lancer les tests modifie donc composer.json : c'est voulu, et ce diff part dans la même pull request.

Un téléchargement de plus. Le locator github:// interroge l'API GitHub, soumise à des limites de débit : moon conseille alors un GITHUB_TOKEN en CI. Nous épinglons plutôt l'URL directe du fichier d'une release, téléchargé sans appel à l'API. Pour ne dépendre d'aucun hôte, le .wasm peut aussi être versionné dans le dépôt et chargé par file://.

Des versions fictives. Les paquets du monorepo ont tous la version 0.0.0 et la contrainte * : ils évoluent avec leurs services, dans les mêmes commits.

Le signal qui doit faire réexaminer ce choix : une bibliothèque consommée hors du monorepo, avec ses propres versions. Le registre privé redevient alors la bonne option pour elle.

Mise en œuvre

Les exemples utilisent moon 2.6, Composer 2.11, PHP 8.4, Symfony 7.4, Foundry 2.16 et DAMA DoctrineTestBundle 8. Le plugin est moon-composer-toolchain 0.1.0, publié sous licence MIT.

1. Activer la toolchain

# .moon/toolchains.yml
composer:
  plugin: 'https://github.com/nathan-de-pachtere/moon-composer-toolchain/releases/download/v0.1.0/composer_toolchain.wasm'
  pathRepositorySymlink: true

La toolchain s'applique aux projets language: php et à tout projet qui a un composer.json. Sans pathRepositoryUrl, chaque bibliothèque reçoit son propre dépôt path, qui pointe vers son dossier.

2. Déclarer les dépendances dans moon.yml

La bibliothèque de test est un projet moon comme un autre. Son composer.json, dans libs/app-test/, porte le nom du paquet et ses propres dépendances :

// libs/app-test/composer.json
{
  "name": "app/test",
  "type": "library",
  "autoload": { "psr-4": { "AppTest\\": "src/" } },
  "require": {
    "php": ">=8.4",
    "dama/doctrine-test-bundle": "^8.7",
    "symfony/framework-bundle": "^7.4 || ^8.0",
    "zenstruck/browser": "^1.13",
    "zenstruck/foundry": "^2.9",
    "zenstruck/messenger-test": "^1.14"
  }
}

Chaque service déclare ses bibliothèques dans dependsOn, et nulle part ailleurs :

# services/order/moon.yml (extrait)
language: php
layer: application
stack: backend
tags: [symfony, docker]
dependsOn:
  - app-contracts
  - id: app-test
    scope: development

stock et shipping déclarent les mêmes. Le plugin lit le nom du paquet dans le composer.json de la dépendance. Un projet sans composer.json, comme un front ou un Dockerfile partagé, est ignoré.

3. Laisser la synchronisation écrire composer.json

moon sync projects synchronise tous les projets, et moon run le fait avant chaque tâche. Dans services/order/composer.json, le plugin écrit ces clés et conserve le reste, indentation et ordre des clés compris :

// services/order/composer.json (extrait)
{
  "require": {
    "app/contracts": "*"
  },
  "require-dev": {
    "app/test": "*"
  },
  "repositories": [
    {
      "type": "path",
      "url": "../../app-contracts",
      "options": {
        "symlink": true,
        "versions": { "app/contracts": "0.0.0" }
      }
    },
    {
      "type": "path",
      "url": "../../libs/app-test",
      "options": {
        "symlink": true,
        "versions": { "app/test": "0.0.0" }
      }
    }
  ]
}

versions donne aux bibliothèques une version stable. Sans elle, Composer leur attribue une version de développement : celle de la branche git, ou dev-master à défaut. La contrainte * la refuse avec la stabilité minimale par défaut.

Le plugin écrit *, là où notre article sur les contrats de messages écrivait *@dev : avec 0.0.0, @dev devient inutile.

Il reste à mettre à jour le lock, avec la commande que moon affiche :

# services/order
composer update app/test

La référence d'un paquet path dans le lock est un hash de son composer.json et des options du dépôt. Le dossier d'une bibliothèque ne contient pas de dépôt git propre : modifier son code ne change donc pas le lock des services.

4. Relier les tests au graphe

Les services héritent test de .moon/tasks/symfony.yml, avec project://^ en entrée implicite, comme dans notre article sur l'héritage de tâches. Nous y ajoutons une tâche, lancée comme audit depuis l'image de Composer :

# .moon/tasks/symfony.yml (extrait)
tasks:
  composer-validate:
    command: docker run --rm --volume $projectRoot:/app composer:2.11 validate --no-check-publish
    inputs: [composer.json, composer.lock]

validate n'a pas à lire les dépôts path, hors du dossier monté.

5. Faire échouer la CI sur un manifeste non synchronisé

En CI, moon signale déjà une synchronisation qui modifie des fichiers, mais par un simple avertissement. Nous en faisons un échec dans le job checks de qg.yml, dont la matrice reçoit aussi :composer-validate :

# .github/workflows/qg.yml (extrait du job checks)
strategy:
  matrix:
    tasks: [':lint', ':format', ':audit :composer-validate', ':test', ':build :docker-build']
steps:
  # ... checkout, toolchain et buildx inchangés
  - name: Manifestes synchronisés
    run: |
      moon sync projects
      git diff --exit-code
  - run: moon ci ${{ matrix.tasks }}

Une bibliothèque ajoutée à la main dans composer.json, avec son dépôt, mais absente de dependsOn, est retirée par la synchronisation. Le diff qui en résulte fait échouer le job.

6. Partager les classes de base des tests

La classe de base regroupe ce que partagent les tests des services : remise à zéro de la base, transports Messenger de test et navigateur.

// libs/app-test/src/AbstractApiTestCase.php
namespace AppTest;

use Symfony\Bundle\FrameworkBundle\Test\KernelTestCase;
use Zenstruck\Browser\HttpOptions;
use Zenstruck\Browser\Test\HasBrowser;
use Zenstruck\Foundry\Attribute\ResetDatabase;
use Zenstruck\Messenger\Test\InteractsWithMessenger;

#[ResetDatabase]
abstract class AbstractApiTestCase extends KernelTestCase
{
    use HasBrowser {
        browser as kernelBrowser;
    }
    use InteractsWithMessenger;

    protected function browser(array $options = [], array $server = []): TestBrowser
    {
        $browser = $this->kernelBrowser($options, $server);

        if (!$browser instanceof TestBrowser) {
            throw new \LogicException('KERNEL_BROWSER_CLASS doit désigner '.TestBrowser::class.'.');
        }

        $browser->setDefaultHttpOptions(
            HttpOptions::create()->withHeader('Accept', 'application/ld+json'),
        );

        return $browser;
    }
}
// libs/app-test/src/TestBrowser.php
namespace AppTest;

use Zenstruck\Browser\KernelBrowser;

class TestBrowser extends KernelBrowser
{
    // Remplace un service du conteneur de test, typiquement par un mock.
    public function addMock(string $id, object $service): self
    {
        $this->client()->getContainer()->set($id, $service);

        return $this;
    }
}

Zenstruck Browser instancie la classe que nomme KERNEL_BROWSER_CLASS. Chaque service la déclare dans sa configuration PHPUnit, avec les trois extensions :

<!-- phpunit.dist.xml (service order), extrait -->
<php>
    <server name="KERNEL_BROWSER_CLASS" value="AppTest\TestBrowser"/>
</php>
<extensions>
    <bootstrap class="DAMA\DoctrineTestBundle\PHPUnit\PHPUnitExtension"/>
    <bootstrap class="Zenstruck\Browser\Test\BrowserExtension"/>
    <bootstrap class="Zenstruck\Foundry\PHPUnit\FoundryExtension"/>
</extensions>

Depuis Foundry 2.9, les traits Factories et ResetDatabase sont dépréciés au profit de l'extension PHPUnit, et Foundry 3 les retirera. L'attribut #[ResetDatabase] posé sur la classe de base est hérité par toutes les classes qui l'étendent. Nous le préférons au paramètre enabled-auto-reset, qui viserait tout KernelTestCase depuis la configuration de chaque service.

Avec DAMA DoctrineTestBundle, Foundry ne recrée le schéma qu'avant le premier test. Chaque test tourne ensuite dans une transaction annulée à sa fin.

Les tests des services étendent AbstractApiTestCase. Une correction de cette classe est une modification de app-test : moon relance les tests des trois services dans la même pull request.

7. Variante : un dépôt partagé pour les images Docker

Si l'image d'un service se construit avec son seul dossier pour contexte, les liens vers app-contracts/ et libs/ n'y mènent nulle part. Le plugin propose alors un dépôt unique (pathRepositoryUrl), où une tâche copie les bibliothèques avant le build, sans lien (pathRepositorySymlink: false). En local, une modification n'atteint plus vendor/ qu'après composer reinstall app/test.

Checklist

  • Chaque bibliothèque interne déclarée dans dependsOn, jamais à la main dans composer.json.
  • scope: development pour les bibliothèques de test.
  • Le plugin épinglé sur une release, par URL directe ou en file://.
  • project://^ dans les entrées des tâches des services.
  • composer update <paquet> après chaque synchronisation qui modifie un manifeste.
  • En CI : moon sync projects, puis git diff --exit-code, et composer validate.
  • Un moon sync projects relu après chaque montée de version de moon.
  • Les classes de base des tests dans une bibliothèque, #[ResetDatabase] sur la classe de base.

Sources

Versions relevées le 15 novembre 2026 : moon 2.6.5, Composer 2.11.2, moon-composer-toolchain 0.1.0, Foundry 2.16.0, DAMA DoctrineTestBundle 8.8.0 et Zenstruck Browser 1.14.0.