Weave Code
Monorepo Builder Laravel Package
symplify/monorepo-builder
Tools for PHP monorepos: discover packages, merge and propagate composer.json, validate dependency/version consistency, and automate releases. Configure via monorepo-builder.php and manage packages across /packages or custom directories.
Monorepo Builder (monorepo-php/monorepo) is a toolkit for managing PHP monorepos: it discovers packages, merges and validates composer.json data, and supports automated releases. Configuration lives in a single monorepo-builder.php, making it easy to keep many packages consistent while working from one repository.
Designed for PHP 8.2+, it provides practical commands and composable config options for real-world monorepo workflows.
- Merge package
composer.jsonsections into the root (preserving key order) - Propagate root settings back to packages (reverse of merge)
- Configure package directories and excludes
- Append/remove arbitrary composer.json data after merging
- Automate and validate versioning and release processes
Frequently asked questions about Monorepo Builder
- How do I set up Monorepo Builder for a Laravel project with multiple packages?
- Start by installing the package via `composer require monorepo-php/monorepo --dev`, then initialize the config with `vendor/bin/monorepo-builder init`. Configure package directories and exclusions in `monorepo-builder.php` to match your Laravel project structure, such as `/packages` or custom paths.
- Can Monorepo Builder handle Laravel-specific composer.json sections like `extra.laravel` or `autoload-dev`?
- Yes, it preserves custom sections by default. To ensure Laravel-specific sections like `extra.laravel` or `scripts` remain intact, use `composerSectionOrder` in your config or leverage `dataToAppend` to explicitly include them after merging.
- How do I enforce consistent Laravel framework versions across all packages in the monorepo?
- Use the `validate` command to check for version conflicts. For stricter control, combine it with `bump-interdependency` in your config to enforce exact or range-based versions (e.g., `^10.0.0`) for `laravel/framework` across all packages.
- What’s the best way to integrate Monorepo Builder into a Laravel CI/CD pipeline?
- Sequence commands like `merge`, `validate`, and `release` in your pipeline. For example, run `merge` to combine package dependencies, then `validate` to catch conflicts before releasing. Use `localize-composer-paths` to test Laravel plugins in isolation if needed.
- Does Monorepo Builder support Laravel’s semantic versioning (e.g., v1.0.0) for automated releases?
- Yes, the `release` command works with Laravel’s versioning. Extend it with custom workers (e.g., `UpdateBranchAliasReleaseWorker`) to handle Laravel-specific tasks like updating `composer.json` branch aliases or running `php artisan optimize` post-release.
- How do I exclude certain Laravel packages (e.g., a secret or legacy package) from the monorepo build?
- Use the `packageDirectoriesExcludes` config option in `monorepo-builder.php` to specify paths or glob patterns for packages you want to exclude, such as `__DIR__ . '/packages/secret-package'`.
- Will Monorepo Builder work with Laravel 10/11 projects running PHP 8.1?
- No, the package requires PHP 8.2+. For PHP 8.1, use version `^11.2` of `symplify/monorepo-builder`, but note it’s no longer maintained. Laravel 10/11 officially support PHP 8.1+, so upgrading PHP is recommended for long-term compatibility.
- How can I append or modify Laravel-specific scripts (e.g., `post-autoload-dump`) after merging composer.json files?
- Use the `dataToAppend` config option to add or override sections like `scripts`. For example, append `post-autoload-dump` under `scripts` to ensure Laravel’s autoloader is regenerated post-merge. Test thoroughly to avoid conflicts with existing scripts.
- What’s the difference between `merge` and `propagate` commands in a Laravel monorepo context?
- `merge` combines all package `composer.json` sections into the root file, preserving the root’s key order. `propagate` does the reverse: it pushes root-level configurations (e.g., global dev dependencies) back to individual packages. Use `merge` for dependency consolidation and `propagate` for enforcing root-level rules.
- How do I handle shared dev dependencies (e.g., `phpunit/phpunit`) between Laravel packages and the root?
- Configure `require-dev` in the root `composer.json` and use `propagate` to push these dependencies to packages. For stricter control, use `dataToAppend` to explicitly define shared dev dependencies in package-level `composer.json` files after merging.
Weaver
How can I help you explore Laravel packages today?