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
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
You can compare your current Magento installation with Magento versions
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):
- 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.
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:
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
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.
M2_VERSION is the target Magento 2 version you want to compare to your Magento instance.
If after running this command:
1 bin/uct upgrade:check INSTALLATION_DIR -c M2_VERSION
the only output is
Upgrade compatibility tool:
1 2 bin/uct upgrade:check /var/www/project/magento/ -c 2.4.1 Upgrade compatibility tool
the likely cause is a PHP memory limitation.
Override the memory limitation by setting
1 php -d memory_limit=-1 /bin/uct upgrade:check INSTALLATION_DIR -c M2_VERSION