PHP Monorepo Builder

monorepo-builder

A set of tools for managing PHP monorepos: merging composer.json files, validating package versions, releasing with automation, and more.

Repository: symplify/monorepo-builder Package: monorepo-php/monorepo (via Packagist) Language: PHP 8.2+ License: MIT License Latest Release: 12.5.2 (2026-03-26)

When to Use This Skill

Use this skill when you need to:

• Set up a new PHP monorepo — scaffolding directory structure, initial monorepo-builder.php config
• Merge composer.json files — aggregate dependencies from all packages into the root composer.json
• Validate version consistency — ensure all inter-package dependencies use matching version constraints
• Automate releases — bump versions, tag releases, push tags across all packages in one command
• Manage package discovery — configure which directories are scanned for packages, and which to exclude
• Append or remove data after merge — add shared dev dependencies, remove per-package-only entries
• Troubleshoot merge issues — composer section ordering, dropped custom keys, readme property loss (fixed in 12.5.0)
• Configure release workers — customize the sequence of steps that run during a release

Quick Reference

Installation

composer require monorepo-php/monorepo --dev

Requires PHP 8.2+. For PHP 8.1, use symplify/monorepo-builder:^11.2 (no longer maintained).

Initialize a New Monorepo

vendor/bin/monorepo-builder init

Generates a basic monorepo structure and a starter monorepo-builder.php config at your project root.

Core Commands

Configuration: Package Directories

All configuration lives in monorepo-builder.php at the project root.

use Symplify\MonorepoBuilder\Config\MBConfig;

return static function (MBConfig $mbConfig): void {
    // Scan multiple directories for packages
    $mbConfig->packageDirectories([
        __DIR__ . '/packages',
        __DIR__ . '/projects',
    ]);

    // Exclude specific packages from discovery
    $mbConfig->packageDirectoriesExcludes([
        __DIR__ . '/packages/secret-package',
    ]);
};

Configuration: Merge — Append and Remove Data

use Symplify\MonorepoBuilder\ComposerJsonManipulator\ValueObject\ComposerJsonSection;
use Symplify\MonorepoBuilder\Config\MBConfig;
use Symplify\MonorepoBuilder\ValueObject\Option;

return static function (MBConfig $mbConfig): void {
    // Add data to root composer.json after merge
    $mbConfig->dataToAppend([
        ComposerJsonSection::AUTOLOAD_DEV => [
            'psr-4' => [
                'Symplify\Tests' => 'tests',
            ],
        ],
        ComposerJsonSection::REQUIRE_DEV => [
            'phpstan/phpstan' => '^2.1',
        ],
    ]);

    // Remove data from root composer.json after merge
    $mbConfig->dataToRemove([
        ComposerJsonSection::REQUIRE => [
            // Version is irrelevant — removed by key
            'phpunit/phpunit' => '*',
        ],
        ComposerJsonSection::REPOSITORIES => [
            Option::REMOVE_COMPLETELY,
        ],
    ]);
};

Note (12.5.0+): dataToAppend now supports arbitrary composer.json keys — no longer limited to 24 hardcoded sections.

Run a Merge

vendor/bin/monorepo-builder merge

Reads all composer.json files in discovered package directories and merges their dependencies into the root composer.json.

Release a New Version

vendor/bin/monorepo-builder release 1.2.0

Runs all configured release workers in sequence (bump versions, create tags, push, etc.).

Split Packages to Separate Repositories

Monorepo Builder does not handle package splitting itself. For split repos, pair it with symplify/github-action-monorepo-split in GitHub Actions.

Key Concepts

Package Discovery

By default, monorepo-builder scans ./packages for subdirectories containing a composer.json. You configure additional or alternative directories with packageDirectories(). Packages whose directory names contain tests may be excluded — see issue #59.

Merge Behaviour

The merge command aggregates require, require-dev, autoload, autoload-dev, and other sections from all discovered packages into the root composer.json. Since 12.5.0, custom/non-standard keys (e.g. scripts-aliases, abandoned, readme) are preserved during merge.

Release Workers

Release workers are discrete steps executed in sequence during a release. They can be customized or reordered. A known issue (#77) exists where SetNextMutualDependenciesReleaseWorker always increments the minor version — review worker ordering carefully.

Version Validation

The validate command checks that when package A depends on package B (both in the monorepo), the version constraint in A's composer.json matches the actual version of B. This prevents inter-package version drift.

Known Issues

Open Issues

Recently Fixed (12.5.0 — 2026-02-13)

• Merge now preserves unknown/custom composer.json sections — scripts-aliases, abandoned, readme, and any non-standard keys are no longer dropped (#105, #106, #71, #107)
• dataToAppend supports arbitrary composer.json keys — no longer limited to 24 hardcoded sections (#105)

Recent Releases

See references/releases.md for full release notes.

Reference Files

Working with This Skill

Beginner

1. Run vendor/bin/monorepo-builder init to scaffold your monorepo.
2. Add packages under packages/ (each with its own composer.json).
3. Run vendor/bin/monorepo-builder merge to sync dependencies into root.
4. Check references/README.md for full configuration options.

Intermediate

• Customize monorepo-builder.php to add multiple package directories and exclusions.
• Use dataToAppend to inject shared dev tooling (PHPStan, PHPUnit) into root composer.json.
• Use dataToRemove to strip per-package-only entries (e.g. local repositories) from the merged root.
• Run validate in CI to catch inter-package version drift early.
• Use propagate or bump-interdependency when root and package version constraints need to move together.

Advanced

• Configure and reorder release workers for custom release pipelines.
• Use Option::REMOVE_COMPLETELY to drop entire sections (e.g. repositories) after merge.
• Be aware of issue #77 when using SetNextMutualDependenciesReleaseWorker — it may bump the minor version unexpectedly.
• For pre-release versions (alpha/beta/RC), see issue #25 before relying on automatic interdependency updates.
• Use branch-aware tag validation if you maintain multiple active major version lines.

Source: GitHub repository symplify/monorepo-builder | Last updated: 2026-04-11