4.1.0 Release
This release contains two great features:
- The Run Configuration integration for the Adobe Commerce Upgrade Compatibility Tool
- The built-in Upgrade Compatibility Tool (MVP)
Run Configurations are used to run internal and external processes from within IntelliJ Platform based products. To get familiar with the concept of a Run Configuration refer Run/Debug Configuration section of IntelliJ IDEA Web Help.
The Upgrade Compatibility Tool Run Configuration is a GUI for the Upgrade Compatibility Tool.
The UCT Run Configuration provides the ability to configure UCT installed for the project via composer. If the UCT was installed separately (outside the project), such UCT executable can also be chosen in the dedicated Run Configuration. In the case when the UCT was not found in the current project, the corresponding message is shown with the link that provides the ability to download and install the UCT for the current project. Be aware, that the UCT is an Adobe Commerce feature, so to install it you should have your Adobe Commerce license key.
The UCT Run Configuration template can be found in the Run/Debug configurations dialog -> Add New Configuration -> Upgrade Compatibility Tool:
The UCT Run Configuration template has the next view:
These are the main components of the configuration template:
-
UCT Executable - path to the UCT executable script which is located by the path
bin/uctfrom the UCT source root directory, required field - Project Root - current PHPStorm Project root directory, it is determined automatically, required field
- Path To Analyse - this field allows you to restrict the search to the specified folder, optional field
- Coming Version - the Adobe Commerce targeted version, required field
- Min Issue Level - minimum issue level to show in the report. Default is [WARNING], optional field
- Ignore Current Version Compatibility Issues - use this option when you do not want to include known critical issues, errors and warnings in your Upgrade Compatibility Tool report, optional field
- Message that appears if the UCT could not be found for the current PHPStorm Project
- Link to install the UCT for the current PHPStorm Project.
After the Run Configuration template is configured it can be used to easily run the tool via a single click whenever needed.
The UCT installation for the current project (if composer wasn't authenticated with the Adobe Commerce repository):
The composer would request the auth keys if they can not be found, for more information refer to the official documentation.
After providing your auth keys you will get the same output as for the authenticated users:
To run the UCT click on the Run 'UCT Run' green button:
The results of UCT execution is displayed in the console including handy navigation to the compatibility issues in the code.
The output of the tool is displayed in the PHPStorm console with the ability to click on the references to:
- navigate to the code that has an issue
- navigate to the issue code description on the DevDocs page
- navigate to the report file
The built-in Upgrade Compatibility Tool aims to achieve the same issues coverage as original Adobe Commerce Upgrade Compatibility Tool. There are issues that covered by this MVP version:
| Code | Name |
|---|---|
| 1131 | extending from @deprecated class |
| 1132 | importing @deprecated class |
| 1332 | importing @deprecated interface |
| 1134 | using @deprecated class |
| 1334 | using @deprecated interface |
| 1234 | using @deprecated constant |
| 1534 | using @deprecated property |
| 1235 | overriding @deprecated constant |
| 1535 | overriding @deprecated property |
| 1337 | inherited from @deprecated interface |
| 1338 | implemented @deprecated interface |
| 1439 | call @deprecated method |
Complete list of inspections that are already available in the original tool can be found by the following link.
This feature can be used in three different ways from the user's point of view:
- run compatibility inspections in a run tool window with the familiar output as in the original Adobe Commerce Upgrade Compatibility Tool
- run inspections in a real time in the files that are opened in the editor (default)
- run inspections manually through the user interface on the selected scope of files (default)
It was developed with an aim to use IntelliJ IDEA in most effective way. So, inspections that are running during
the code analysis can alternatively be enabled in the inspections settings
Preferences -> Editor -> Inspections -> UCT:
It allows you to see the problematic code just in real time without running it intentionally during code writing or even files visiting. The result of the real time inspection is most suitable for using during development to be always compatible with the future versions:
The second cool IntelliJ IDEA tool under which we adapted our code by reusing Inspections feature of it is running inspections through special action
Code -> Inspect Code or just open context menu under target directory to allow IntelliJ IDEA populates path to analyse for you automatically:
By calling Inspect Code action from the context menu we have Inspection Scope populated for us automatically. The last thing to configure here is Inspection Profile. By default, here will be the Project Default profile with all inspections that are not connected to our goal.
So you can just create new profile with the only UCT inspections enabled (more about that read here):
For this inspection type you don't need to have UCT inspections enabled for your project. The result of this inspection is most suitable for code refactoring during problematic code elimination:
The most powerful inspection type is the execution of compatibility inspections in a run tool window with the familiar output as in the original Adobe Commerce Upgrade Compatibility Tool.
Advantages from using this one:
- all problems gathered in one place
- there are navigations to the problem files, stored report in a json format, link to the web page with detailed description of all the error codes
- this report can be easily used from the merchant, management or agencies sides
- there is a complexity score that helps compare the upgrade complexity from practice side for agencies
Before using it you should configure the built-in UCT in the similar way as the CLI Run Configuration.
All fields are described above in the Upgrade Compatibility Tool Run Configuration section and even more detailed
in the official documentation.
Go to the UCT configuration dialog Tools -> Configure The Upgrade Compatibility Tool and configure it as needed:
Right after that you can run this tool in any time you need that Tools -> Run The Upgrade Compatibility Tool:
For this inspection type you don't need to have UCT inspections enabled for your project, but it is more comfortable to see visually the problems in the file after navigating to it.
Keep in mind, that for all inspection types the target Magento version (coming version) is configured
in the built-in UCT configuration dialog Tools -> Configure The Upgrade Compatibility Tool.
This also applicable for other selected configurations on the screenshot below:
