Most of our readers know that Magento has security, cloud, quality, and custom patches that can be installed to fix particular website issues on Adobe Commerce or Magento Open Source platforms.
In this post, we’ll speak about the tool released by Adobe to apply quality patches and work with them – Quality Patches Tool (QPT). In addition, we’ll describe how to use QPT on different Magento platforms and the existing best practices.
Table of Contents:
Overview.
Quality Patch is a fix provided by Adobe Commerce support or the Magento Open Source community to resolve a particular issue/bug in a core Magento functionality. Quality patch is available for certain Adobe Commerce/Magento Open Source versions and in most cases, it is included in the newest release.
Quality Patches Tool or QPT allows you to apply, revert, and view general information about quality patches available for your installed version of Adobe Commerce (for both on-premise and cloud infrastructure) and Magento Open Source.
The list of all available quality patches can be found in the Adobe Commercial DevDocs.
Please note that the Quality Patches Tool is for quality patches only.
Security patches can be found in the Magento Security Center.
Installation a quality patch
QPT is delivered as a composer package. So, for Adobe Commerce on cloud infrastructure, the package is included in the ECE-Tools package (available from 2002.1.3 ECE-Tools version).
To install the latest QPT package, use:
composer update magento/ece-tools --with-dependencies
For the Adobe Commerce (on-premise) & Magento Open Source QPT can be installed via the next command:
composer require magento/quality-patches
Applying quality patches
To apply a quality patch on Adobe Commerce on cloud infrastructure use QUALITY_PATCHES variable in the .magento.env.yaml file:
stage:
build:
QUALITY_PATCHES:
- MCTEST-1002
- MCTEST-1003
You need to commit your changes to .magento.env.yaml and provided in QUALITY_PATCHES patches will be installed automatically to cloud instances within a deployment.
Before pushing quality patches to cloud instances, you should apply patches manually in a local environment and test them before you deploy.
To apply patches to a local environment, run the next in your project root:
vendor/bin/ece-patches apply
and do not forget to clear cache after that:
bin/magento cache:clean
Keep in mind that ECE-Tools applies patches in the following sequence:
Test the patches, and make any necessary changes to custom patches if needed.
To install a quality patch on Adobe Commerce (on-premise) & Magento Open Source run the following:
vendor/bin/magento-patches apply MCTEST-1002 MCTEST-1003
Also, please don’t forget to clear the cache after applying patches to see changes in the Magento application.
QPT controls quality patch installation and does not allow to install a patch twice. See the example below:
We recommend using the post-install-cmd command event in composer.json to install QPT patches on projects with non-cloud infrastructure.
Example, of post-install-cmd command event in composer.json:
"scripts": {
"post-install-cmd": [
"bash post-install.sh"
]
}
A content of post-install.sh bash script is:
#!/bin/bash
appliedPatches='MCTEST-1002 MCTEST-1003'
if [ "$appliedPatches" ]
then
./vendor/bin/magento-patches apply $appliedPatches
fi
Reverting quality patches
The reverting process is very simple.
Adobe Commerce on cloud infrastructure:
Remove a necessary patch from the QUALITY_PATCHES in .magento.env.yaml.
Adobe Commerce (on-premise) & Magento Open-Source:
vendor/bin/magento-patches revert MCTEST-1002 MCTEST-1003
To revert all quality patches:
vendor/bin/magento-patches revert —-all
As during a patch installation, QPT also controls a revert operation and won’t allow reverting a patch twice or reverting a patch that is not applied.
See the example below:
Checking the patch status
QPT provides an ability to check the statuses of all quality patches.
You may use one of the following commands to check the statuses of quality patches for Adobe Commerce and Magento Open-Source in shell:
vendor/bin/ece-patches status
vendor/bin/magento-patches status
In Adobe Commerce on cloud infrastructure, you may also check the statuses of quality patches in the Site-Wide Analysis Tool (SWAT):
Logging of patching operations
The Quality Patches Tool logs all operations in the <Magento_root>/var/log/patch.log file.
Example of a log:
Recommendations when using a Quality Patches Tool
- If you see an issue in your Adobe Commerce or Magento Open Source project please check QPT for a quality patch.
- We do not recommend using the QPT to apply large numbers of patches because it increases the complexity of project code, which makes upgrading to a new version of Adobe Commerce or Magento Open Source more difficult.
- We strongly recommend testing all patches in a staging or development environment before deploying to production.
- Consider keeping a list of applied patches in a separate location. You might need to re-apply some of them after upgrading to a new version of Adobe Commerce or Magento Open Source.
- After upgrading to a new version of Adobe Commerce or Magento Open Source, you must make a revision of installed patches and re-apply patches if the patches are not included in the new version.
Quality Patches Tool and Magento community
Quality Patch, which was created by the Magento community, is not verified by the Adobe QA team. There is a video guide about quality patch creation by contributors.