Chris@0: [![Latest Stable Version]](https://packagist.org/packages/wikimedia/composer-merge-plugin) [![License]](https://github.com/wikimedia/composer-merge-plugin/blob/master/LICENSE) Chris@0: [![Build Status]](https://travis-ci.org/wikimedia/composer-merge-plugin) Chris@0: [![Code Coverage]](https://scrutinizer-ci.com/g/wikimedia/composer-merge-plugin/?branch=master) Chris@0: Chris@0: Composer Merge Plugin Chris@0: ===================== Chris@0: Chris@0: Merge multiple composer.json files at [Composer] runtime. Chris@0: Chris@0: Composer Merge Plugin is intended to allow easier dependency management for Chris@0: applications which ship a composer.json file and expect some deployments to Chris@0: install additional Composer managed libraries. It does this by allowing the Chris@0: application's top level `composer.json` file to provide a list of optional Chris@0: additional configuration files. When Composer is run it will parse these files Chris@0: and merge their configuration settings into the base configuration. This Chris@0: combined configuration will then be used when downloading additional libraries Chris@0: and generating the autoloader. Chris@0: Chris@0: Composer Merge Plugin was created to help with installation of [MediaWiki] Chris@0: which has core library requirements as well as optional libraries and Chris@0: extensions which may be managed via Composer. Chris@0: Chris@0: Chris@0: Installation Chris@0: ------------ Chris@0: Chris@0: Composer Merge Plugin requires [Composer 1.0.0](https://getcomposer.org/) or Chris@0: newer. Chris@0: Chris@0: ``` Chris@0: $ composer require wikimedia/composer-merge-plugin Chris@0: ``` Chris@0: Chris@0: Chris@0: Usage Chris@0: ----- Chris@0: Chris@0: ```json Chris@0: { Chris@0: "require": { Chris@0: "wikimedia/composer-merge-plugin": "dev-master" Chris@0: }, Chris@0: "extra": { Chris@0: "merge-plugin": { Chris@0: "include": [ Chris@0: "composer.local.json", Chris@0: "extensions/*/composer.json" Chris@0: ], Chris@0: "require": [ Chris@0: "submodule/composer.json" Chris@0: ], Chris@0: "recurse": true, Chris@0: "replace": false, Chris@0: "ignore-duplicates": false, Chris@0: "merge-dev": true, Chris@0: "merge-extra": false, Chris@0: "merge-extra-deep": false, Chris@0: "merge-scripts": false Chris@0: } Chris@0: } Chris@0: } Chris@0: ``` Chris@0: Chris@0: Chris@0: Plugin configuration Chris@0: -------------------- Chris@0: Chris@0: The plugin reads its configuration from the `merge-plugin` section of your Chris@0: composer.json's `extra` section. An `include` setting is required to tell Chris@0: Composer Merge Plugin which file(s) to merge. Chris@0: Chris@0: Chris@0: ### include Chris@0: Chris@0: The `include` setting can specify either a single value or an array of values. Chris@0: Each value is treated as a PHP `glob()` pattern identifying additional Chris@0: composer.json style configuration files to merge into the root package Chris@0: configuration for the current Composer execution. Chris@0: Chris@0: The following sections of the found configuration files will be merged into Chris@0: the Composer root package configuration as though they were directly included Chris@0: in the top-level composer.json file: Chris@0: Chris@0: * [autoload](https://getcomposer.org/doc/04-schema.md#autoload) Chris@0: * [autoload-dev](https://getcomposer.org/doc/04-schema.md#autoload-dev) Chris@0: (optional, see [merge-dev](#merge-dev) below) Chris@0: * [conflict](https://getcomposer.org/doc/04-schema.md#conflict) Chris@0: * [provide](https://getcomposer.org/doc/04-schema.md#provide) Chris@0: * [replace](https://getcomposer.org/doc/04-schema.md#replace) Chris@0: * [repositories](https://getcomposer.org/doc/04-schema.md#repositories) Chris@0: * [require](https://getcomposer.org/doc/04-schema.md#require) Chris@0: * [require-dev](https://getcomposer.org/doc/04-schema.md#require-dev) Chris@0: (optional, see [merge-dev](#merge-dev) below) Chris@0: * [suggest](https://getcomposer.org/doc/04-schema.md#suggest) Chris@0: * [extra](https://getcomposer.org/doc/04-schema.md#extra) Chris@0: (optional, see [merge-extra](#merge-extra) below) Chris@0: * [scripts](https://getcomposer.org/doc/04-schema.md#scripts) Chris@0: (optional, see [merge-scripts](#merge-scripts) below) Chris@0: Chris@0: Chris@0: ### require Chris@0: Chris@0: The `require` setting is identical to [`include`](#include) except when Chris@0: a pattern fails to match at least one file then it will cause an error. Chris@0: Chris@0: ### recurse Chris@0: Chris@0: By default the merge plugin is recursive; if an included file has Chris@0: a `merge-plugin` section it will also be processed. This functionality can be Chris@0: disabled by adding a `"recurse": false` setting. Chris@0: Chris@0: Chris@0: ### replace Chris@0: Chris@0: By default, Composer's conflict resolution engine is used to determine which Chris@0: version of a package should be installed when multiple files specify the same Chris@0: package. A `"replace": true` setting can be provided to change to a "last Chris@0: version specified wins" conflict resolution strategy. In this mode, duplicate Chris@0: package declarations found in merged files will overwrite the declarations Chris@0: made by earlier files. Files are loaded in the order specified by the Chris@0: `include` setting with globbed files being processed in alphabetical order. Chris@0: Chris@0: ### ignore-duplicates Chris@0: Chris@0: By default, Composer's conflict resolution engine is used to determine which Chris@0: version of a package should be installed when multiple files specify the same Chris@0: package. An `"ignore-duplicates": true` setting can be provided to change to Chris@0: a "first version specified wins" conflict resolution strategy. In this mode, Chris@0: duplicate package declarations found in merged files will be ignored in favor Chris@0: of the declarations made by earlier files. Files are loaded in the order Chris@0: specified by the `include` setting with globbed files being processed in Chris@0: alphabetical order. Chris@0: Chris@0: Note: `"replace": true` and `"ignore-duplicates": true` modes are mutually Chris@0: exclusive. If both are set, `"ignore-duplicates": true` will be used. Chris@0: Chris@0: ### merge-dev Chris@0: Chris@0: By default, `autoload-dev` and `require-dev` sections of included files are Chris@0: merged. A `"merge-dev": false` setting will disable this behavior. Chris@0: Chris@0: Chris@0: ### merge-extra Chris@0: Chris@0: A `"merge-extra": true` setting enables the merging the contents of the Chris@0: `extra` section of included files as well. The normal merge mode for the extra Chris@0: section is to accept the first version of any key found (e.g. a key in the Chris@0: master config wins over the version found in any imported config). If Chris@0: `replace` mode is active ([see above](#replace)) then this behavior changes Chris@0: and the last key found will win (e.g. the key in the master config is replaced Chris@0: by the key in the imported config). If `"merge-extra-deep": true` is specified Chris@0: then, the sections are merged similar to array_merge_recursive() - however Chris@0: duplicate string array keys are replaced instead of merged, while numeric Chris@0: array keys are merged as usual. The usefulness of merging the extra section Chris@0: will vary depending on the Composer plugins being used and the order in which Chris@0: they are processed by Composer. Chris@0: Chris@0: Note that `merge-plugin` sections are excluded from the merge process, but are Chris@0: always processed by the plugin unless [recursion](#recurse) is disabled. Chris@0: Chris@0: ### merge-scripts Chris@0: Chris@0: A `"merge-scripts": true` setting enables merging the contents of the Chris@0: `scripts` section of included files as well. The normal merge mode for the Chris@0: scripts section is to accept the first version of any key found (e.g. a key in Chris@0: the master config wins over the version found in any imported config). If Chris@0: `replace` mode is active ([see above](#replace)) then this behavior changes Chris@0: and the last key found will win (e.g. the key in the master config is replaced Chris@0: by the key in the imported config). Chris@0: Chris@0: Note: [custom commands][] added by merged configuration will work when invoked Chris@0: as `composer run-script my-cool-command` but will not be available using the Chris@0: normal `composer my-cool-command` shortcut. Chris@0: Chris@0: Chris@0: Running tests Chris@0: ------------- Chris@0: Chris@0: ``` Chris@0: $ composer install Chris@0: $ composer test Chris@0: ``` Chris@0: Chris@0: Chris@0: Contributing Chris@0: ------------ Chris@0: Chris@0: Bug, feature requests and other issues should be reported to the [GitHub Chris@0: project]. We accept code and documentation contributions via Pull Requests on Chris@0: GitHub as well. Chris@0: Chris@0: - [PSR-2 Coding Standard][] is used by the project. The included test Chris@0: configuration uses [PHP Code Sniffer][] to validate the conventions. Chris@0: - Tests are encouraged. Our test coverage isn't perfect but we'd like it to Chris@0: get better rather than worse, so please try to include tests with your Chris@0: changes. Chris@0: - Keep the documentation up to date. Make sure `README.md` and other Chris@0: relevant documentation is kept up to date with your changes. Chris@0: - One pull request per feature. Try to keep your changes focused on solving Chris@0: a single problem. This will make it easier for us to review the change and Chris@0: easier for you to make sure you have updated the necessary tests and Chris@0: documentation. Chris@0: Chris@0: Chris@0: License Chris@0: ------- Chris@0: Chris@0: Composer Merge plugin is licensed under the MIT license. See the Chris@0: [`LICENSE`](LICENSE) file for more details. Chris@0: Chris@0: Chris@0: --- Chris@0: [Composer]: https://getcomposer.org/ Chris@0: [MediaWiki]: https://www.mediawiki.org/wiki/MediaWiki Chris@0: [GitHub project]: https://github.com/wikimedia/composer-merge-plugin Chris@0: [PSR-2 Coding Standard]: https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-2-coding-style-guide.md Chris@0: [PHP Code Sniffer]: http://pear.php.net/package/PHP_CodeSniffer Chris@0: [Latest Stable Version]: https://img.shields.io/packagist/v/wikimedia/composer-merge-plugin.svg?style=flat Chris@0: [License]: https://img.shields.io/packagist/l/wikimedia/composer-merge-plugin.svg?style=flat Chris@0: [Build Status]: https://img.shields.io/travis/wikimedia/composer-merge-plugin.svg?style=flat Chris@0: [Code Coverage]: https://img.shields.io/scrutinizer/coverage/g/wikimedia/composer-merge-plugin/master.svg?style=flat Chris@0: [custom commands]: https://getcomposer.org/doc/articles/scripts.md#writing-custom-commands