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 |
A 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 real time, on 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 the 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 file viewing. The result of the real time inspection is most suitable for use during development, to be always compatible with future versions:
The second IntelliJ IDEA tool that we can use for running UCT inspections is called Inspect Code. It is available under menu item
Code -> Inspect Code. Also, you can open a context menu under the target directory that allows IntelliJ IDEA to populate the path to analyse for you automatically:
By calling the Inspect Code action from the context menu, the Inspection Scope will be populated for us automatically. The last thing to configure here is Inspection Profile. By default, there will be the Project Default profile with all inspections that are not connected to our goal.
You can create a new profile with the only UCT inspections enabled (for further information read here):
For this inspection type you do not need to have UCT inspections enabled for your project. The result of this inspection is most suitable for code refactoring when eliminating problematic code:
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 inspection:
- all problems are gathered in one place
- there are links to the problem files, a stored report in json format, links to the web page with detailed descriptions of all the error codes
- this report can be easily used from the merchant, management or agency side
- there is a complexity score that helps measure the upgrade complexity
Before using it, you should configure the built-in UCT in a same way to the CLI Run Configuration.
All fields, as above, are described in the Upgrade Compatibility Tool Run Configuration section and are more detailed
in the official documentation.
Go to the UCT configuration dialog Tools -> Configure The Upgrade Compatibility Tool and configure it as required:
After this, you can run this tool at any time you require by using Tools -> Run The Upgrade Compatibility Tool:
For this inspection type you do not need to have UCT inspections enabled for your project, but it is easier to see the problems in the file after navigating to it.
Remember, 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 is also applicable for the other selected configurations on the screenshot below:
