Getting Started

Minimal Steps

Installation
```
composer require monorepo-php/monorepo --dev
```
Ensure PHP 8.2+ is used (or downgrade to symplify/monorepo-builder:^11.2 for PHP 8.1).
Initialize the Monorepo Run once to scaffold the structure:
```
vendor/bin/monorepo-builder init
```
This creates:
- packages/ directory (default location for sub-packages).
- monorepo-builder.php (configuration file).
First Merge Merge all composer.json files from sub-packages into the root:
```
vendor/bin/monorepo-builder merge
```
Verify the root composer.json now includes all dependencies, scripts, and configurations.
First Release Test a release workflow:
```
vendor/bin/monorepo-builder release v0.1.0
```
This validates versions, updates composer.json, and generates changelogs.

Where to Look First

Configuration: Start with monorepo-builder.php to customize paths, package naming conventions, and release behavior.
Commands: Run vendor/bin/monorepo-builder list to see all available commands and their descriptions.

Documentation: Check the Configuration section in the README for key options like:

return [
    'paths' => [
        'packages' => 'packages/*', // Customize package directory paths
        'config' => 'monorepo-builder.php',
    ],
    'github' => [
        'user' => 'your-github-username',
        'repository' => 'your-repo-name',
    ],
];

Debugging: Use --dry-run flag for commands like merge or release to preview changes:
```
vendor/bin/monorepo-builder merge --dry-run
```

First Use Case: Adding a New Package

Create a new package directory under packages/ (e.g., packages/my-new-package).
Add a composer.json to the package with its dependencies and configurations.
Merge the package into the root:
```
vendor/bin/monorepo-builder merge
```
Test locally by requiring the package in the root:
```
composer require my-new-package
```

Implementation Patterns

Core Workflows

1. Package Management

Adding Packages: Use merge to include new packages in the root composer.json. The tool automatically handles:
- Dependencies (require, require-dev).
- Autoloading (autoload, autoload-dev).
- Scripts (scripts section).
- Configurations (config, extra, etc.).
- Tip: Use --dry-run first to verify the merge output.
Removing Packages: Manually delete the package directory and run:
```
vendor/bin/monorepo-builder merge --remove-unused
```
This cleans up unused dependencies from the root composer.json.

2. Version Management

Version Validation: The release command validates that all packages in the monorepo follow semantic versioning (SemVer) and are compatible. Configure version ranges in monorepo-builder.php:
```
return [
    'version_ranges' => [
        'packages/*' => '1.0.0|2.0.0', // Allow versions 1.x or 2.x
    ],
];
```
Bumping Versions: Use the release command to bump versions across the monorepo:
```
vendor/bin/monorepo-builder release v1.2.0 --bump
```
This updates all package versions in composer.json files and generates changelogs.

3. Release Automation

Full Release Workflow:
```
vendor/bin/monorepo-builder release v1.0.0
```
Steps performed:
1. Validates versions and dependencies.
2. Updates composer.json versions.
3. Generates changelogs for each package.
4. Commits changes with a release message.
5. (Optional) Pushes to GitHub if configured.

Custom Release Scripts: Extend the release process by adding scripts to monorepo-builder.php:

return [
    'release' => [
        'scripts' => [
            'post-release' => 'php scripts/deploy.php',
        ],
    ],
];

4. Dependency Propagation

Propagate Root Dependencies: Use propagate to push root-level dependencies (e.g., dev dependencies) down to packages:
```
vendor/bin/monorepo-builder propagate
```
Configure which dependencies to propagate:
```
return [
    'propagate' => [
        'dev-dependencies' => ['phpunit/phpunit', 'symfony/debug'],
    ],
];
```

Integration Tips

1. CI/CD Pipelines

Merge Validation: Add a step to validate the monorepo structure in CI:

# Example GitHub Actions step
- name: Validate Monorepo
  run: vendor/bin/monorepo-builder merge --dry-run

Release Automation: Trigger releases on tags or merge to main:

- name: Release
  if: github.ref == 'refs/heads/main'
  run: vendor/bin/monorepo-builder release $(date +'%Y.%m.%d') --no-commit

2. Custom Package Paths

Override default paths in monorepo-builder.php:

return [
    'paths' => [
        'packages' => ['src/*', 'lib/*'], // Include multiple directories
        'config' => '.monorepo.php',
    ],
];

3. GitHub Integration

Configure GitHub credentials for automated releases:

return [
    'github' => [
        'token' => getenv('GITHUB_TOKEN'),
        'user' => 'your-org',
        'repository' => 'your-repo',
    ],
];

Use release with --push to auto-publish tags:

vendor/bin/monorepo-builder release v1.0.0 --push

4. Changelog Generation

Customize changelog templates by extending the release command:

return [
    'changelog' => [
        'template' => file_get_contents('custom-changelog-template.md'),
    ],
];

5. Dependency Conflicts

Resolve conflicts during merge by using --strategy:
```
vendor/bin/monorepo-builder merge --strategy=prefer-root
```
Strategies:
- prefer-root: Prioritize root composer.json values.
- prefer-package: Prioritize package-level values.
- union: Merge arrays (default).

Gotchas and Tips

Pitfalls

Version Mismatches:
- Issue: Running release with mismatched package versions (e.g., some packages at 1.0.0, others at 2.0.0) may fail validation.
- Fix: Use version_ranges in config to allow flexibility:
```
'version_ranges' => [
    'packages/*' => '1.0.0|2.0.0',
],
```
- Debug: Run vendor/bin/monorepo-builder validate to check versions before releasing.
Circular Dependencies:
- Issue: Packages depending on each other may cause infinite loops during merge or propagate.
- Fix: Manually review the dependency graph or use --dry-run to identify cycles.
Overwriting Configurations:
- Issue: Running merge may overwrite root-level configurations (e.g., config, extra) with package-level values.
- Fix: Use --strategy=prefer-root to preserve root configurations or explicitly define which sections to merge.
Git Ignore Conflicts:
- Issue: The init command may create .gitignore files that conflict with existing ones.
- Fix: Merge .gitignore files manually or customize the init template in monorepo-builder.php:
```
return [
    'init' => [
        'gitignore_template' => file_get_contents('custom-gitignore'),
    ],
];
```
PHP Version Constraints:
- Issue: Mixing packages with incompatible PHP version requirements (e.g., one requires PHP 8.1, another 8.2) may cause conflicts.
- **Fix

Monorepo Builder Laravel Package