How to Create a Custom Patch in Magento 2

Magento Custom Patch Guide

Magento is a powerful eCommerce platform, but sometimes you need to make custom changes to improve its functionality or fix issues. Instead of directly modifying core files (which is risky), you can create a custom patch! In this blog post, I’ll guide you through the process in simple steps.

What is a Patch in Magento?

A patch is a small file that contains code changes. It helps you apply fixes or improvements without changing the original code directly. This makes your site more organized and easier to maintain, especially when updating Magento in the future.

Why Should You Use Patches?

• Keeps your code clean and organized.
• Prevents losing changes during updates.
• Makes collaboration easier.
• Easy to apply and revert.

Step 1: Install the Patch Package

Magento uses a Composer package to manage patches. First, install it with this command:

composer require cweagans/composer-patches

This tool helps you apply patches smoothly.

Step 2: Update the composer.json File

Now, let’s tell Magento to use the patch system. Open your Magento project’s composer.json file and add the following lines under the "extra" section:

{
    "extra": {
        "magento-force": "override",
        "patches-file": "composer-patches.json",
        "composer-exit-on-patch-failure": true
    }
}

This sets up Magento to handle patches correctly.

Step 3: Create the Patch File

Now comes the fun part — creating your patch!

1. Copy the Original File

Let’s say you want to modify system.js in the PayPal Braintree module. First, make a backup copy of the original file:

cp vendor/paypal/module-braintree-core/view/adminhtml/web/js/system.js vendor/paypal/module-braintree-core/view/adminhtml/web/js/systemUpdate.js

2. Make Your Changes

Open systemUpdate.js and apply the changes you want. After editing, you’ll create the patch file.

3. Generate the Patch

Run this command to create your patch file:

diff -u vendor/paypal/module-braintree-core/view/adminhtml/web/js/system.js 
        vendor/paypal/module-braintree-core/view/adminhtml/web/js/systemUpdate.js > patches/Fix_Store_Config_Issue.patch

4. Update the Patch File

Open the patch file (Fix_Store_Config_Issue.patch) and replace this part:

+++ vendor/paypal/module-braintree-core/view/adminhtml/web/js/systemUpdate.js

with:

+++ vendor/paypal/module-braintree-core/view/adminhtml/web/js/system.js

This ensures the patch updates system.js directly.

Step 4: Organize Your Patch

Create a new folder called patches in your Magento root directory and place your patch file inside it:

mkdir patches
mv Fix_Store_Config_Issue.patch patches/

Step 5: Add Patches to Composer

Create a new file called composer-patches.json at the Magento root and add this content:

{
  "patches": {
    "paypal/module-braintree-core": {
      "Fix Store Configuration Tab Issue": "patches/Fix_Store_Config_Issue.patch"
    }
  }
}

In this file:

• Module Name: Use the correct package name from the module’s composer.json (e.g., paypal/module-braintree-core).
• Patch Path: Ensure the path to the patch file is correct.

Step 6: Apply the Patch

Finally, apply the patch with this command:

composer install

If everything is set up correctly, Magento will apply your patch automatically!

Sample Patch File for Magento

Let’s take a look at a sample patch file. In this example, we’re fixing a PayPal Braintree module issue by updating the system.js file.

Fix_Store_Config_Issue.patch

--- a/vendor/paypal/module-braintree-core/view/adminhtml/web/js/system.js   2023-01-25 22:36:53.170211591 +0530
+++ b/vendor/paypal/module-braintree-core/view/adminhtml/web/js/system.js   2022-09-12 14:45:06.000000000 +0530
@@ -125,7 +125,7 @@
        let messagingLogoPosition = $('.' + location + '-messaging-logo-position').val();
        let messagingTextColor = $('.' + location + '-messaging-text-color').val();
 
-       locations.each(function (loc) {
+       $.each(locations, function (loc) {
            buttonTypes.each(function (type) {
                $('[data-ui-id="select-groups-braintree-section-groups-braintree-groups-braintree-paypal-groups-styling-groups-button-' + loc + '-groups-button-location-' + loc + '-type-' + type + '-fields-button-location-' + loc + '-type + '-show-value"]').val(buttonShowStatus).click();
                $('[data-ui-id="select-groups-braintree-section-groups-braintree-groups-braintree-paypal-groups-styling-groups-button-' + loc + '-groups-button-location-' + loc + '-type-' + type + '-fields-button-location-' + loc + '-type + '-layout-value"]').val(buttonLayout).click();
@@ -150,7 +150,7 @@
        let locations = ['checkout', 'productpage', 'cart'], buttonTypes = ['paypal', 'paylater', 'credit'];
        let buttonShowStatus = 1, buttonLayout = 'horizontal', buttonTagline = 0, buttonLabel = 'paypal', buttonColor = 'gold', buttonShape = 'rect', buttonSize = 'responsive';
 
-       locations.each(function (loc) {
+       $.each(locations, function (loc) {
            buttonTypes.each(function (type) {
                $('[data-ui-id="select-groups-braintree-section-groups-braintree-groups-braintree-paypal-groups-styling-groups-button-' + loc + '-groups-button-location-' + loc + '-type-' + type + '-fields-button-location-' + loc + '-type + '-show-value"]').val(buttonShowStatus).click();
                $('[data-ui-id="select-groups-braintree-section-groups-braintree-groups-braintree-paypal-groups-styling-groups-button-' + loc + '-groups-button-location-' + loc + '-type-' + type + '-fields-button-location-' + loc + '-type + '-layout-value"]').val(buttonLayout).click();

Understanding the Patch:

• --- a/: Refers to the original file path.
• +++ b/: Refers to the updated file path.
• -: Shows the lines being removed.
• +: Shows the lines being added.
• @@: Indicates the line numbers where changes occur.

Once your patch file is ready, add it to the patches folder and reference it in composer-patches.json to apply the changes.

Conclusion

Creating custom patches in Magento is a smart and organized way to apply changes without directly modifying core files. This method keeps your code cleaner and makes it easier to manage updates, ensuring your customizations aren’t overwritten when upgrading Magento or third-party modules.

By following these steps — installing the patch tool, configuring Magento, creating the patch, and applying it with Composer — you’ve set up a workflow that’s both efficient and reliable. Not only does this save you time in the long run, but it also helps maintain a professional development process.

Embrace the power of patches and take control of your Magento customizations with confidence. Happy patching!