README

Composer Merge Plugin

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.

Installation

$ composer require wikimedia/composer-merge-plugin

Usage

{
    "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,
            "merge-dev": true,
            "merge-extra": false
        }
    }
}

Plugin configuration

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.

include

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
repositories
require
require-dev (optional, see merge-dev below)
suggest
extra (optional, see merge-extra below)

require

The require setting is identical to [include](#include) except when a pattern fails to match at least one file then it will cause an error.

recurse

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 setting.

replace

By default, Composer's conflict resolution engine is used to determine which version of a package should be installed when multiple files specify the same package. A "replace": true setting can be provided to change to a "last version specified wins" conflict resolution strategy. In this mode, duplicate package declarations found in merged files will overwrite the declarations made by earlier files. Files are loaded in the order specified by the include setting with globbed files being processed in alphabetical order.

merge-dev

By default, autoload-dev and require-dev sections of included files are merged. A "merge-dev": false setting will disable this behavior.

merge-extra

A "merge-extra": true setting enables the merging the contents of the extra section of included files as well. The normal merge mode for the extra section is to accept the first version of any key found (e.g. a key in the master config wins over the version found in any imported config). If replace mode is active (see above) then this behavior changes and the last key found will win (e.g. the key in the master config is replaced by the key in the imported config). The usefulness of merging the extra section will vary depending on the Composer plugins being used and the order in which they are processed by Composer.

Note that merge-plugin sections are excluded from the merge process, but are always processed by the plugin unless recursion is disabled.

Running tests

$ composer install
$ composer test

Contributing

Bug, feature requests and other issues should be reported to the GitHub project. We accept code and documentation contributions via Pull Requests on GitHub as well.

PSR-2 Coding Standard is used by the project. The included test configuration uses PHP Code Sniffer to validate the conventions.
Tests are encouraged. Our test coverage isn't perfect but we'd like it to get better rather than worse, so please try to include tests with your changes.
Keep the documentation up to date. Make sure README.md and other relevant documentation is kept up to date with your changes.
One pull request per feature. Try to keep your changes focused on solving a single problem. This will make it easier for us to review the change and easier for you to make sure you have updated the necessary tests and documentation.

License

Composer Merge plugin is licensed under the MIT license. See the LICENSE file for more details.

wkse / composer-merge-plugin

Maintainers

Details