www.aleph1.co.uk Git - yaffs-website/blob - vendor/cweagans/composer-patches/README.md

   1 # composer-patches
   2
   3 Simple patches plugin for Composer. Applies a patch from a local or remote file to any package required with composer.
   4
   5 Note that the 1.x versions of Composer Patches are supported on a best-effort
   6 basis due to the imminent release of 2.0.0. You may still be interested in
   7 using 1.x if you need Composer to cooperate with earlier PHP versions. No new
   8 features will be added to 1.x releases, but any security or bug fixes will
   9 still be accepted.
  10
  11 ## Usage
  12
  13 Example composer.json:
  14
  15 ```json
  16 {
  17   "require": {
  18     "cweagans/composer-patches": "~1.0",
  19     "drupal/drupal": "~8.2"
  20   },
  21   "config": {
  22     "preferred-install": "source"
  23   },
  24   "extra": {
  25     "patches": {
  26       "drupal/drupal": {
  27         "Add startup configuration for PHP server": "https://www.drupal.org/files/issues/add_a_startup-1543858-30.patch"
  28       }
  29     }
  30   }
  31 }
  32
  33 ```
  34
  35 ## Using an external patch file
  36
  37 Instead of a patches key in your root composer.json, use a patches-file key.
  38
  39 ```json
  40 {
  41   "require": {
  42     "cweagans/composer-patches": "~1.0",
  43     "drupal/drupal": "~8.2"
  44   },
  45   "config": {
  46     "preferred-install": "source"
  47   },
  48   "extra": {
  49     "patches-file": "local/path/to/your/composer.patches.json"
  50   }
  51 }
  52
  53 ```
  54
  55 Then your `composer.patches.json` should look like this:
  56
  57 ```
  58 {
  59   "patches": {
  60     "vendor/project": {
  61       "Patch title": "http://example.com/url/to/patch.patch"
  62     }
  63   }
  64 }
  65 ```
  66
  67 ## Allowing patches to be applied from dependencies
  68
  69 If you want your project to accept patches from dependencies, you must have the following in your composer file:
  70
  71 ```json
  72 {
  73   "require": {
  74       "cweagans/composer-patches": "^1.5.0"
  75   },
  76   "extra": {
  77       "enable-patching": true
  78   }
  79 }
  80 ```
  81
  82 ## Ignoring patches
  83
  84 There may be situations in which you want to ignore a patch supplied by a dependency. For example:
  85
  86 - You use a different more recent version of a dependency, and now a patch isn't applying.
  87 - You have a more up to date patch than the dependency, and want to use yours instead of theirs.
  88 - A dependency's patch adds a feature to a project that you don't need.
  89 - Your patches conflict with a dependency's patches.
  90
  91 ```json
  92 {
  93   "require": {
  94     "cweagans/composer-patches": "~1.0",
  95     "drupal/drupal": "~8.2",
  96     "drupal/lightning": "~8.1"
  97   },
  98   "config": {
  99     "preferred-install": "source"
 100   },
 101   "extra": {
 102     "patches": {
 103       "drupal/drupal": {
 104         "Add startup configuration for PHP server": "https://www.drupal.org/files/issues/add_a_startup-1543858-30.patch"
 105       }
 106     },
 107     "patches-ignore": {
 108       "drupal/lightning": {
 109         "drupal/panelizer": {
 110           "This patch has known conflicts with our Quick Edit integration": "https://www.drupal.org/files/issues/2664682-49.patch"
 111         }
 112       }
 113     }
 114   }
 115 }
 116 ```
 117
 118 ## Using patches from HTTP URLs
 119
 120 Composer [blocks](https://getcomposer.org/doc/06-config.md#secure-http) you from downloading anything from HTTP URLs, you can disable this for your project by adding a `secure-http` setting in the config section of your `composer.json`. Note that the `config` section should be under the root of your `composer.json`.
 121
 122 ```json
 123 {
 124   "config": {
 125     "secure-http": false
 126   }
 127 }
 128 ```
 129
 130 However, it's always advised to setup HTTPS to prevent MITM code injection.
 131
 132 ## Patches containing modifications to composer.json files
 133
 134 Because patching occurs _after_ Composer calculates dependencies and installs packages, changes to an underlying dependency's `composer.json` file introduced in a patch will have _no effect_ on installed packages.
 135
 136 If you need to modify a dependency's `composer.json` or its underlying dependencies, you cannot use this plugin. Instead, you must do one of the following:
 137 - Work to get the underlying issue resolved in the upstream package.
 138 - Fork the package and [specify your fork as the package repository](https://getcomposer.org/doc/05-repositories.md#vcs) in your root `composer.json`
 139 - Specify compatible package version requirements in your root `composer.json`
 140
 141 ## Error handling
 142
 143 If a patch cannot be applied (hunk failed, different line endings, etc.) a message will be shown and the patch will be skipped.
 144
 145 To enforce throwing an error and stopping package installation/update immediately, you have two available options:
 146
 147 1. Add `"composer-exit-on-patch-failure": true` option to the `extra` section of your composer.json file.
 148 1. Export `COMPOSER_EXIT_ON_PATCH_FAILURE=1`
 149
 150 By default, failed patches are skipped.
 151
 152 ## Difference between this and netresearch/composer-patches-plugin
 153
 154 - This plugin is much more simple to use and maintain
 155 - This plugin doesn't require you to specify which package version you're patching
 156 - This plugin is easy to use with Drupal modules (which don't use semantic versioning).
 157 - This plugin will gather patches from all dependencies and apply them as if they were in the root composer.json
 158
 159 ## Credits
 160
 161 A ton of this code is adapted or taken straight from https://github.com/jpstacey/composer-patcher, which is abandoned in favor of https://github.com/netresearch/composer-patches-plugin, which is (IMHO) overly complex and difficult to use.