Monorepo Builder Laravel Package

Product Decisions This Supports

• Monorepo Strategy for Laravel Ecosystems: Justify transitioning to a PHP monorepo for Laravel-based projects (e.g., modular SaaS platforms, plugin ecosystems, or microservices). This package automates critical workflows, reducing friction for teams scaling Laravel codebases by:

  • Centralizing dependency management: Merge package composer.json files into a root (e.g., consolidating Laravel core + plugin dependencies) via the merge command, ensuring consistency across require, require-dev, and custom sections like scripts-aliases.
  • Enforcing dependency governance: Validate shared dependencies (e.g., laravel/framework, symfony/console) across packages with the validate command to prevent version conflicts, critical for Laravel ecosystems with tightly coupled plugins.
  • Streamlining releases: Automate version bumps, Git tags, and changelog updates for all packages simultaneously using the release command, cutting release cycle time by 50–70%—ideal for Laravel projects with frequent updates.

• Build vs. Buy Decision:

  • Buy to avoid reinventing tools for:
    • composer.json merging/propagation (replaces manual scripts or custom PHP logic).
    • Version conflict resolution (e.g., bump-interdependency for Laravel plugin dependencies).
    • Release orchestration (e.g., package-alias for branch-aware development).
  • Maturity: Actively maintained (12.5.x), Laravel-aligned features (e.g., localize-composer-paths for testing plugins in isolation), and MIT license reduce custom development risk.

• CI/CD & Developer Experience:

  • Integrate with GitHub Actions for monorepo-to-polyrepo splitting (e.g., deploying Laravel modules independently) using symplify/github-action-monorepo-split.
  • Improve onboarding with the init command to generate standardized package structures (e.g., packages/laravel-plugin-*).
  • Enable parallel testing with localize-composer-paths (e.g., testing a Laravel plugin against a local core framework version).
  • Support Laravel-specific workflows: Configure composerSectionOrder to preserve Laravel’s autoload-dev or extra.laravel sections during merges.

• LTS & Multi-Version Support:

  • Branch-aware tag validation for long-term support (LTS) releases (e.g., Laravel 10 vs. 11). Ensures compatibility checks compare only within the same major version, critical for teams maintaining multiple version lines.
  • Customizable release workers: Extend functionality (e.g., add a NotifySlackReleaseWorker for Laravel release announcements or a RunLaravelTestsReleaseWorker to execute tests post-release).

When to Consider This Package

• Adopt if:

  • Your Laravel project uses a monorepo (or is evaluating one) with ≥5 composer.json files (e.g., core framework + plugins/microservices).
  • You need to merge, validate, or propagate composer.json sections across packages to avoid manual drudgery (e.g., shared Laravel dependencies like laravel/framework or spatie/laravel-permission).
  • Your team releases interdependent Laravel packages and wants to automate version bumps, tags, and changelogs (e.g., core + plugins).
  • You require parallel testing or localized Composer paths for pre-split package development (e.g., testing a Laravel plugin against a local core).
  • Your CI/CD pipeline could benefit from monorepo-to-polyrepo splitting (e.g., independent deployments of Laravel modules).
  • You maintain multiple version lines (e.g., LTS branches) and need branch-aware release validation.
  • Your team lacks dedicated DevOps resources but needs to maintain scalable dependency management for Laravel projects.

• Look elsewhere if:

  • Your project is not a monorepo (or won’t adopt one). This package is monorepo-specific and offers no value for single-repo or polyrepo setups.
  • You’re using non-PHP/Laravel stacks (e.g., Node.js, Python, or Go).
  • You need advanced monorepo features like cross-language support (e.g., PHP + JavaScript) or multi-repository Git management (e.g., Git submodules or subtrees).
  • Your team has dedicated DevOps resources to build custom solutions for composer.json management or release automation.
  • You require fine-grained access control (e.g., per-package dependency approvals) beyond what this package offers.

How to Pitch It (Stakeholders)

For Executives: "This package automates the pain points of managing a Laravel monorepo—merging dependencies, validating versions, and orchestrating releases—saving 50–70% of release cycle time while reducing manual errors. For example, teams maintaining Laravel plugins or microservices can now release all packages simultaneously with a single command, ensuring consistency across shared dependencies like laravel/framework. It’s a turnkey solution for scaling PHP projects, with minimal maintenance overhead (MIT license, active updates). The cost of adoption is low: a few hours to configure, and the ROI comes from faster releases, fewer dependency conflicts, and easier CI/CD integration."

For Engineering Teams: *"Monorepo Builder solves three critical problems for Laravel monorepos:

1. Dependency Hell: Automatically merges and validates composer.json files across packages, preventing version conflicts (e.g., laravel/framework mismatches).
2. Release Automation: Handles version bumps, Git tags, and changelogs for all packages at once, with dry-run support to preview changes. Customize workflows with PHP config or extend via ReleaseWorkerInterface.
3. Developer Experience: Commands like localize-composer-paths enable parallel testing (e.g., testing a plugin against a local Laravel core), and init scaffolds new packages with consistent structure.

Why use it?

• Replace manual scripts for merging composer.json or propagating versions.
• Integrate with GitHub Actions for monorepo splitting (e.g., deploying Laravel modules independently).
• Support LTS branches with branch-aware release validation.
• Leverage Laravel-specific features like preserving autoload-dev or extra.laravel sections.

Getting Started:

1. Run composer require monorepo-php/monorepo --dev and vendor/bin/monorepo-builder init.
2. Configure monorepo-builder.php to define package directories, exclusions, and custom merge rules.
3. Use commands like merge, validate, or release in CI/CD pipelines.

Example Use Case: A Laravel SaaS platform with 10+ plugins can now release all packages in one command, ensuring plugins use compatible versions of the core framework. The validate command catches dependency conflicts before they break builds, and localize-composer-paths speeds up plugin testing by 30%."