Monorepo Builder Laravel Package

Getting Started

Minimal Steps

1. Initialize the Monorepo Run vendor/bin/monorepo-builder init once to scaffold a packages/ directory and a basic monorepo-builder.php config file.

2. Merge Package Dependencies After adding packages to packages/, run vendor/bin/monorepo-builder merge to fold all composer.json sections (e.g., require, autoload) into the root composer.json.

3. Validate Shared Dependencies Ensure consistency with vendor/bin/monorepo-builder validate.

First Use Case

Scenario: You have a new Laravel monorepo with 3 packages (auth, api, cli). After initializing:

composer require monorepo-php/monorepo --dev
vendor/bin/monorepo-builder init

Add packages to packages/ (e.g., packages/auth). Then merge:

vendor/bin/monorepo-builder merge

This aggregates all dependencies (e.g., laravel/framework) and autoload rules into the root composer.json.

Implementation Patterns

Daily Workflow

1. Package Development

   • Develop features in individual packages (e.g., packages/auth).
   • Test locally with composer install in the root.

2. Dependency Management

   • Use vendor/bin/monorepo-builder bump-interdependency "^1.0" to update mutual dependencies (e.g., auth and api both requiring shared-utils).
   • Validate consistency with vendor/bin/monorepo-builder validate.

3. Release Automation

   • Preview changes: vendor/bin/monorepo-builder release v1.0 --dry-run.
   • Cut a release: vendor/bin/monorepo-builder release v1.0.
   • For patch releases: vendor/bin/monorepo-builder release patch.

4. CI/CD Integration

   • Run merge and validate in CI to catch misconfigurations early.
   • Use localize-composer-paths for testing packages in isolation:

     vendor/bin/monorepo-builder localize-composer-paths
     composer install --prefer-source
     

Laravel-Specific Tips

• Laravel Packages: Configure type: laravel-package in package composer.json and use disableAutoloadMerge for libraries:

  $mbConfig->disableAutoloadMerge(
      sections: [AutoloadSection::Autoload],
      forTypes: [PackageType::Library]
  );
  

• Service Providers: Merge autoload-dev to enable root-level testing:

  $mbConfig->disableAutoloadMerge(
      sections: [AutoloadSection::AutoloadDev],
      forTypes: [] // Merge for all packages
  );
  

• Publishable Assets: Use dataToAppend to add root-level extra.publish:

  $mbConfig->dataToAppend([
      ComposerJsonSection::EXTRA => [
          'publish' => [
              'auth' => 'config/auth.php',
          ],
      ],
  ]);
  

Integration with Laravel Tools

• Laravel Mix/Vite: Localize paths for asset compilation:

  vendor/bin/monorepo-builder localize-composer-paths
  npm run dev --prefix packages/auth
  

• Pint/Pint: Run in root with merged autoload:

  vendor/bin/monorepo-builder merge
  vendor/bin/pint
  

Gotchas and Tips

Pitfalls

1. Autoload Merging Conflicts

   • Issue: Skipping autoload-dev merge breaks cross-package PHPUnit tests.
   • Fix: Ensure AutoloadSection::AutoloadDev is merged for testable packages:

     $mbConfig->disableAutoloadMerge(
         sections: [AutoloadSection::Autoload],
         forTypes: [PackageType::Library]
     );
     

2. Package Replace Overrides

   • Issue: disablePackageReplace() may break symlinked dependencies in Laravel apps.
   • Fix: Re-enable for apps requiring real installs:

     $mbConfig->enablePackageReplace(); // Default behavior
     

3. Version Validation Failures

   • Issue: validate fails if packages use different versions of laravel/framework.
   • Fix: Use bump-interdependency to align versions:

     vendor/bin/monorepo-builder bump-interdependency "^10.0"
     

4. Dry-Run Ignored

   • Issue: --dry-run may not show all changes (e.g., replace section updates).
   • Fix: Check monorepo-builder.php for disableDefaultWorkers() or custom workers.

Debugging

• Inspect Merged Output:

  vendor/bin/monorepo-builder merge --dump-config
  

• Log Release Steps: Add --verbose to release commands to see worker execution:

  vendor/bin/monorepo-builder release v1.0 --verbose
  

Configuration Quirks

1. Package Discovery
   • Exclude directories like packages/tests:

     $mbConfig->packageDirectoriesExcludes([
         __DIR__ . '/packages/tests',
     ]);
     

2. Section Ordering
   • Override Composer’s default order (e.g., move autoload before require):

     $mbConfig->composerSectionOrder([
         ComposerJsonSection::AUTOLOAD,
         ComposerJsonSection::REQUIRE,
         // ...
     ]);
     

3. Branch-Aware Releases
   • Enable LTS validation for multi-version monorepos:

     $mbConfig->enableBranchAwareTagValidation();
     

Extension Points

1. Custom Workers Implement ReleaseWorkerInterface for pre/post-release tasks (e.g., Slack notifications):

   use Symplify\MonorepoBuilder\Release\ReleaseWorker\ReleaseWorkerInterface;
   
   class SlackNotifyReleaseWorker implements ReleaseWorkerInterface {
       public function work(Release $release): void {
           // Send Slack message
       }
   }
   

   Register in config:

   $mbConfig->workers([SlackNotifyReleaseWorker::class]);
   

2. Decorators Extend merge logic by decorating ComposerJsonMerger:

   use Symplify\MonorepoBuilder\Merge\ComposerJsonMerger;
   
   class CustomComposerJsonMerger extends ComposerJsonMerger {
       protected function mergeAutoload(array $rootAutoload, array $packageAutoload): array {
           // Custom logic
           return parent::mergeAutoload($rootAutoload, $packageAutoload);
       }
   }
   

   Bind in service container (e.g., Laravel’s AppServiceProvider).

3. Event Listeners Listen to monorepo-builder.events (e.g., for Git hooks):

   use Symplify\MonorepoBuilder\Event\MonorepoBuilderEvent;
   
   event(new MonorepoBuilderEvent('merge.started'));