Patching Magento 2 Code

patching_magento2_app_code.md

To patch code in Composer modules

1. composer require cweagans/composer-patches
2. Create your patch file as normal (referencing the paths to file in /vendor) and put it in a '.patches' folder at the top level of your code base.
3. Edit composer.json to apply the patch(es) as below (this goes at the first level of composer.json) :

    "extra": {
        "magento-force": "override",
        "enable-patching": true,
        "patches-file": "composer.patches.json"
    },

4. Create composer.patches.json with content as per below example:

{
  "patches": {
    "magento/framework": {
      "MAG231-SALESRULE-FIX-UPG": ".patches/MAG231-SALESRULE-FIX-UPG.patch"
    },
    "magento/module-checkout-agreements": {
      "MAGFIX_231_AGREEMENT_CONFIG": ".patches/MAGFIX_231_AGREEMENT_CONFIG.patch"
    }
}

To patch code in /app/code

1. Create your patch file as normal (referencing the paths to file in app/code/) and put it in a '.patches' folder at the top level of your code base.
2. Edit composer.json to apply the patch(es) as below (this goes at the first level of composer.json) :

{
<other json here>
    "scripts": {
        "post-update-cmd": [
            "patch -p1 < .patches/app_code_some.patch",
            "patch -p1 < .patches/app_code_another.patch"
        ],
        "post-install-cmd": [
            "patch -p1 < .patches/app_code_some.patch",
            "patch -p1 < .patches/app_code_another.patch"
        ]
    }
}

Cool tip on how to apply patches to app/code files (as an alternative to the approach I suggested here).

Regarding your first "To patch code in Composer modules" section:

When using composer-patches, I like to include composer-exit-on-patch-failure in the extra object, as it results in a non-zero exit code if a patch fails to apply. This is helpful when using a deployment tool like Capistrano, as deployment will fail and you can investigate the issue.

{
    "extra": {
        …
        "composer-exit-on-patch-failure": true
    }
}

@cmtickle - How do you prevent Composer from outputting an error when you run composer update *** or composer install multiple times on a local development environment? Because once the patch is applied the first time, I expect it will output an error any subsequent times the patch command is run.

@erikhansen reset the patched files to the unpatched (version controlled) files then composer install/update as normal.

@cmtickle Got it. Considering that I run composer install and composer update **** dozens/hundreds of times across the course of an M2 project, I think that would get old after a while. :) But to each their own!

@erikhansen I guess once you're confident the patches apply you could just use the --no-scripts: argument for composer to avoid applying the patches again?

Remembering to reset the original unpatched version or using --no-scripts argument is not sustainable, not long term, not across multiple projects. The patch module should keep track of the patches applied and skip them. My 2c worth.