vendor/wikimedia/composer-merge-plugin/README.md

   1 [![Latest Stable Version]](https://packagist.org/packages/wikimedia/composer-merge-plugin) [![License]](https://github.com/wikimedia/composer-merge-plugin/blob/master/LICENSE)
   2 [![Build Status]](https://travis-ci.org/wikimedia/composer-merge-plugin)
   3 [![Code Coverage]](https://scrutinizer-ci.com/g/wikimedia/composer-merge-plugin/?branch=master)
   4
   5 Composer Merge Plugin
   6 =====================
   7
   8 Merge multiple composer.json files at [Composer] runtime.
   9
  10 Composer Merge Plugin is intended to allow easier dependency management for
  11 applications which ship a composer.json file and expect some deployments to
  12 install additional Composer managed libraries. It does this by allowing the
  13 application's top level `composer.json` file to provide a list of optional
  14 additional configuration files. When Composer is run it will parse these files
  15 and merge their configuration settings into the base configuration. This
  16 combined configuration will then be used when downloading additional libraries
  17 and generating the autoloader.
  18
  19 Composer Merge Plugin was created to help with installation of [MediaWiki]
  20 which has core library requirements as well as optional libraries and
  21 extensions which may be managed via Composer.
  22
  23
  24 Installation
  25 ------------
  26
  27 Composer Merge Plugin requires [Composer 1.0.0](https://getcomposer.org/) or
  28 newer.
  29
  30 ```
  31 $ composer require wikimedia/composer-merge-plugin
  32 ```
  33
  34
  35 Usage
  36 -----
  37
  38 ```json
  39 {
  40     "require": {
  41         "wikimedia/composer-merge-plugin": "dev-master"
  42     },
  43     "extra": {
  44         "merge-plugin": {
  45             "include": [
  46                 "composer.local.json",
  47                 "extensions/*/composer.json"
  48             ],
  49             "require": [
  50                 "submodule/composer.json"
  51             ],
  52             "recurse": true,
  53             "replace": false,
  54             "ignore-duplicates": false,
  55             "merge-dev": true,
  56             "merge-extra": false,
  57             "merge-extra-deep": false,
  58             "merge-scripts": false
  59         }
  60     }
  61 }
  62 ```
  63
  64
  65 Plugin configuration
  66 --------------------
  67
  68 The plugin reads its configuration from the `merge-plugin` section of your
  69 composer.json's `extra` section. An `include` setting is required to tell
  70 Composer Merge Plugin which file(s) to merge.
  71
  72
  73 ### include
  74
  75 The `include` setting can specify either a single value or an array of values.
  76 Each value is treated as a PHP `glob()` pattern identifying additional
  77 composer.json style configuration files to merge into the root package
  78 configuration for the current Composer execution.
  79
  80 The following sections of the found configuration files will be merged into
  81 the Composer root package configuration as though they were directly included
  82 in the top-level composer.json file:
  83
  84 * [autoload](https://getcomposer.org/doc/04-schema.md#autoload)
  85 * [autoload-dev](https://getcomposer.org/doc/04-schema.md#autoload-dev)
  86   (optional, see [merge-dev](#merge-dev) below)
  87 * [conflict](https://getcomposer.org/doc/04-schema.md#conflict)
  88 * [provide](https://getcomposer.org/doc/04-schema.md#provide)
  89 * [replace](https://getcomposer.org/doc/04-schema.md#replace)
  90 * [repositories](https://getcomposer.org/doc/04-schema.md#repositories)
  91 * [require](https://getcomposer.org/doc/04-schema.md#require)
  92 * [require-dev](https://getcomposer.org/doc/04-schema.md#require-dev)
  93   (optional, see [merge-dev](#merge-dev) below)
  94 * [suggest](https://getcomposer.org/doc/04-schema.md#suggest)
  95 * [extra](https://getcomposer.org/doc/04-schema.md#extra)
  96   (optional, see [merge-extra](#merge-extra) below)
  97 * [scripts](https://getcomposer.org/doc/04-schema.md#scripts)
  98   (optional, see [merge-scripts](#merge-scripts) below)
  99
 100
 101 ### require
 102
 103 The `require` setting is identical to [`include`](#include) except when
 104 a pattern fails to match at least one file then it will cause an error.
 105
 106 ### recurse
 107
 108 By default the merge plugin is recursive; if an included file has
 109 a `merge-plugin` section it will also be processed. This functionality can be
 110 disabled by adding a `"recurse": false` setting.
 111
 112
 113 ### replace
 114
 115 By default, Composer's conflict resolution engine is used to determine which
 116 version of a package should be installed when multiple files specify the same
 117 package. A `"replace": true` setting can be provided to change to a "last
 118 version specified wins" conflict resolution strategy. In this mode, duplicate
 119 package declarations found in merged files will overwrite the declarations
 120 made by earlier files. Files are loaded in the order specified by the
 121 `include` setting with globbed files being processed in alphabetical order.
 122
 123 ### ignore-duplicates
 124
 125 By default, Composer's conflict resolution engine is used to determine which
 126 version of a package should be installed when multiple files specify the same
 127 package. An `"ignore-duplicates": true` setting can be provided to change to
 128 a "first version specified wins" conflict resolution strategy. In this mode,
 129 duplicate package declarations found in merged files will be ignored in favor
 130 of the declarations made by earlier files. Files are loaded in the order
 131 specified by the `include` setting with globbed files being processed in
 132 alphabetical order.
 133
 134 Note: `"replace": true` and `"ignore-duplicates": true` modes are mutually
 135 exclusive. If both are set, `"ignore-duplicates": true` will be used.
 136
 137 ### merge-dev
 138
 139 By default, `autoload-dev` and `require-dev` sections of included files are
 140 merged. A `"merge-dev": false` setting will disable this behavior.
 141
 142
 143 ### merge-extra
 144
 145 A `"merge-extra": true` setting enables the merging the contents of the
 146 `extra` section of included files as well. The normal merge mode for the extra
 147 section is to accept the first version of any key found (e.g. a key in the
 148 master config wins over the version found in any imported config). If
 149 `replace` mode is active ([see above](#replace)) then this behavior changes
 150 and the last key found will win (e.g. the key in the master config is replaced
 151 by the key in the imported config). If `"merge-extra-deep": true` is specified
 152 then, the sections are merged similar to array_merge_recursive() - however
 153 duplicate string array keys are replaced instead of merged, while numeric
 154 array keys are merged as usual. The usefulness of merging the extra section
 155 will vary depending on the Composer plugins being used and the order in which
 156 they are processed by Composer.
 157
 158 Note that `merge-plugin` sections are excluded from the merge process, but are
 159 always processed by the plugin unless [recursion](#recurse) is disabled.
 160
 161 ### merge-scripts
 162
 163 A `"merge-scripts": true` setting enables merging the contents of the
 164 `scripts` section of included files as well. The normal merge mode for the
 165 scripts section is to accept the first version of any key found (e.g. a key in
 166 the master config wins over the version found in any imported config). If
 167 `replace` mode is active ([see above](#replace)) then this behavior changes
 168 and the last key found will win (e.g. the key in the master config is replaced
 169 by the key in the imported config).
 170
 171 Note: [custom commands][] added by merged configuration will work when invoked
 172 as `composer run-script my-cool-command` but will not be available using the
 173 normal `composer my-cool-command` shortcut.
 174
 175
 176 Running tests
 177 -------------
 178
 179 ```
 180 $ composer install
 181 $ composer test
 182 ```
 183
 184
 185 Contributing
 186 ------------
 187
 188 Bug, feature requests and other issues should be reported to the [GitHub
 189 project]. We accept code and documentation contributions via Pull Requests on
 190 GitHub as well.
 191
 192 - [PSR-2 Coding Standard][] is used by the project. The included test
 193   configuration uses [PHP Code Sniffer][] to validate the conventions.
 194 - Tests are encouraged. Our test coverage isn't perfect but we'd like it to
 195   get better rather than worse, so please try to include tests with your
 196   changes.
 197 - Keep the documentation up to date. Make sure `README.md` and other
 198   relevant documentation is kept up to date with your changes.
 199 - One pull request per feature. Try to keep your changes focused on solving
 200   a single problem. This will make it easier for us to review the change and
 201   easier for you to make sure you have updated the necessary tests and
 202   documentation.
 203
 204
 205 License
 206 -------
 207
 208 Composer Merge plugin is licensed under the MIT license. See the
 209 [`LICENSE`](LICENSE) file for more details.
 210
 211
 212 ---
 213 [Composer]: https://getcomposer.org/
 214 [MediaWiki]: https://www.mediawiki.org/wiki/MediaWiki
 215 [GitHub project]: https://github.com/wikimedia/composer-merge-plugin
 216 [PSR-2 Coding Standard]: https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-2-coding-style-guide.md
 217 [PHP Code Sniffer]: http://pear.php.net/package/PHP_CodeSniffer
 218 [Latest Stable Version]: https://img.shields.io/packagist/v/wikimedia/composer-merge-plugin.svg?style=flat
 219 [License]: https://img.shields.io/packagist/l/wikimedia/composer-merge-plugin.svg?style=flat
 220 [Build Status]: https://img.shields.io/travis/wikimedia/composer-merge-plugin.svg?style=flat
 221 [Code Coverage]: https://img.shields.io/scrutinizer/coverage/g/wikimedia/composer-merge-plugin/master.svg?style=flat
 222 [custom commands]: https://getcomposer.org/doc/articles/scripts.md#writing-custom-commands