Running the Upgrade Compatibility Tool through the Magento PHP Storm Plugin

Marc Ginesta · ‎02-17-2022

As a developer for Adobe Commerce or Magento Open Source, you may already be aware of the Magento plugin for PHP Storm — currently one of the most popular PHP IDEs. We’re excited to announce that the Adobe Commerce Upgrade Compatibility Tool is now integrated with the plugin, which will make your future upgrades much easier and faster to analyse.

What is the Upgrade Compatibility Tool?

The Upgrade Compatibility Tool is a command line tool that checks an installed Adobe Commerce customised instance against a specific target version by analysing all modules and code installed. It scans the code and evaluates its compatibility with any target version, looking for incompatibilities, such as deprecated API usages or code references that might have been removed in the target version.

At the end, the tool provides a report of all incompatibilities and lists the files that need to be adjusted to be compatible with the target version. A sample report is pictured below.

By integrating this tool with the Magento PHP Storm plugin, compatibility issues can be avoided during the development phase.

The built-in Upgrade Compatibility Tool aims to achieve the same issues coverage as the original Adobe Commerce Upgrade Compatibility Tool, while providing a better user experience and a more developer-friendly interface.

How do you install the plugin?

You can download the plugin from the PHP Storm Marketplace.

Alternatively, you can look for it and install it directly to your PHP Storm through Preferences > Plugins.

After the installation, you need to enable the Adobe Commerce integration through Preferences > PHP > Frameworks.

How do you use the plugin?

The Magento PHP Storm plugin has plenty of useful functionalities that will allow you to speed up your routine operations and simplify tedious processes. The Upgrade Compatibility Tool functionality of the plugin can be used in three different ways:

Run compatibility inspections in a run tool window
Run inspections in real-time on the files that are opened in the editor
Run inspections manually through the user interface on the selected scope of files

Let’s take a deeper dive into each one of these capabilities.

1. Run compatibility inspections in a run tool window

This is the most complete inspection type. Before using it, you should configure the built-in Upgrade Compatibility Tool to perform the inspection.

Go to the configuration dialog (found under the Tools > Configure The Upgrade Compatibility Tool) so you can set it up according to your needs.

You need to provide the current version, target version, path to analyse, and minimum issue level. When this is done, you can run this tool at any time that you require, by using Tools > Run The Upgrade Compatibility Tool.

The output is similar to the output from the original Adobe Commerce Upgrade Compatibility Tool. You can easily navigate through the files by clicking the link and jumping to the specific line to fix whatever is needed to be compatible with the target version.

2. Run inspections in real-time

First, you need to configure the Inspections through your PHPStorm preferences (Preferences > Editor > Inspections > UCT). We recommend creating a separate profile used only to inspect the Upgrade Compatibility Tool issues and skip other types of inspections.

Note that there are three types of inspections covered by this tool:

Deprecation (severity level: WARNING)
API coverage (severity level: ERROR)
Existence (severity level: CRITICAL)

For this new profile, simply enable the checks under UCT.

When we apply and save changes, the code will be highlighted when there are issues of any type. Then, when you hover your mouse over these highlighted pieces of code, a tooltip displays the associated error in a format that is suitable for developers.

3. Run inspections manually

In this case, you need to select the scope of the inspection. You can do so through the tree view of the project.

Right-click any file or folder and then, from the displayed menu, select Inspect code....

This action opens a dialog, where you are prompted for the inspection profile. As previously mentioned, we recommend using a separate profile to inspect the UCT issues.

Click OK to run the inspection. This time, instead of terminal output, you will get an actual list in a tree format that allows you to display the files and errors in the selected scope. The result of this inspection is suitable for code refactoring when eliminating problematic code.

Bonus: Run/Debug Configurations

Finally, the Magento PHP Storm plugin provides a way to run the Upgrade Compatibility Tool using the Run/Debug Configurations feature from PHPStorm.

The Run Configuration is a Graphical User Interface for the tool.

Remember that you need to have the Upgrade Compatibility Tool installed in your system, and you must have the Adobe Commerce license keys to install it. You can find more details about the installation process in the Upgrade Guide.

The Upgrade Compatibility Tool Run Configuration template is at the PHPStorm plugin menu, under Run/Debug Configurations, you need to Add New Configuration and choose Upgrade Compatibility Tool.

In this template, you are asked to provide the details to run the Upgrade Compatibility Tool. At a minimum, you need to set up:

The Path where the Upgrade Compatibility Tool executable script is installed
The Project root where the Adobe Commerce instance is located
The Path to analyse, which by default it is using the root directory
The Adobe Commerce target version
The minimum issue level to show in the report

You could also setup the option to Ignore Current Version Compatibility Issues by clicking the appropriate checkbox. Pictured above (item 6).

In case you do not have the Upgrade Compatibility Tool installed in your system, a message is displayed with a link to download it. Pictured above (items 7 and 8).

When these changes are saved, click Run UCT to run the analysis. At the bottom of your PHPStorm terminal, the progress is displayed.

The results are displayed in the console, including a summary and handy references to the compatibility issues found. Navigate to where issues are found by simply clicking on the file links.

Note that at the bottom of the report, you are provided with JSON and HTML reports. Open the generated HTML report in your browser to better visualise the report and view diagrams of detected issues by severity.

The diagrams included show:

The modules by issue severity
The files by issue severity
The modules that have more backward-incompatible changes

For additional information on the Upgrade Compatibility Tool, visit the following resources:

We will continue to make improvements to the Upgrade Compatibility Tool to best serve developer needs. As you test the tool, we encourage you to provide feedback by filling out this survey. In addition, you can contact us via the #upgrade-compatibility-tool Slack channel should you have any questions.