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 dependsOn with require and require-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.json is 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.json ignores dependencies that are not packages, such as a shared Dockerfile. Part of dependsOn is still written by hand.

Generate composer.json from moon.yml

  • What it solves: dependsOn becomes the only declaration. A moon toolchain plugin writes require, require-dev and the repositories, as moon's JavaScript toolchain syncs the package.json files.
  • What it costs: a WASM plugin to install, to pin and to follow on every moon upgrade. composer.lock is 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.

One declaration, in moon.yml: moon writes composer.json and picks the tests composer.json written by the sync require: app/contracts require-dev: app/test repositories: path one repository per library by hand composer.lock updated by Composer, not by the sync composer update app/test command printed by moon in a warning Project graph: what moon reruns moon.yml (order service) the only declaration dependsOn: - app-contracts - id: app-test scope: development sync composer toolchain (WASM) moon sync projects and before every task dependsOn app-test changed order stock shipping affected: tests rerun Without the sync: two declarations that drift Installed but outside the graph: changing app-test does not rerun the tests of shipping . Required but unused: the library stays installed, with its dependencies, and audited.

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:

  • production and peer go to require;
  • development goes to require-dev, as app-test does;
  • build is 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 in composer.json.
  • scope: development for 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, then git diff --exit-code, and composer validate.
  • A moon sync projects reviewed 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.