PHPackages                             symplify/monorepo-builder - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. symplify/monorepo-builder

ActiveLibrary[Utility & Helpers](/categories/utility)

symplify/monorepo-builder
=========================

Not only Composer tools to build a Monorepo.

12.7.1(1mo ago)5275.9M↓19.1%46[7 issues](https://github.com/symplify/monorepo-builder/issues)20MITPHPPHP >=8.2CI failing

Since Jun 10Pushed 1mo ago11 watchersCompare

[ Source](https://github.com/symplify/monorepo-builder)[ Packagist](https://packagist.org/packages/symplify/monorepo-builder)[ Fund](https://www.paypal.me/rectorphp)[ GitHub Sponsors](https://github.com/tomasvotruba)[ RSS](/packages/symplify-monorepo-builder/feed)WikiDiscussions main Synced 3d ago

READMEChangelog (4)Dependencies (69)Versions (572)Used By (20)

Monorepo Builder
================

[](#monorepo-builder)

[![Downloads total](https://camo.githubusercontent.com/5dc91e0266e06abd90ccd8d84e1ca0a118271d7967e642df54cc620f4f45580a/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f73796d706c6966792f6d6f6e6f7265706f2d6275696c6465722e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/symplify/monorepo-builder)

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

Install
-------

[](#install)

```
composer require monorepo-php/monorepo --dev
```

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

Quick Start
-----------

[](#quick-start)

```
# 1. Scaffold a basic monorepo layout (one time)
vendor/bin/monorepo-builder init

# 2. Fold every package's composer.json into the root composer.json
vendor/bin/monorepo-builder merge

# 3. Cut a release when you're ready
vendor/bin/monorepo-builder release v1.0
```

All configuration goes in `monorepo-builder.php` at your project root. See [Configuration](#configuration) for the full list of options.

Commands
--------

[](#commands)

### init

[](#init)

Generates a basic monorepo skeleton (a `packages/` directory and a starter `monorepo-builder.php`) so you can start adding packages immediately:

```
vendor/bin/monorepo-builder init
```

Run once at the start of a new monorepo. Existing files are not overwritten.

### merge

[](#merge)

Merges all sections from package `composer.json` files into the root `composer.json`. For the reverse direction, see [`propagate`](#propagate).

```
vendor/bin/monorepo-builder merge
```

**Behavior:**

- All sections are merged, including standard (`require`, `autoload`, etc.) and custom ones (`scripts-aliases`, `abandoned`, etc.)
- If a package appears in both `require` and `require-dev`, the `require` entry takes priority
- The original key order of the root `composer.json` is preserved; new sections are appended at the end

To customize what gets merged (append / remove data, reorder sections, skip autoload merging, etc.) see [Customizing merge output](#customizing-merge-output).

### validate

[](#validate)

Checks that all packages use the same version for shared dependencies:

```
vendor/bin/monorepo-builder validate
```

### bump-interdependency

[](#bump-interdependency)

Updates mutual dependencies between packages to a given version:

```
vendor/bin/monorepo-builder bump-interdependency "^4.0"
```

### propagate

[](#propagate)

Propagates versions from root `composer.json` back to each package's `composer.json` (the reverse of [`merge`](#merge)):

```
vendor/bin/monorepo-builder propagate
```

### package-alias

[](#package-alias)

Updates the `branch-alias` in every package `composer.json` to match the current version:

```
vendor/bin/monorepo-builder package-alias
```

To customize the alias format string, see [Custom alias format](#custom-alias-format) under Configuration.

### localize-composer-paths

[](#localize-composer-paths)

Sets mutual package paths to local packages for pre-split testing:

```
vendor/bin/monorepo-builder localize-composer-paths
```

### release

[](#release)

Automates the release process: bumping dependencies, tagging, pushing, and updating changelogs.

```
vendor/bin/monorepo-builder release v7.0
```

Preview what will happen without making changes:

```
vendor/bin/monorepo-builder release v7.0 --dry-run
```

Release by semver level (`patch`, `minor`, or `major`):

```
# current v0.7.1 → v0.7.2
vendor/bin/monorepo-builder release patch
```

The default pipeline runs `TagVersionReleaseWorker` followed by `PushTagReleaseWorker`. To customize the pipeline (add workers, reorder, disable defaults, enable LTS-aware tag resolution), see [Customizing the release pipeline](#customizing-the-release-pipeline).

Configuration
-------------

[](#configuration)

All configuration lives in `monorepo-builder.php` at your project root. Every option below is set on the `MBConfig` instance passed into the configurator closure:

```
use Symplify\MonorepoBuilder\Config\MBConfig;

return static function (MBConfig $mbConfig): void {
    // your configuration here
};
```

### Package discovery

[](#package-discovery)

By default, packages are discovered from `./packages`. To customize:

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

    // exclude specific packages
    $mbConfig->packageDirectoriesExcludes([__DIR__ . '/packages/secret-package']);
};
```

### Customizing merge output

[](#customizing-merge-output)

These options shape what `vendor/bin/monorepo-builder merge` writes into the root `composer.json`.

#### Append / remove data after merge

[](#append--remove-data-after-merge)

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

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

    // remove data after merge
    $mbConfig->dataToRemove([
        ComposerJsonSection::REQUIRE => [
            // removed by key, version is irrelevant
            'phpunit/phpunit' => '*',
        ],
        ComposerJsonSection::REPOSITORIES => [
            Option::REMOVE_COMPLETELY,
        ],
    ]);
};
```

#### Section ordering

[](#section-ordering)

By default, the original key order of root `composer.json` is preserved. To enforce a specific order:

```
use Symplify\MonorepoBuilder\Config\MBConfig;
use Symplify\MonorepoBuilder\Merge\JsonSchema;

return static function (MBConfig $mbConfig): void {
    $mbConfig->composerSectionOrder(JsonSchema::getProperties());
};
```

#### Skip autoload merging for selected packages

[](#skip-autoload-merging-for-selected-packages)

By default, every internal package's `autoload` and `autoload-dev` PSR-4 entries are folded into the root `composer.json` so that `vendor/bin/phpunit` and other root-level tooling can resolve every namespace. The three scenarios below cover when you'd want to skip part or all of that merging — pick the one that matches your monorepo:

**Scenario 1 — Default monorepo of libraries.** No skip needed. The root `composer.json` `autoload` aggregates every internal library's PSR-4 mapping, so any namespace resolves from the root vendor.

**Scenario 2 — Mixed monorepo with libraries symlinked + apps not required from root.** When [`disablePackageReplace()`](#skip-the-package-replace-section) is on (libraries are real path-repo deps, Composer symlinks them into `vendor/`), the libraries' `autoload` is registered automatically by Composer via `vendor/composer/autoload_psr4.php`. Folding them into the root `composer.json` would duplicate that registration. Skip autoload merging for libraries only — apps' autoload still merges so root-level scripts can find them:

```
use Symplify\MonorepoBuilder\Config\AutoloadSection;
use Symplify\MonorepoBuilder\Config\MBConfig;
use Symplify\MonorepoBuilder\Config\PackageType;

return static function (MBConfig $mbConfig): void {
    $mbConfig->disablePackageReplace();
    $mbConfig->disableAutoloadMerge(
        sections: [AutoloadSection::Autoload],
        forTypes: [PackageType::Library],
    );
};
```

Result: root `autoload` contains apps' PSR-4 entries but NOT libraries'. Root `autoload-dev` still aggregates everything (see "Why autoload-dev is independent" below).

**Scenario 3 — Custom merge.** To turn off both sections entirely (you handle merging yourself, e.g. via a custom decorator):

```
use Symplify\MonorepoBuilder\Config\AutoloadSection;
use Symplify\MonorepoBuilder\Config\MBConfig;

return static function (MBConfig $mbConfig): void {
    $mbConfig->disableAutoloadMerge(
        sections: [AutoloadSection::Autoload, AutoloadSection::AutoloadDev],
        forTypes: [],
    );
};
```

Result: root `autoload` and `autoload-dev` are untouched by `monorepo-builder merge`.

**API reference:**

- `disableAutoloadMerge(array $sections, array $forTypes)` — both arguments are required.
    - `$sections`: a non-empty list of `AutoloadSection` cases (`Autoload`, `AutoloadDev`).
    - `$forTypes`: a list of composer.json `type` filter values. **Each element may be either a `PackageType` enum case (preferred for the four [Composer schema](https://getcomposer.org/doc/04-schema.md#type) types: `Library`, `Project`, `Metapackage`, `ComposerPlugin`) or a non-empty string (escape hatch for ecosystem types defined by `composer/installers` such as `'wordpress-plugin'`, `'drupal-module'`, `'symfony-bundle'`, and for user-defined custom types).** Mixing enum cases and strings in the same call is allowed; multiple types are OR-matched. The two filter channels are intentionally distinct: pass an **empty array** (`forTypes: []`) to skip every package regardless of type, OR pass a non-empty list of types to skip ONLY packages whose `composer.json` declares the matching `type` literally. Composer's "missing `type` defaults to library" rule does NOT extend the filter — a package without an explicit `type` field is NOT swept up by `forTypes: [PackageType::Library]`. If you want the filter to catch an untyped package, declare `type: library` (or whichever) in that package's `composer.json`.
- Repeated calls follow last-call-wins semantics PER section. Calls touching different sections compose; calls touching the same section override.

**Migrating from the previous binary API:** The earlier zero-argument form `$mbConfig->disableAutoloadMerge();` continues to work but is deprecated and emits an `E_USER_DEPRECATED` notice. It maps to the full-kill behavior — equivalent to `disableAutoloadMerge(sections: [AutoloadSection::Autoload, AutoloadSection::AutoloadDev], forTypes: [])`. Update existing config files at your convenience. The legacy `MBConfig::isAutoloadMergeDisabled()` getter is also kept as a deprecated convenience that returns `true` only when both sections are configured to skip merging for all packages — prefer `MBConfig::shouldSkipAutoload($packageType)` and `MBConfig::shouldSkipAutoloadDev($packageType)` for new code.

##### Why autoload-dev is independent

[](#why-autoload-dev-is-independent)

Composer treats `autoload-dev` as a **root-only** section: dev autoload entries from path-repo dependencies are NEVER registered in the consumer's `vendor/composer/autoload_psr4.php`. (See [Composer schema docs — `autoload-dev`](https://getcomposer.org/doc/04-schema.md#autoload-dev).)

Practical consequence: if your CI runs `vendor/bin/phpunit` from the monorepo root and expects to discover library test classes, those test classes are reachable ONLY because `monorepo-builder merge` has folded each library's `autoload-dev` PSR-4 into the root `composer.json`. Skipping `AutoloadSection::AutoloadDev` from root merge therefore breaks cross-package PHPUnit discovery — skip it only when you're handling test discovery another way.

#### Skip the package-replace section

[](#skip-the-package-replace-section)

By default, `monorepo-builder merge` writes a `replace` section into the root `composer.json` listing every internal package at `self.version`. This is correct for monorepos that publish a single combined dependency surface — Composer then refuses to install any external copy of those packages.

Some monorepos do NOT want this:

- Apps that require their own internal libraries via `path` repositories and rely on Composer's symlink installation (the `replace` entry would short-circuit the symlink)
- Monorepos with mixed `type: library` packages and `type: project` apps where the apps need real installs of the libs

To skip writing the `replace` section entirely:

```
use Symplify\MonorepoBuilder\Config\MBConfig;

return static function (MBConfig $mbConfig): void {
    $mbConfig->disablePackageReplace();
};
```

This pairs naturally with [Scenario 2 of the autoload skip section](#skip-autoload-merging-for-selected-packages) above. With both opt-outs on, your `path`-repository-based libraries get symlink-installed by Composer and only your apps' autoload entries land in the root `composer.json`.

### Customizing the release pipeline

[](#customizing-the-release-pipeline)

These options shape what `vendor/bin/monorepo-builder release` does on each invocation.

#### Custom workers

[](#custom-workers)

`TagVersionReleaseWorker` and `PushTagReleaseWorker` are enabled by default. Add more workers or customize the order:

```
use Symplify\MonorepoBuilder\Config\MBConfig;
use Symplify\MonorepoBuilder\Release\ReleaseWorker\AddTagToChangelogReleaseWorker;
use Symplify\MonorepoBuilder\Release\ReleaseWorker\PushNextDevReleaseWorker;
use Symplify\MonorepoBuilder\Release\ReleaseWorker\PushTagReleaseWorker;
use Symplify\MonorepoBuilder\Release\ReleaseWorker\SetCurrentMutualDependenciesReleaseWorker;
use Symplify\MonorepoBuilder\Release\ReleaseWorker\SetNextMutualDependenciesReleaseWorker;
use Symplify\MonorepoBuilder\Release\ReleaseWorker\TagVersionReleaseWorker;
use Symplify\MonorepoBuilder\Release\ReleaseWorker\UpdateBranchAliasReleaseWorker;
use Symplify\MonorepoBuilder\Release\ReleaseWorker\UpdateReplaceReleaseWorker;

return static function (MBConfig $mbConfig): void {
    $mbConfig->workers([
        UpdateReplaceReleaseWorker::class,
        SetCurrentMutualDependenciesReleaseWorker::class,
        AddTagToChangelogReleaseWorker::class,
        TagVersionReleaseWorker::class,
        PushTagReleaseWorker::class,
        SetNextMutualDependenciesReleaseWorker::class,
        UpdateBranchAliasReleaseWorker::class,
        PushNextDevReleaseWorker::class,
    ]);
};
```

To disable the default workers (and define your pipeline from scratch):

```
return static function (MBConfig $mbConfig): void {
    $mbConfig->disableDefaultWorkers();
};
```

You can also add custom workers by implementing `ReleaseWorkerInterface`.

#### Branch-aware tag validation (LTS)

[](#branch-aware-tag-validation-lts)

If you maintain multiple version lines, the release command may reject older versions because it compares against the most recent tag globally. Enable branch-aware validation to compare only within the same major version:

```
use Symplify\MonorepoBuilder\Config\MBConfig;
use Symplify\MonorepoBuilder\Contract\Git\TagResolverInterface;
use Symplify\MonorepoBuilder\Git\BranchAwareTagResolver;

return static function (MBConfig $mbConfig): void {
    $services = $mbConfig->services();
    $services->set(BranchAwareTagResolver::class);
    $services->alias(TagResolverInterface::class, BranchAwareTagResolver::class);
};
```

#### Custom alias format

[](#custom-alias-format)

`vendor/bin/monorepo-builder package-alias` writes a `branch-alias` entry into every package `composer.json`. To override the format string used:

```
use Symplify\MonorepoBuilder\Config\MBConfig;

return static function (MBConfig $mbConfig): void {
    // default: ".-dev"
    $mbConfig->packageAliasFormat('..x-dev');
};
```

Package Splitting
-----------------

[](#package-splitting)

To split packages into separate repositories, use [symplify/github-action-monorepo-split](https://github.com/symplify/github-action-monorepo-split) with GitHub Actions.

###  Health Score

77

—

ExcellentBetter than 100% of packages

Maintenance90

Actively maintained with recent releases

Popularity66

Solid adoption and visibility

Community43

Growing community involvement

Maturity95

Battle-tested with a long release history

 Bus Factor1

Top contributor holds 93.1% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~5 days

Total

571

Last Release

45d ago

Major Versions

v7.3.18 → v8.0.0-beta12020-05-16

8.3.48 → 9.0.0-BETA12020-11-14

9.4.70 → 10.0.0-beta12021-11-02

10.3.3 → 11.0.12022-06-13

11.2.23 → 12.0.02025-08-06

PHP version history (9 changes)v4.4.2PHP ^7.1

v7.0.0PHP ^7.2

8.2.17PHP ^7.2|^8.0

8.3.0PHP >=7.2

9.0.0-rc1PHP >=7.3

v9.3.27PHP >=8.0

9.4.6PHP >=7.1

11.1.25PHP >=8.1

12.1.0PHP >=8.2

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/924196?v=4)[Tomas Votruba](/maintainers/TomasVotruba)[@TomasVotruba](https://github.com/TomasVotruba)

---

Top Contributors

[![actions-user](https://avatars.githubusercontent.com/u/65916846?v=4)](https://github.com/actions-user "actions-user (1715 commits)")[![kayw-geek](https://avatars.githubusercontent.com/u/29700073?v=4)](https://github.com/kayw-geek "kayw-geek (46 commits)")[![TomasVotruba](https://avatars.githubusercontent.com/u/924196?v=4)](https://github.com/TomasVotruba "TomasVotruba (35 commits)")[![samsonasik](https://avatars.githubusercontent.com/u/459648?v=4)](https://github.com/samsonasik "samsonasik (26 commits)")[![rector-bot](https://avatars.githubusercontent.com/u/291251500?v=4)](https://github.com/rector-bot "rector-bot (6 commits)")[![garrettw](https://avatars.githubusercontent.com/u/84885?v=4)](https://github.com/garrettw "garrettw (3 commits)")[![elliotbruneel](https://avatars.githubusercontent.com/u/37578863?v=4)](https://github.com/elliotbruneel "elliotbruneel (2 commits)")[![tchapuis](https://avatars.githubusercontent.com/u/15218089?v=4)](https://github.com/tchapuis "tchapuis (2 commits)")[![AntonEvers](https://avatars.githubusercontent.com/u/1489129?v=4)](https://github.com/AntonEvers "AntonEvers (2 commits)")[![georgique](https://avatars.githubusercontent.com/u/15987211?v=4)](https://github.com/georgique "georgique (1 commits)")[![elpadi](https://avatars.githubusercontent.com/u/1967321?v=4)](https://github.com/elpadi "elpadi (1 commits)")[![jdreesen](https://avatars.githubusercontent.com/u/424602?v=4)](https://github.com/jdreesen "jdreesen (1 commits)")[![RobinDev](https://avatars.githubusercontent.com/u/3944894?v=4)](https://github.com/RobinDev "RobinDev (1 commits)")[![tacman](https://avatars.githubusercontent.com/u/619585?v=4)](https://github.com/tacman "tacman (1 commits)")

---

Tags

composermonorepophp

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan, Rector

Code StyleECS

Type Coverage Yes

### Embed Badge

![Health badge](/badges/symplify-monorepo-builder/health.svg)

```
[![Health](https://phpackages.com/badges/symplify-monorepo-builder/health.svg)](https://phpackages.com/packages/symplify-monorepo-builder)
```

###  Alternatives

[drupal/core

Drupal is an open source content management platform powering millions of websites and applications.

21866.0M1.7k](/packages/drupal-core)[shopware/core

Shopware platform is the core for all Shopware ecommerce products.

585.6M574](/packages/shopware-core)[rector/rector-src

Instant Upgrade and Automated Refactoring of any PHP code

136406.3k14](/packages/rector-rector-src)[open-dxp/opendxp

Content & Product Management Framework (CMS/PIM)

9421.6k61](/packages/open-dxp-opendxp)[chameleon-system/chameleon-base

The Chameleon System core.

1028.6k5](/packages/chameleon-system-chameleon-base)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)