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àrequireetrequire-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.jsonpour 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.jsonignore les dépendances qui ne sont pas des paquets, comme un Dockerfile partagé. Une partie dedependsOnreste donc écrite à la main.
Générer composer.json depuis
moon.yml
-
Ce qu'elle règle :
dependsOndevient la seule déclaration. Un plugin de toolchain moon écritrequire,require-devet les dépôts, comme la toolchain JavaScript de moon synchronise lespackage.json. -
Ce qu'elle coûte : un plugin WASM à
installer, à épingler et à suivre à chaque montée de
version de moon.
composer.lockreste à 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.
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 :
-
productionetpeervont dansrequire; -
developmentva dansrequire-dev: c'est le cas deapp-test; -
buildest 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 danscomposer.json. -
scope: developmentpour 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, puisgit diff --exit-code, etcomposer validate. -
Un
moon sync projectsrelu 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.
- moon, langages pris en charge : PHP au niveau 1, sans inférence de dépendances.
- moon, graphe des projets : dépendances implicites et scopes.
-
moon,
configuration de projet :
dependsOn,scopeet entréesproject://. -
moon,
toolchains
(
plugin) et plugins WASM : locatorsfile://,github://ethttps://,GITHUB_TOKEN, API expérimentale. - moon, sync projects et action Sync project ; son code : l'avertissement en CI.
- moon, tâches héritées et conditions d'héritage.
-
moon,
schéma des toolchains :
syncProjectWorkspaceDependenciesde la toolchain JavaScript ; versions publiées. - moon-composer-toolchain : règles de synchronisation, réglages et release 0.1.0.
-
Composer,
dépôts path :
symlink,versionset référence ; dépôts lus dans le paquet racine. - Composer, validate et reinstall ; paquets privés : Private Packagist et Satis.
-
Foundry,
documentation : extension PHPUnit,
#[ResetDatabase],enabled-auto-reset, DAMA ; UPGRADE-2.9. -
DAMA DoctrineTestBundle,
Zenstruck Browser
(
KERNEL_BROWSER_CLASS) et Zenstruck Messenger Test. - Lychen, pull request 273 : une mise en œuvre open source de la synchronisation décrite ici, dans un monorepo moon.
- Lychen, pull requests 235 et 241 : la bibliothèque de test partagée et l'extension PHPUnit de Foundry, dans le même monorepo.