Using the Upgrade Compatibility Tool on PHP Storm

Transcript

Hello everybody. I am Marc Ginesta from the Iberian Lynx Team. Amongst other projects, we are responsible for developing the upgrade compatibility tool.

This tool also known as UCT is a common line tool that checks another commerce customized instance against a specific version by analyzing all models and code installed. The purpose of this tool is to provide a list of issues, identifying warnings, errors, and critical errors that must be addressed if you want to perform and upgrade on your current Adobe Commerce instance. Basically, it scans the code and evaluates its compatibility to any target version. Looking for incompatibility, such as code references that might have been removed in the target version or duplicated API usages. At the end, the tool provides a report of all the issues in the custom modules listing those files that need to be adjusted to be compatible with the upcoming Adobe Commerce version. But we wanted to take this analysis even one step further. That’s why we decided to introduce UCT as part of the Magento 2, PhpStorm plugin. This way we can avoid compatibility issues during the development phase. You just need to retrieve this plugin from the PhpStorm marketplace, configure it accordingly and you will be able to run this analysis from the PhpStorm IDE.

The built-in upgrade compatibility tool aims to achieve the same issues coverage as the original Adobe Commerce UCT.

This plugin can be used in three different ways. First, run the compatibility inspections in a run tool window. Second, run the inspections in real time, on the files that are open in the editor. And third, run the inspections manually through the user interface on the selected scope of files. Let’s check them out. The most powerful inspection type is the execution of compatibility inspections in a run through window. Before using it, you should configure the built-in upgrade compatibility tool to perform the inspection. You need to provide the current version, common version, path to analyze and minimum issue level.

Once this is done, you will be able to run this tool at any time you require by using tools to run the upgrade compatibility tool. As previously mentioned, the output is really similar to the output from the original Adobe Commerce UCT. You can easily navigate through the files by clicking the link and jumping to the specific line in order to fix whatever is needed to be compatible with the target version. This seems really useful, right? Then let me show inspections in real time. You need to configure the UCT inspections through your PhpStorm preferences, go to editor inspections. To do so, I will create a separate profile just to inspect the UCT issues.

Once I have this profile ready, I will simply enable the checks for the UCT. Know that there are three types of inspections covered by this tool: API, Duplication and Existence.

Once we apply and safe changes, the code would be highlighted when there are any kind of issues. Now, when you are most covering this highlighted pieces of code, a tool tip is showing up indicating the associate error. This way would be more suitable for developers.

And let’s check out the third way to inspect code which is running inspections manually. You just need to select the scope of the inspection, either a file or a folder. Imagine that we want to check out this folder. Then, right click and select inspect code.

You will be asked for the inspection profile. In this case, let’s choose the one previously created and click okay to run the inspection. This time, instead of a terminal output, you will get an actual list that allows us to display the files and errors in the selected scope. The result of this inspection is more suitable for code refactoring when eliminating problematic code.

Finally, this Magento PhpStorm plugin provides a way to run UCT using the run configurations feature from PhpStorm. The run configuration is basically a graphical user interface for UCT. Remember that you need to download UCT separately and you need to have the Adobe Commerce license keys to install it.

The upgrade compatibility tool run configuration template is located in the PhpStorm plugin menu and to run back 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 least, you need to set up the path where the user executor or script is installed, the project route where the other commerce instance is located. The path to analyze which by default, it’s using the route directory the other commerce target version and the minimum issue level to show in the report.

Once these changes are safe, click the button run UCT to run the analysis.

At the bottom of your PhpStorm, a terminal is open showing the progress. The results are displayed in the console including a summary and handy references to the compatibility issues in the code. If you just click this once, you will navigate to the file as we previously saw in this video.

See, that you are provided with reports in different formats, such as JSON and HTML. Open the generated HTML report in your browser to check it more in depth. As you will notice, it contains the same summary and the list of issues splitted by severity, but with a nicer look and feel.

Apart from that, different diagrams are provided showing the modules by issue severity files, by issue severity and the modules with more backwards incompatible changes.

And that’s all, I hope you like the video. Please refer to the project and documentation pages for any questions you may have. Thank you very much for your attention. -