The problem
Our online shop lives in a monorepo driven by moon. The
Symfony services order, stock and
shipping share two internal libraries:
app-contracts for the message contracts,
app-test for the tests.
Each library is declared twice there. The
dependsOn of moon.yml puts the
service in the project graph, from which moon works out the
task order and the affected projects. The
composer.json installs it: an entry in
require or require-dev, and a
path repository that tells Composer where to
find it.
Nothing links these two declarations. moon infers
dependencies from a package.json, but for PHP
it only categorises projects and does not read
composer.json. The two lists drift, in both
directions.
A dependency installed, but missing from the
graph.
shipping requires app/test in its
composer.json, but its
moon.yml does not list app-test. A
pull request that changes the base test class does not rerun
the tests of shipping. The breakage shows up
later, in a pull request that has nothing to do with it.
A dependency required, but unused. A
service no longer uses a library, and its
moon.yml no longer lists it. Its
composer.json still requires it: the library
stays installed with its own dependencies, and their
vulnerabilities show up in the service's audit.
Repositories to copy around. Composer only
reads repositories from the root composer.json,
never from those of the dependencies. If
app/test required app/contracts,
every service would have to declare the
app/contracts repository, even without
requiring it.
A test library born from copies
Before app-test, each service had its own copy
of the test browser and of the base class of its functional
tests. The copies had drifted: only
order reloaded the authenticated user and could
replace a service with a mock, only stock had
the PHPStan annotations.
Grouping these classes in a library ends the drift. But it adds one more internal dependency, declared in two places.
The options
Declare in both places, and check in CI
-
What it solves: the tooling does not
change. A script compares
dependsOnwithrequireandrequire-dev, and fails the CI on any difference. - What it costs: two edits for every dependency, and a script that must know the scopes, the repositories and the transitive dependencies. It reports the gap without fixing it.
Generate moon.yml from
composer.json
-
What it solves: Composer stays the
reference, as
package.jsonis for the implicit dependencies of JavaScript projects. -
What it costs: moon infers nothing for
PHP, so a plugin has to extend the project graph. And
composer.jsonignores dependencies that are not packages, such as a shared Dockerfile. Part ofdependsOnis still written by hand.
Generate composer.json from
moon.yml
-
What it solves:
dependsOnbecomes the only declaration. A moon toolchain plugin writesrequire,require-devand the repositories, as moon's JavaScript toolchain syncs thepackage.jsonfiles. -
What it costs: a WASM plugin to install,
to pin and to follow on every moon upgrade.
composer.lockis still updated with Composer.
One repository per library, published to a private registry
- What it solves: each library has real versions, published on Private Packagist or a Satis repository. Each service upgrades at its own pace.
- What it costs: changing a library and its services takes several pull requests and a release. The libraries leave the monorepo's graph, and a service is no longer tested against their latest version.
Our recommendation
An internal dependency is declared in
moon.yml, and only there. A moon toolchain
plugin writes the Composer side.
The project graph already decides what to test, as in our article on CI pipelines driven by moon. Making it the only declaration removes the gap, instead of detecting it. Composer keeps what it does well: resolving versions and writing the lock.
The scope picks the section
An entry of dependsOn has a scope:
production by default,
development, build or
peer. moon uses scopes to sync projects, and
the plugin applies them to Composer:
-
productionandpeergo torequire; -
developmentgoes torequire-dev, asapp-testdoes; -
buildis ignored, as Composer has no equivalent.
Removing an entry from dependsOn removes the
package from require, from
require-dev and from the repositories. A
library required only by another one gets its repository,
without entering require: no repository is left
to copy around. Only the monorepo's packages are managed:
symfony/console and the constraints already
written are left alone.
The lock stays with Composer
The plugin edits manifests; it runs neither PHP nor
Composer. When a composer.json changes, moon
logs a warning with the command to run:
composer update followed by the changed
packages. Naming the packages matters: a
composer update without arguments would upgrade
every dependency of the service.
Tasks affected by their dependencies
dependsOn links the projects, but it is a
task's inputs that make it affected. The
project://^ input stands for every project of
dependsOn, whatever its scope. A change to
app-test therefore reruns the tests of
order, stock and
shipping.
The trade-offs we accept
A plugin outside moon. moon has no official
PHP toolchain: the plugin is a third-party WASM file. moon
warns that its plugin API is experimental and may break in
non-major releases. After every moon upgrade, we run
moon sync projects and read the diff.
A lock updated by hand. The sync only
writes composer.json. In CI,
composer validate fails when
composer.lock is no longer up to date with it.
Files changed by moon run. The
sync runs before every task. Adding a line to
dependsOn, then running the tests, therefore
changes composer.json: this is intended, and
the diff goes into the same pull request.
One more download. The
github:// locator calls the GitHub API, which
is rate limited: moon then recommends a
GITHUB_TOKEN in CI. We pin the direct URL of a
release asset instead, downloaded without any API call. To
depend on no host at all, the .wasm can also be
committed to the repository and loaded with
file://.
Placeholder versions. The monorepo's
packages all have the version 0.0.0 and the
constraint *: they evolve with their services,
in the same commits.
The signal that should make us revisit this choice: a library consumed outside the monorepo, with its own versions. The private registry then becomes the right option for it again.
Implementation
The examples use moon 2.6, Composer 2.11, PHP 8.4, Symfony 7.4, Foundry 2.16 and DAMA DoctrineTestBundle 8. The plugin is moon-composer-toolchain 0.1.0, released under the MIT licence.
1. Enable the 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
The toolchain applies to language: php projects
and to any project that has a composer.json.
Without pathRepositoryUrl, each library gets
its own path repository, pointing to its
folder.
2. Declare the dependencies in moon.yml
The test library is a moon project like any other. Its
composer.json, in libs/app-test/,
holds the package name and its own dependencies:
// 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"
}
}
Each service declares its libraries in
dependsOn, and nowhere else:
# services/order/moon.yml (excerpt)
language: php
layer: application
stack: backend
tags: [symfony, docker]
dependsOn:
- app-contracts
- id: app-test
scope: development
stock and shipping declare the
same ones. The plugin reads the package name from the
dependency's composer.json. A project without a
composer.json, such as a frontend or a shared
Dockerfile, is ignored.
3. Let the sync write composer.json
moon sync projects syncs every project, and
moon run does it before every task. In
services/order/composer.json, the plugin writes
these keys and keeps the rest, indentation and key order
included:
// services/order/composer.json (excerpt)
{
"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 gives the libraries a stable version.
Without it, Composer gives them a development version: the
one of the git branch, or dev-master as a
fallback. The * constraint rejects it under the
default minimum stability.
The plugin writes *, where
our article on message contracts
wrote *@dev: with 0.0.0,
@dev is no longer needed.
What is left is updating the lock, with the command moon prints:
# services/order
composer update app/test
The reference of a path package in the lock is
a hash of its composer.json and of the
repository options. A library's folder holds no git
repository of its own: changing its code therefore does not
change the services' locks.
4. Tie the tests to the graph
The services inherit test from
.moon/tasks/symfony.yml, with
project://^ as an implicit input, as in
our article on task inheritance. We add one task to it, run like audit from
the Composer image:
# .moon/tasks/symfony.yml (excerpt)
tasks:
composer-validate:
command: docker run --rm --volume $projectRoot:/app composer:2.11 validate --no-check-publish
inputs: [composer.json, composer.lock]
validate does not need to read the
path repositories, outside the mounted folder.
5. Fail the CI on an unsynced manifest
In CI, moon already reports a sync that changes files, but
only with a warning. We turn it into a failure in the
checks job of qg.yml, whose matrix
also gets :composer-validate:
# .github/workflows/qg.yml (excerpt of the checks job)
strategy:
matrix:
tasks: [':lint', ':format', ':audit :composer-validate', ':test', ':build :docker-build']
steps:
# ... checkout, toolchain and buildx unchanged
- name: Synced manifests
run: |
moon sync projects
git diff --exit-code
- run: moon ci ${{ matrix.tasks }}
A library added by hand to composer.json, with
its repository, but missing from dependsOn, is
removed by the sync. The resulting diff fails the job.
6. Share the base test classes
The base class groups what the services' tests share: database reset, Messenger test transports and the browser.
// 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 must name '.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
{
// Replaces a service of the test container, typically with a mock.
public function addMock(string $id, object $service): self
{
$this->client()->getContainer()->set($id, $service);
return $this;
}
}
Zenstruck Browser instantiates the class that
KERNEL_BROWSER_CLASS names. Each service sets
it in its PHPUnit configuration, along with the three
extensions:
<!-- phpunit.dist.xml (order service), excerpt -->
<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>
Since Foundry 2.9, the Factories and
ResetDatabase traits are deprecated in favour
of the PHPUnit extension, and Foundry 3 will remove them.
The #[ResetDatabase] attribute set on the base
class is inherited by every class that extends it. We prefer
it to the enabled-auto-reset parameter, which
would target every KernelTestCase from each
service's configuration.
With DAMA DoctrineTestBundle, Foundry only recreates the schema before the first test. Each test then runs in a transaction rolled back at its end.
The services' tests extend AbstractApiTestCase.
A fix to this class is a change to app-test:
moon reruns the tests of the three services in the same pull
request.
7. Variant: a shared repository for Docker images
If a service's image is built with its own folder as the
only context, links to app-contracts/ and
libs/ lead nowhere inside it. The plugin then
offers a single repository (pathRepositoryUrl),
where a task copies the libraries before the build, without
links (pathRepositorySymlink: false). Locally,
a change then only reaches vendor/ after
composer reinstall app/test.
Checklist
-
Each internal library declared in
dependsOn, never by hand incomposer.json. -
scope: developmentfor test libraries. -
The plugin pinned to a release, through a direct URL or
with
file://. -
project://^in the inputs of the services' tasks. -
composer update <package>after every sync that changes a manifest. -
In CI:
moon sync projects, thengit diff --exit-code, andcomposer validate. -
A
moon sync projectsreviewed after every moon upgrade. -
The base test classes in a library, with
#[ResetDatabase]on the base class.
Sources
Versions checked on 15 November 2026: moon 2.6.5, Composer 2.11.2, moon-composer-toolchain 0.1.0, Foundry 2.16.0, DAMA DoctrineTestBundle 8.8.0 and Zenstruck Browser 1.14.0.
- moon, supported languages: PHP at tier 1, without dependency inference.
- moon, project graph: implicit dependencies and scopes.
-
moon,
project configuration:
dependsOn,scopeandproject://inputs. -
moon,
toolchains
(
plugin) and WASM plugins:file://,github://andhttps://locators,GITHUB_TOKEN, experimental API. - moon, sync projects and Sync project action; its code: the warning in CI.
- moon, inherited tasks and inheritance conditions.
-
moon,
toolchains schema:
syncProjectWorkspaceDependenciesof the JavaScript toolchain; releases. - moon-composer-toolchain: sync rules, settings and release 0.1.0.
-
Composer,
path repositories:
symlink,versionsand reference; repositories read from the root package. - Composer, validate and reinstall; private packages: Private Packagist and Satis.
-
Foundry,
documentation: PHPUnit extension,
#[ResetDatabase],enabled-auto-reset, DAMA; UPGRADE-2.9. -
DAMA DoctrineTestBundle,
Zenstruck Browser
(
KERNEL_BROWSER_CLASS) and Zenstruck Messenger Test. - Lychen, pull request 273: an open-source implementation of the sync this article describes, in a moon monorepo.
- Lychen, pull requests 235 and 241: the shared test library and Foundry's PHPUnit extension, in the same monorepo.