Composer Merge Plugin Laravel Package

Getting Started

Start by installing the plugin via Composer in your root project:

composer require --dev wikimedia/composer-merge-plugin

Then declare it in your root composer.json under "extra" (no version needed unless pinning):

{
  "extra": {
    "merge-plugin": {
      "include": ["components/*/composer.json"]
    }
  }
}

Prerequisites:

• Composer 2.0+ (required for v2.0.1; drop-in replacement for Composer 1.x).
• PHP 7.2.0+ (minimum; HHVM no longer supported).

Now, add per-component composer.json files (e.g., components/foo/composer.json, components/bar/composer.json) — each can define its own require, autoload, etc. Running composer install or update will automatically merge them into a unified dependency graph.

Implementation Patterns

• Component-scoped dependencies: Each module/component (e.g., src/App/FeatureA/, vendor-packages/) holds its own composer.json, reducing clutter and ownership fragmentation.
• Git submodule integration: Use submodules for external/internal packages and let each manage its own deps via merge-plugin, avoiding conflict-prone manual updates.
• Precedence control: Use "include" paths in order (e.g., ["base/composer.json", "overrides/composer.json"]) where later entries override earlier ones. Combine with "recurse": true to scan subdirectories recursively.
• Conditional inclusion: Use "require": true per file to mark optional modules — the plugin skips missing files gracefully.
• Autoload composition: Each merged file’s "autoload" section is flattened and merged (not overridden), enabling modular PSR-4/PSR-0 definitions.

Composer 2.0+ Optimization:

• Leverage Composer 2.0’s faster dependency resolution for improved install/update performance in large monorepos.
• Use composer why-not <package> to debug missing dependencies in merged environments.

Gotchas and Tips

• No replace, provide, or conflict merging: Only require, require-dev, autoload, scripts, and repositories are merged — other sections like config or scripts event definitions are not merged but are preserved as arrays. Double-check for unintentional overwrites.
• Order matters: Later entries in include take precedence. If two files define the same PSR-4 prefix, the last one in the merge list wins. Use "exclude" and "ignore-duplicates" to fine-tune.
• Debugging:
  • Run composer run-script --list --dev or inspect composer install -v output — the plugin logs merge activity.
  • For deeper insight, use composer show -m (if supported) or manually run composer dump-autoload -o -v to verify merged autoloader behavior.
  • Composer 2.0 tip: Use composer diagnose to check for environment compatibility (e.g., PHP 7.2+).
• Performance:
  • Large monorepos with many merged files may still slow update/install. Use "recurse": false and explicit paths to reduce scan scope.
  • Composer 2.0’s caching improves repeatability; clear caches with composer clear-cache if issues persist.
• Git conflicts:
  • Merged files evolve independently — enforce CI checks that run composer validate against both root and merged files to catch misconfigurations early.
  • PHP 7.2+ tip: Use composer validate --strict to enforce modern syntax rules.
• Avoid circular merge loops: Never include the root composer.json recursively — the plugin only merges extra files, but misconfiguration can cause infinite recursion.
• Deprecation Note:
  • HHVM dropped: Ensure your CI/CD pipelines no longer test on HHVM (removed in v2.0.1).
  • PHP 5.3/5.6: Projects using these versions must upgrade to PHP 7.2+ for compatibility.