Weave Code
Monorepo Builder Laravel Package
symplify/monorepo-builder
Toolkit for managing PHP monorepos: merge package composer.json files into the root, validate dependency versions, bump interdependencies, propagate versions back, manage package aliases, and automate releases. Configured via monorepo-builder.php; requires PHP 8.2+.
Not only Composer tools to build a Monorepo.
Frequently asked questions about Monorepo Builder
- Is symplify/monorepo-builder a Laravel package?
- No. symplify/monorepo-builder is framework-agnostic Composer tooling for PHP monorepos. It ships no Laravel service provider, publishable config, Artisan commands, or facade, and it runs as vendor/bin/monorepo-builder from the repository root against a monorepo-builder.php file. In a Laravel monorepo it lives beside your apps and packages without coupling to the framework.
- How do I install monorepo-builder in a Laravel monorepo?
- Install it as a dev-only dependency with composer require --dev, then place monorepo-builder.php at the repository root. PHP 8.2 or newer is required. The README currently shows monorepo-php/monorepo as the install name, so confirm the canonical Packagist package name before pinning it. After install, run vendor/bin/monorepo-builder validate in read-only mode to confirm package discovery.
- Does monorepo-builder support Laravel 11 and Laravel 12?
- The tool itself has no Laravel version gate; its PHP 8.2+ requirement lines up with Laravel 11 and Laravel 12 stacks. Laravel 9 and 10 projects still on PHP 8.0 or 8.1 are excluded, and the legacy ^11.2 line that supports PHP 8.1 is explicitly unmaintained. Because it is framework-independent, Laravel upgrades do not affect the tool itself.
- Why do path repositories break after merging composer.json in monorepo-builder?
- The default merge writes replace entries at self.version for every internal package, which short-circuits Composer's symlink install for path-repository consumers. Laravel apps that require internal libraries through path repositories are exactly the case that can break. Use disablePackageReplace() and, where appropriate, selective disableAutoloadMerge() as the documented escape hatch. Make that configuration decision before rollout, not during an incident.
- Why does PHPUnit stop finding package tests after monorepo-builder merge?
- Composer treats autoload-dev as root-only, and path-repository dependencies never register their dev autoload. If AutoloadDev is not folded during merge, root-level PHPUnit can silently stop discovering library test classes. That failure often appears only in CI, so verify test discovery after changing merge settings. Configure autoload-dev handling deliberately and keep a smoke test.
- What is the difference between merge and propagate in monorepo-builder?
- merge folds every package composer.json into the root composer.json so root-level PHPUnit, PHPStan, and Pint can resolve all namespaces. propagate runs in the opposite direction, pushing versions from the root composer.json back to each package. Use merge for a unified root manifest and propagate to keep package manifests in sync. Both commands rewrite Composer files, so review the diff.
- Should monorepo-builder release run automatically in CI?
- release mutates git state: it bumps interdependencies, creates tags, pushes tags, and pushes next dev versions. Treat that as a governance decision as much as a technical one. Gate it behind protected-branch policy and, ideally, manual approval in CI. Avoid letting developers run it ad hoc from a workstation.
- Is monorepo-builder safe for production Laravel apps?
- It is a dev-only dependency with no runtime footprint and no autoload surface in deployed artifacts. The worst realistic failure is broken local or CI tooling rather than a broken Laravel application, which caps the blast radius. It is MIT licensed and clean for commercial use. Still gate destructive commands such as merge and release.
- How do I validate dependency versions across packages with monorepo-builder?
- Run vendor/bin/monorepo-builder validate from the repository root. It checks that all packages use the same version for shared dependencies and is usable immediately in read-only mode with no config beyond package discovery. Add it to CI so version drift across packages is caught before merge. Without that gate, drift can stay silent.
- Is monorepo-php/monorepo the same package as symplify/monorepo-builder?
- The package name question is worth resolving first: the README install command references monorepo-php/monorepo while the package under evaluation is symplify/monorepo-builder. That suggests a rename or namespace migration in flight, so verify the canonical name and Packagist ownership before the first install. Also plan for maintenance concentration, since the project has a single-vendor origin and thin external validation. For dev tooling it may be acceptable, but assume you might need to fork or replace it within 12 to 24 months.
Weaver
How can I help you explore Laravel packages today?