How-to
Apr 9, 2024

How to Use Magento's Upgrade Compatibility Tool

Using Magento's upgrade tool to find issues before you start an upgrade.

N.b: This guide requires PHPStorm

Last year Magento released their upgrade compatibility tool for any users on their Commerce platform. 

Ensuring that your Magento store is kept up to date is vital for many reasons, not least for your PCI compliance. Each upgrade version also comes with a host of performance enhancements, bug fixes and features.

It’s no secret that these upgrades can require substantial planning and effort. The compatibility tool is a powerful tool to help while scoping and estimating an upgrade project. It works by checking all customisations on the Magento instance to see if there are any incompatibilities with the new Magento version. 

In this article, we will walk you through how to use this tool to ensure your upgrades go as smoothly as possible.

First, you need to install. the Magento PHPStorm plugin. This can either be downloaded from the PHPStorm Marketplace or installed from your PHPStorm screen by going to Preferences>Plugins and selecting Magento PHPStorm.

Once installed, you can enable the integration with Magento:

  1. Go to Preferences > Frameworks.
  2. Select the Enable Magento Integration checkbox. See Install PHPStorm plugin topic for more information.

You will also need to provide the following:

  • Adobe Commerce or Magento Open Source installation path
  • Adobe Commerce or Magento Open Source version (for example, 2.4.4)

Next, go to Tools > Configure The Upgrade Compatibility Tool

Here you set values for the Current version, Coming version (the version you will to upgrade to), Path to Analyse (the project absolute path) and the Min Issue Level.

We're now ready to run the report. To do this, go to Tools > Run The Upgrade Compatibility Tool and wait for the execution.

Once it's complete, you will see the output of the tool in the Run tab of PHPStorm.

The tool will also generate two files with the results of the report: a JSON and HTML file.

N.b. currently, PHPStorm stops without generating the files. This is a known issue and a bug report has been created for the issue.

The output of the HTML file will show the following:

At a glance we can see the amount of errors and modules that require upgrade.
The relative size circles give a visual indication of potential concerns

Need a hand?

If you need help with any of your Magento Upgrade needs please get in touch, and we'll be delighted to talk to your about your maintenance needs.

More articles

Browse all posts