Composer Merge Plugin

Composer Merge Plugin lets a top-level composer.json list additional, optional composer.json files whose require, require-dev, autoload, and other settings get merged into the base configuration whenever Composer runs. It was built by the Wikimedia Foundation to support MediaWiki, which ships core library requirements alongside a large set of optional extensions and skins that each carry their own Composer dependencies.

By merging these fragment files at runtime instead of requiring every optional dependency to be hand-added to one giant composer.json, applications can let each plugin/module/extension declare its own dependencies independently while still resolving everything through a single composer install.

What You Get

• Merging of require/require-dev entries from multiple composer.json files into a single dependency resolution pass.
• Support for glob patterns in extra.merge-plugin.include, so newly added extension/module directories are picked up automatically.
• Configurable conflict handling for version constraints across merged files via MultiConstraint and StabilityFlags.
• Merging of autoload/autoload-dev PSR-4/PSR-0 mappings, repositories, and extra sections, not just dependency requirements.
• A replace mode (merge-plugin.replace) to control whether merged sections replace or combine with the base file’s values.

Common Use Cases

• Letting a CMS or wiki platform (as MediaWiki does) allow each optional extension to declare its own Composer dependencies without editing the core composer.json.
• Splitting a large application’s dependencies into per-module composer.json fragments that are merged at install time for clearer ownership.
• Composing a project’s dependency list from a base file plus environment-specific fragments (e.g. dev-only tooling merged only in local checkouts).
• Supporting plugin/addon ecosystems where third-party packages ship alongside their own dependency manifest that needs to be honored by the host application’s install.

Under The Hood

Architecture: MergePlugin.php implements Composer’s PluginInterface/EventSubscriberInterface, hooking into Composer’s init and pre-install/pre-update events. PluginState.php tracks the plugin’s runtime configuration (which files to include, merge order, replace mode) parsed from the extra.merge-plugin section of the base composer.json. ExtraPackage.php represents each discovered fragment file and knows how to fold its require, autoload, and other sections into the root package, while MultiConstraint.php and StabilityFlags.php resolve version-constraint conflicts when the same dependency appears with different constraints across merged files, and NestedArray.php provides the recursive array-merge primitive used throughout.

Tech Stack: PHP 7.4+, targets the composer-plugin-api (both v1.x and v2.x of Composer itself are supported), with no other runtime dependencies — it’s a thin layer directly on top of Composer’s own plugin and package APIs.

Code Quality: tests/ contains PHPUnit test classes (6 files) covering the merge logic, run alongside phpcs (PSR2) and phan static analysis per the composer.json scripts section; CI runs on GitHub Actions with Scrutinizer tracking code coverage. Development activity has slowed considerably in recent years (the last tagged release, v2.1.0, shipped in 2023) though the plugin remains widely depended upon and functionally stable for its narrow scope.

API Design: The entire integration surface is a JSON configuration block (extra.merge-plugin.include, .recurse, .replace, .merge-dev) in the consuming project’s own composer.json — there is no PHP API to call directly, since the plugin’s job is purely to intercept and augment Composer’s own dependency-resolution process.