Apply patches in Magento 2
MaartenPatches to your installed Adobe Commerce application is delivered by Cloud Patches for Commerce and the Quality Patches tool
- Patches with critical fixes are delivered by Cloud Patches for Commerce delivers
- The patches which are optional and have low-impact quality fixes are delivered by Quality Patches. It does not contain backward-incompatible changes.
Both packages improve the integration of all Adobe Commerce versions with the Cloud environment by delivering critical, optional and custom fixes. Visit Available Patches in the Software Update Guide to review a full list of released patches.
While deploying the changes in a remote environment, ece-tools uses magento/magento-cloud-patches and magento/quality-patches to check pending patches. If there are any pending patches, it automatically applies them in the following order:
- First it applies all required Magento patches that are included in the Cloud Patches for Commerce package.
- Second, it applies optional Magento patches that are included in the Quality Patches Tool.
- Last, it applies custom patches in the /m2-hotfixes directory.
Note: The required patches are applied when you deploy your project for the next time (When you update ece-tools or the Cloud Patches for Commerce package). If you want to deploy them immediately, use ece-patchesapply CLI command and redeploy your Cloud environment. Skipping required patches is not allowed during the deployment process.
Prerequisites
Create an active branch from the integration environment and checkout the new branch to your local workstation before beginning an upgrade or a patching process. It helps to avoid interference with your work in progress.
Remember that in order to apply the latest patches, the latest version of ece-tools must be installed. The minimum required version of ece-tools is 2002.1.2.
View available patches and status
Use this command to view the list of available individual patches
$ php ./vendor/bin/ece-patches statusSample response
///////////////////////////////////
The status table contains the following types of information:
- Type:
- Optional: For both Adobe Commerce and Magento Open Source, patches from the Quality Patches Tool and the Magento Cloud Patches package are optional. If you’re using Adobe Commerce on cloud infrastructure, all patches are optional too.
- Required: For Cloud customers, all patches from the Cloud Patches for Commerce package are required
- Deprecated: When the individual patch is marked as deprecated, it is recommended to revert it if you’ve applied it. Once reverted it won’t appear in the status table.
- Custom—It includes all patches from the ‘m2-hotfixes’ directory.
- Status:
- Applied—The patch has been applied.
- Not applied—The patch has not been applied.
- N/A—The status of the patch cannot be defined due to conflicts.
- Details:
- Affected components—The list of affected modules.
- Required patches—The list of required patches (in most cases these patches are dependencies).
- Recommended replacement— These patches are the recommended replacements for a deprecated patch.
Apply a patch in a local environment
If you want to test patches before you deploy them, you can apply them manually in a local environment
To apply individual patches in a local development environment:
- Go to the .magento.env.yaml file and Add the ‘QUALITY_PATCHES’ variable. Now list the required patches underneath.
stage:
build:
QUALITY_PATCHES:
– MCTEST-1002
– MCTEST-1003
- Apply the patches from the project root using this command–
$ php ./vendor/bin/ece-patches applyWhen you use ece-patches apply command, patches are applied in the following order:
- Required patches
- Optional individual patches
- Custom patches from the /m2-hotfixes directory
- Clear the cache using command–
| php ./bin/magento cache:clean |
- Test the patches, and if required make necessary changes to custom patches.
Apply a patch in a Cloud environment
Before deploying patches to the Production environment, test all patches in a Staging environment or Integration
To apply patches in a Cloud environment:
- Go to the .magento.env.yaml file and Add the ‘QUALITY_PATCHES’ variable. Now list the required patches underneath.
stage:
build:
QUALITY_PATCHES:
– MCTEST-1002
– MCTEST-1003
Note: If the patches are not included in the new version, you’ll have to re-apply them After upgrading to a new version.
- Commit and push the updated .magento.env.yaml file.
$ git commit -m “Apply patch”
$ git push origin <branch-name>
Apply a custom patch
When you deploy, ece-tools applies all Adobe patches and any custom patches that you add to the /m2-hotfixes directory in the project root.
All patch file names must end with the .patch extension.
To apply and test a custom patch on a Cloud environment:
- Create a directory named m2-hotfixes in the project root if it does not exist
$ mkdir m2-hotfixes- Go to /m2-hotfixes directory and copy the patch.
- Add, commit, and push code changes.
$ git add -A
$ git commit -m “Apply patch”
$ git push origin <branch-name>
Apply patches to a non-Cloud project
For Magento Open Source and Adobe Commerce projects, use the Quality Patches Tool
Revert a patch in a local environment
Using the ece-patches CLI, you can revert all previously applied patches in a local development environment.
Run this command in CLI to revert all applied patches.
php ./vendor/bin/ece-patches revertThis command reverts all patches in the following order:
- First it reverts all applied custom patches from the /m2-hotfixes directory.
- Second it reverts all applied optional individual patches.
- And last it reverts all applied required patches.
Logging
The Quality Patches Tool logs all operations to the <Project_root>/var/log/patch.log file.
That’s all about applying patches in Magento 2.