Merge multiple composer.json files at Composer runtime.
Composer Merge Plugin is intended to allow easier dependency management for
applications which ship a composer.json file and expect some deployments to
install additional Composer managed libraries. It does this by allowing the
application's top level composer.json
file to provide a list of optional
additional configuration files. When Composer is run it will parse these files
and merge their configuration settings into the base configuration. This
combined configuration will then be used when downloading additional libraries
and generating the autoloader.
Composer Merge Plugin was created to help with installation of MediaWiki which has core library requirements as well as optional libraries and extensions which may be managed via Composer.
Composer Merge Plugin 1.4.x (and older) requires Composer 1.x.
Composer Merge Plugin 2.0.x (and newer) is compatible with both Composer 2.x and 1.x.
$ composer require wikimedia/composer-merge-plugin
If you are already using Composer Merge Plugin 1.4 (or older) and you are updating the plugin to 2.0 (or newer), it is recommended that you update the plugin first using Composer 1.
If you update the incompatible plugin using Composer 2, the plugin will be ignored:
The "wikimedia/composer-merge-plugin" plugin was skipped because it requires a Plugin API version ("^1.0") that does not match your Composer installation ("2.0.0"). You may need to run composer update with the "--no-plugins" option.
Consequently, Composer will be unaware of the merged dependencies and will remove them requiring you to run composer update
again to reinstall merged dependencies.
{
"require": {
"wikimedia/composer-merge-plugin": "dev-master"
},
"extra": {
"merge-plugin": {
"include": [
"composer.local.json",
"extensions/*/composer.json"
],
"require": [
"submodule/composer.json"
],
"recurse": true,
"replace": false,
"ignore-duplicates": false,
"merge-dev": true,
"merge-extra": false,
"merge-extra-deep": false,
"merge-replace": true,
"merge-scripts": false
}
}
}
In order for Composer Merge Plugin to install dependencies from updated or newly created sub-level composer.json
files in your project you need to run the command:
$ composer update
This will instruct Composer to recalculate the file hash for the top-level composer.json
thus triggering Composer Merge Plugin to look for the sub-level configuration files and update your dependencies.
The plugin reads its configuration from the merge-plugin
section of your
composer.json's extra
section. An include
setting is required to tell
Composer Merge Plugin which file(s) to merge.
The include
setting can specify either a single value or an array of values.
Each value is treated as a PHP glob()
pattern identifying additional
composer.json style configuration files to merge into the root package
configuration for the current Composer execution.
The following sections of the found configuration files will be merged into the Composer root package configuration as though they were directly included in the top-level composer.json file:
- autoload
- autoload-dev (optional, see merge-dev below)
- conflict
- provide
- replace (optional, see merge-replace below)
- repositories
- require
- require-dev (optional, see merge-dev below)
- suggest
- extra (optional, see merge-extra below)
- scripts (optional, see merge-scripts below)
The require
setting is identical to include
except when
a pattern fails to match at least one file then it will cause an error.
By default the merge plugin is recursive; if an included file has
a merge-plugin
section it will also be processed. This functionality can be
disabled by adding a "recurse": false