Test a Magento patch

This topic discusses how to test patches to your Magento Enterprise Cloud Edition system locally before you push them to the remote server. We strongly recommend you test patches locally so you can identify any issues.

There are two types of patches:

  • General patches

    These patches are provided for all Magento Enterprise Cloud Edition customers in a GitHub repository that’s referenced in your composer.json. We apply these patches automatically during the build phase.

    To install general patches, use composer update, test your system, and push the patches to the remote server.

  • Custom patches

    Custom patches can be provided by Magento to address a specific issue you raised in a Support ticket. Third-party extension developers can also provide a custom patch.

    Copy custom patches to the m2-hotfixes directory and test them on your locally. After successfully testing them, push the patches to the remote server.

Always test a patch your local system, then your integration environment system (that is, the remote Cloud server). Resolve any issues before you patch either staging or production.

Test general patches

General patches are provided for all Magento Enterprise Cloud Edition customers in a repository referenced in your composer.json. We apply patches automatically during the build phase when a patch is available. The procedure discussed in this section enables to you test a patch locally anytime you choose.

The procedure you use is slightly different, depending on the type of environment: integration, staging, or production.

Get started

We recommend you test a patch in the master branch.

  1. Log in to your local development machine, or switch to, the Magento file system owner.
  2. Change to a directory to which the Magento file system owner has write access, such as the web server docroot.
  3. Log in to your project:

    magento-cloud login
    
  4. List your projects:

    magento-cloud project:list
    
  5. If necessary, clone a project.

    magento-cloud project:get <project ID>
    

    Typically, you should clone the project in the web server’s docroot or a Virtual Host docroot.

  6. Change to a project directory.

    For example, cd /var/www/html/magento2

  7. List environments in the project:

    magento-cloud environment:list
    

    magento-cloud environment:list displays environment hierarchies whereas git branch displays does not. If you have any nested environments, use magento-cloud environment:list.

  8. Fetch origin branches:

    git fetch origin
    
  9. Check out an environment:

    magento-cloud environment:checkout <environment ID>
    

    To create a new environment, use magento-cloud environment:branch <environment name> <parent environment ID>

  10. Pull updated code:

    git pull origin <environment ID>
    
  11. Create a snapshot of the environment.

    magento-cloud snapshot:create -e <environment ID>
    

Test a general patch on your local system

To test a general patch on your local system:

  1. On your local system, enter the following commands as the Magento file system owner:

    cd <project root dir>
    magento-cloud environment:checkout master
    git pull origin master
    composer update
    
  2. Apply the patch locally:

    git apply vendor/magento/magento-cloud-configuration/patches/<patch file name>
    
  3. Clean the Magento cache:

    php <Magento project root dir>/bin/magento cache:clean
    

    You can also clean the cache using the Magento Admin.

  4. Thoroughly test your local system to make sure the patch doesn’t have unexpected side-affects.
  5. After testing the patch, push it to the remote server and deploy it:

    git add -A && git commit -m "Apply patch"
    git push origin <branch name>
    

Push a general patch to the staging or production environment

After you’ve successfully tested a patch locally and on your integration environment, you can push the patch to staging or production as follows:

  1. Open an SSH connection to your staging or production server:

    • Staging: ssh -A <project ID>_stg@<project ID>.ent.magento.cloud
    • Production: ssh -A <project ID>@<project ID>.ent.magento.cloud
  2. Enter the following commands:

    <Magento project root dir>/composer update
    
  3. Apply the patch locally:

    git apply vendor/magento/magento-cloud-configuration/patches/<patch file name>
    
  4. Clean the Magento cache:

    php <Magento project root dir>/bin/magento cache:clean
    

    You can also clean the cache using the Magento Admin.

  5. Thoroughly test your local system to make sure the patch doesn’t have unexpected side-affects.
  6. After testing the patch, push it to the remote server and deploy it:

    git add -A && git commit -m "Apply patch"
    git push origin master
    

Test custom patches

Custom patches are provided to specific customers in a Support ticket. Before you continue, make sure the patch file we provided you is available.

The procedure you use is slightly different, depending on the type of environment: integration, staging, or production.

Get started

We recommend you test a patch locally in the master branch.

  1. Log in to your local development machine, or switch to, the Magento file system owner.
  2. Change to a directory to which the Magento file system owner has write access, such as the web server docroot.
  3. Log in to your project:

    magento-cloud login
    
  4. List your projects:

    magento-cloud project:list
    
  5. If necessary, clone a project.

    magento-cloud project:get <project ID>
    

    Typically, you should clone the project in the web server’s docroot or a Virtual Host docroot.

  6. Change to a project directory.

    For example, cd /var/www/html/magento2

  7. List environments in the project:

    magento-cloud environment:list
    

    magento-cloud environment:list displays environment hierarchies whereas git branch displays does not. If you have any nested environments, use magento-cloud environment:list.

  8. Fetch origin branches:

    git fetch origin
    
  9. Check out an environment:

    magento-cloud environment:checkout <environment ID>
    

    To create a new environment, use magento-cloud environment:branch <environment name> <parent environment ID>

  10. Pull updated code:

    git pull origin <environment ID>
    
  11. Create a snapshot of the environment.

    magento-cloud snapshot:create -e <environment ID>
    

Test a custom patch on your local system

To test a custom patch on your local system:

  1. On your local system, enter the following command as the Magento file system owner if you haven’t done so already:

    mkdir <Magento project root dir>/m2-hotfixes
    
  2. Copy the patch file to that directory.
  3. Apply the patch locally:

    cd <Magento project root dir>
    magento-cloud environment:checkout master
    git pull origin master
    git apply <Magento project root dir>/m2-hotfixes/<patch file name>
    
  4. Clean the Magento cache:

    php <Magento project root dir>/bin/magento cache:clean
    

    You can also clean the cache using the Magento Admin.

  5. After testing the patch, push it to the remote server and deploy it:

    git add -A && git commit -m "Apply patch"
    git push origin <branch name>
    

Push a custom patch to a staging or production environment

After you’ve successfully tested a custom patch locally and on your integration environment, you can push the patch to staging or production as follows:

  1. Open an SSH connection to your staging or production server:

    • Staging: ssh -A <project ID>_stg@<project ID>.ent.magento.cloud
    • Production: ssh -A <project ID>@<project ID>.ent.magento.cloud
  2. On your staging or production system, enter the following command if you haven’t done so already:

    mkdir <Magento project root dir>/m2-hotfixes
    
  3. Copy the patch file to that directory.

    We suggest using the following command:

    rsync -azvP <source> <destination>
    

    Options:

    a archive

    z compress

    v verbose

    P partial progress

    For additional options, see the rsync man page.

  4. Apply the patch:

    git apply <Magento project root dir>/m2-hotfixes/<patch file name>
    
  5. Clean the Magento cache:

    php <Magento project root dir>/bin/magento cache:clean
    

    You can also clean the cache using the Magento Admin.

  6. After testing the patch, push it to the remote server and deploy it:

    git add -A && git commit -m "Apply patch"
    git push origin <branch name>