Run the tool
Magento Commerce only
The Upgrade Compatibility Tool ALPHA is a command line tool that checks a Magento instance against a specific version by analyzing all the non-Magento modules installed on it.
The Upgrade Compatibility Tool identifies potential problems that must be fixed in your custom code before attempting to upgrade to a newer version of Magento.
The tool returns a list of errors and warnings that you must address before upgrading to a new version of Magento.
Use the Upgrade Compatibility Tool
Execute the tool by running the following command:
1
bin/uct upgrade:check INSTALLATION_DIR
The INSTALLATION_DIR
value is the directory where your Magento instance is located.
We recommend running the following command to avoid memory limitations:
1
php -d memory_limit=-1 /bin/uct
We also recommend using the -m
command to run the tool against a specific module.
To see Upgrade Compatibility Tool command options and help:
1
bin/uct --help
GraphQL schema compatibility verification
The Upgrade Compatibility Tool also provides the option to introspect two GraphQL endpoints and compare their schemas looking for breaking and dangerous changes between them:
1
bin/uct graphql:compare https://domain1.com/graphql https://domain2.com/graphql
You must have running instance before
and instance after
the upgrade.
Arguments and options
Version
You can compare your current Magento installation with Magento versions >=2.3
.
You must provide the version as a parameter when running the command:
1
bin/uct upgrade:check INSTALLATION_DIR -c 2.4.1
There are some limitations when running the previous command:
- This parameter refers to any tag that identifies a specific version of Magento.
- It is a requirement to provide this one explicitly; providing only the value of it will not work.
- Provide the tag version without any quotation marks (neither single nor double):
‘2.4.1-develop’. - You should NOT provide older versions than the one you have currently installed, nor older than 2.3, which is the oldest one supported at the moment.
Full report
You can also get a full report containing both PHP-related errors and GraphQL. In this case, you must provide at least the following options:
--schema1=SCHEMA1
--schema2=SCHEMA2
INSTALLATION_DIR
Example of a bin/uct command
1
bin/uct upgrade:check --schema1=https://domain1.com/graphql --schema2=https://domain2.com/graphql -c 2.4.1 INSTALLATION_DIR
Output
The Upgrade Compatibility Tool provides a report identifying the affected non-Magento modules and the severity and description of the problem for every issue encountered:
Example with a list of errors/warnings
1
2
3
4
5
File: /app/code/Custom/CatalogExtension/Controller/Index/Index.php
------------------------------------------------------------------
* [ERROR] Line 84: Used nonexistent or non Magento API interface 'Magento\Catalog\Model\ProductRepositoryInterface'
* [WARNING] Line 6: Importing Magento @deprecated class 'Magento\Catalog\Model\ProductRepository'
The report also includes a detailed summary:
- Installed Version: the version currently installed
- Magento Version: the version you want to upgrade to
- Running time: amount of time the analysis took to build the report (mm:ss)
- Checked modules: amount of modules installed in the current magento version examined during the analysis
- PHP errors found: amount of PHP errors
- PHP warnings found: amount of PHP warnings
- GraphQL errors found: amount of GraphQL errors
- GraphQL warnings found: amount of GraphQL warnings
- Total errors found: total amount of errors found
- Total warnings found: total amount of warnings found
- Complexity score: a figure that indicates how difficult is to upgrade from the current version to the new one
The lower this number is, the easier is to perform the upgrade.
Example of a summary report
1
2
3
4
5
6
7
8
9
10
11
12
13
------------------------ --------
Installed version 2.3.5
Magento version 2.4.1
Running time 0m:48s
Checked modules 60
PHP errors found 162
PHP warnings found 120
GraphQL errors found 19
GraphQL warnings found 0
Total errors found 181
Total warnings found 120
Complexity score 482
------------------------ --------
Regarding the GraphQL schema compatibility comparison, the output would be very similar:
Example with a list of errors/warnings for GraphQL
1
2
* [ERROR] FIELD_CHANGED_KIND: ConfigurableProduct.gender changed type from Int to String.
* [WARNING] OPTIONAL_INPUT_FIELD_ADDED: An optional field sku on input type ProductAttributeSortInput was added.
See Developer information for more information.