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

Command	Description
vendor/bin/monorepo-builder merge	Merge all package composer.json into root
vendor/bin/monorepo-builder validate	Check that inter-package versions are consistent
vendor/bin/monorepo-builder propagate	Push root dependency versions back into package composer.json files
vendor/bin/monorepo-builder bump-interdependency <version>	Update mutual package constraints to one target version
vendor/bin/monorepo-builder package-alias	Update branch-alias across package composer.json files
vendor/bin/monorepo-builder localize-composer-paths	Swap mutual package paths to local paths for pre-split testing
vendor/bin/monorepo-builder release <version>	Tag and release a new version across all packages
vendor/bin/monorepo-builder init	Scaffold a new monorepo structure

---

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

#	Summary
#90	[Feature] Conventional Commit release support
#77	SetNextMutualDependenciesReleaseWorker always updates minor version
#76	No helper to import autoloader regardless of monorepo depth
#72	Incompatible declaration in EventDispatcher.php
#69	Composer install behaviour question
#59	Packages with tests in name are always ignored
#25	Interdependency version update fails for pre-release versions

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

Version	Date	Highlights
12.5.2	2026-03-26	Allow sebastian/diff ^8 (#110)
12.5.0	2026-02-13	Preserve custom composer.json sections; arbitrary dataToAppend keys

See references/releases.md for full release notes.

---

Reference Files

File	Contents	Confidence
references/README.md	Full README: install, commands, configuration options, usage examples	Medium
references/releases.md	Release notes for all tagged versions (2 releases)	Medium
references/issues.md	All 34 GitHub issues — 7 open, 27 closed — with labels and dates	Medium
references/file_structure.md	Repository directory tree (813 items)	Medium

---

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