PHP Series: How to Use a Composer Patch

What is a patch?

The patch is a program that updates text files according to instructions in a separate file called a patch file. The patch file (also called a patch for short) is a text file that consists of a list of differences and is produced by running the related diff program with the original and updated file as arguments. Updating files with a patch is often referred to as applying the patch or simply patching the files.

How do patches work?

Patch files are text files that note the following:

• The file(s) to be changed
• The line number to begin the change and the number of lines to be changed
• The new code to swap in.

How to create a custom patch?

Think twice before creating a patch, as there are better ways to customize functionality. Try implementing your task in other ways, e.g., by creating a plugin.

1. Create a patches/composer directory in your local project
2. Identify the GitHub commit or pull request to use for the patch. This example uses the 2d31571 commit linked to Magento 2 GitHub issue #6474
3. Append the .patch or the .diff extensions to the commit URL
4. Save the page as a file in the patches/composer directory. For example, github-issue-6474.diff
5. Edit the file and remove app/code/<VENDOR>/<PACKAGE> from all paths so that they are relative to the vendor/<VENDOR>/<PACKAGE> directory.

The following example shows the previously mentioned diff file after removing all instances of app/code/<VENDOR>/<PACKAGE>:

diff --git a/view/frontend/web/js/view/payment/iframe.js
 b/view/frontend/web/js/view/payment/iframe.js

index c8a6fef58d31..7d01c195791e 100644
--- a/view/frontend/web/js/view/payment/iframe.js
+++ b/view/frontend/web/js/view/payment/iframe.js
@@ -154,6 +154,7 @@ define(
              */
              clearTimeout: function () {
                  clearTimeout(this.timeoutId);
                  this.fail();
                  return this;
            },

How to apply patches using Composer?

1. Open your command line application and navigate to your project directory
2. Add the cweagans/composer-patches plugin to the composer.json file: composer require cweagans/composer-patches (Magento now uses the Quality Patch Tool)
3. Edit the composer.json file and add the following section to specify:
   • Module: “magento/module-payment”
   • Title: “MAGETWO-56934: Checkout page freezes when ordering with Authorize.net with invalid credit card”
   • Path to patch: “patches/composer/github-issue-6474.diff”.

"extra": {
      "composer-exit-on-patch-failure": true,
      "patches": {
          "magento/module-payment": {
              "MAGETWO-56934: Checkout page freezes when ordering with Authorize.net with invalid credit card": "patches/composer/github-issue-6474.diff"
          }
      }
  }

You must create multiple patch files targeting multiple modules if a patch affects numerous modules.

4. Apply the patch. Use the -v option only if you want to see debugging information: composer -v install
5. Update the composer.lock file. The lock file tracks which patches have been applied to each Composer package in an object: composer update --lock.

Warning! If line endings do not match the patch and your files, the patching won’t work. This is a silent error, so check the line endings if something goes wrong.

Was this article helpful? There’s more where this came from! Browse our tech category in the blog, or contact our team directly!

Share on: