Composer-Merge-Plugin
A Composer plugin that merges multiple composer.json files at runtime to simplify dependency management for modular applications.
What is Composer-Merge-Plugin?
Wikimedia Composer Merge Plugin is a Composer plugin that allows a project's main composer.json file to include and merge configuration from additional composer.json files. It enables modular dependency management by dynamically combining dependencies, autoload rules, repositories, and other settings from specified files, simplifying complex setups where core requirements coexist with optional components.
PHP developers and maintainers of large applications or frameworks, such as MediaWiki, that need to manage dependencies across multiple modules, extensions, or sub-projects via Composer.
Developers choose this plugin over manual dependency management because it provides a hierarchical, automated way to merge configurations, supports flexible conflict resolution strategies, and ensures critical files are validated, reducing configuration overhead in modular projects.
Overview
Merge one or more additional composer.json files at Composer runtime
Use Cases
Best For
- Managing dependencies in large PHP applications with core and optional extensions, like MediaWiki.
- Modular projects where sub-projects or components have their own composer.json files that need integration.
- Enforcing required configuration files in deployments to prevent missing critical dependencies.
- Applications needing fine-grained control over merging specific sections like dev dependencies, scripts, or extra settings.
- Projects requiring flexible conflict resolution for duplicate packages, such as last-wins or first-wins strategies.
- Simplifying Composer setups in monorepo-like structures where multiple packages are managed within a single repository.
Not Ideal For
- Small, single-package PHP applications with no modular dependencies or extensions.
- Projects already using Composer's native monorepo features like path repositories for local package management.
- Teams requiring all dependencies explicitly listed in a single composer.json file for auditing or compliance purposes.
- CI/CD pipelines that need deterministic, immutable builds without dynamic configuration merges.
Pros & Cons
Pros
Supports glob patterns in the 'include' setting to dynamically merge multiple composer.json files, enabling hierarchical dependency management for extensions, as shown in the example with 'extensions/*/composer.json'.
Offers multiple strategies for duplicate packages: Composer's default engine, last-wins via 'replace': true, or first-wins via 'ignore-duplicates': true, providing control over version selection.
Configurable options like 'merge-dev', 'merge-scripts', and 'merge-extra' allow selective merging of specific sections, tailoring the combined configuration to project needs without unnecessary bloat.
The 'require' setting errors if patterns match no files, ensuring critical configurations like essential dependencies are never silently omitted, adding robustness to deployments.
Cons
Changes in included files aren't auto-detected; running 'composer update' is required to trigger re-evaluation, which can be overlooked in development workflows and lead to missing dependencies.
Custom commands from merged scripts sections are not available as direct Composer commands; they must be invoked via 'composer run-script', reducing convenience as documented in the 'merge-scripts' note.
Moving from Composer 1 to 2 requires updating the plugin first with Composer 1 to avoid it being ignored, adding steps and potential for error during upgrades, as highlighted in the README.
Frequently Asked Questions
Related Projects
Prestissimocomposer parallel install plugin
Symfony-FlexComposer plugin for Symfony
SatisSimple static Composer repository generator - For a full private Composer repo use Private Packagist
PackageVersions:package: Composer addon to efficiently get installed packages' version numbers
Found a gem we're missing?
Open-Awesome is built by the community, for the community. Submit a project, suggest an awesome list, or help improve the catalog on GitHub.