Monorepo Builder Laravel Package

Product Decisions This Supports

• Packaging architecture: one package vs. many. The core decision this unlocks is whether to ship a single Laravel package or split it into installable sub-packages (core, drivers, UI, testing helpers). The tool makes the split model viable without the usual version-skew tax, so the decision becomes a product question (surface area, install footprint, upgrade ergonomics) rather than a "we can't maintain that" engineering veto.
• Release cadence and version policy. release patch|minor|major with --dry-run makes a predictable release train a commitment you can actually keep, and validate enforces a single shared version of Laravel, PHP, PHPUnit, and PHPStan across every sub-package — i.e., an enforceable "supported Laravel versions" policy rather than a wiki page.
• Build vs. buy for release engineering. The alternative is hand-rolled Composer scripts or a heavier JS-ecosystem orchestrator. Under ~4 packages, custom scripts are cheaper. At 5–10+ interdependent packages, this is the buy.
• Roadmap sequencing / de-risking the split. Because merge keeps root-level tooling working while packages are still separate, you can ship as one package today and split incrementally later without a big-bang migration sprint.
• Developer experience as a shipped feature. One composer install, one CI pipeline, and root-level PHPUnit/PHPStan/Pint across all packages directly affect contributor onboarding time and review throughput — measurable proxies for delivery velocity.
• Customer-facing release artifacts. The release pipeline (worker order, changelog worker, next-dev alias) determines what your tag history and changelog look like, which is the raw material for public release notes and backport/LTS policy.
• Mixed library/app layouts. disablePackageReplace() plus the section-and-type-aware disableAutoloadMerge() supports the "libraries symlinked via path repos, apps not required from root" topology — a real decision for teams whose Laravel app consumes its own packages.

When to Consider This Package

Adopt when:

• You have 4+ Composer packages in one repo with mutual dependencies, or a credible plan to reach that within 2–3 quarters.
• You maintain multiple version lines (e.g., a Laravel 10 LTS line alongside current) and need branch-aware tag validation.
• The team is on PHP 8.2+ — this is a hard requirement.
• You need either replace-based single-surface publishing or path-repo symlink installs; both are first-class config options.
• You want release automation you own and can extend (ReleaseWorkerInterface) rather than a hosted service you can't fork.

Look elsewhere when:

• You ship one Laravel package, or a few genuinely independent ones. The merge/validate/propagate machinery is pure overhead; Composer path repositories plus a release script suffice.
• You still support PHP 8.1. Only the deprecated symplify/monorepo-builder:^11.2 branch works there — an unmaintained dependency in your build chain is a bad trade for a convenience tool.
• The rest of the repo is on a JS-ecosystem workspace manager. Two competing monorepo philosophies cost more than either saves.
• You expect per-package test matrices across Laravel versions out of the box. This tool consolidates versions; it does not orchestrate a matrix. You'd still own that CI.
• Procurement requires vendor SLAs or commercial support.

Diligence flags to price in:

• The README's install command (composer require monorepo-php/monorepo --dev) diverges from the package name (symplify/monorepo-builder), which signals an in-flight rebrand. Confirm the canonical package name before it lands in internal docs, or you'll write stale onboarding material on day one.
• Packagist dependents show 0. For a --dev tool that's partly a measurement artifact, but treat ecosystem support as thin and the maintainer-bus factor as real.
• Plan for this as a forkable internal dev dependency, not a strategic platform bet. Pin the version; keep the release-worker config minimal so a swap stays cheap.

How to Pitch It (Stakeholders)

For executives: This is build tooling, not shipped code — MIT-licensed, --dev only, zero runtime footprint in what customers install. What it buys is release velocity and version hygiene: one command to bump, tag, and push across N packages, plus a CI gate that stops sub-packages drifting onto different Laravel or PHPUnit versions. Cost is a single config file and a one-time migration; risk is a single-maintainer dependency in our build chain, which we contain by pinning versions and keeping our release-worker config thin enough to fork or replace in a day.

For engineering: It replaces hand-rolled Composer merge and release scripts with tested equivalents. merge folds each package's composer.json into the root so root PHPUnit/PHPStan resolve every namespace; validate enforces shared-dependency parity; propagate and bump-interdependency push versions back out; release runs a configurable worker pipeline (update replace, set deps, changelog, tag, push, next-dev alias) with --dry-run for preview. All configuration lives in one monorepo-builder.php. The autoload-skip and disablePackageReplace options cover mixed library/app layouts — but note autoload-dev must keep merging if root PHPUnit is to discover library test classes, since Composer never registers dev autoload from path-repo dependencies. Prerequisite is PHP 8.2+.

The ask: A one-day spike on a branch — run init, merge, and validate against our current packages, with release --dry-run as the acceptance test — then a go/no-go. Success criteria: root CI green on a single install, and a dry-run release that produces the tag sequence and changelog entries we'd actually want to publish.