In the following article, we describe how to upgrade your e-commerce website toMagento 2.3 – the latest version of our favorite e-commerce platform. Besides, you will find solutions of the most common issues related to the process. If you want to get all the latest benefits Magento offers, change the version of your platform immediately. This guide will teach you how to achieve this goal.
The first thing we’d like to draw your attention to is the Magento 2.3 system requirements. You always need to pay attention to them before upgrading to the latest version since your current setup can be outdated for the upgrade causing multiple issues and breaking the entire online store. Of course, you don’t want to have all these troubles, so check the Magento 2.3.x technology stack requirements to eliminate possible future problems.
The supported operating systems for Magento 2.3 are Linux x86-64 distributions, such as RHEL, CentOS, Debian, Ubuntu, etc. What operating system do you use? Is it supported?
How many gigabytes does your system have? The minimum amount of RAM required for the upgrade to Magento 2.3 is 2GB. If you have less – create a swap file to prevent the upgrade fail.
If you want to contribute to the Magento 2.3 codebase or develop Magento extensions for the latest platform version, you need the latest stable version of Composer to be installed.
Web Server Requirements
While upgrading to Magento 2.3, you can use several options. First of all, it is Apache 2.2 or 2.4. Note that you must enable the Apache mod_rewrite to enable the server to perform URL rewriting and mod_version to enable flexible version checking for different httpd versions.
Alternatively, it is possible to use nginx 1.x to update your Magento version to 2.3.
As for the database suitable for Magento 2.3, it is MySQL 5.6 or 5.7. At the same time, you can use several alternative options since the latest platform version is compatible with MySQL NDB Cluster, MariaDB, Percona, as well as other binary-compatible MySQL technologies.
And there are a plethora of PHP requirements regarding the upgrade to Magento 2.3. The two supported versions are 7.1.3+ and 7.2.x. At the same time, you need to install multiple extensions. You can find them here: Required PHP Extensions.
And don’t forget to enable PHP OPcache for performance reasons. Chances are, you should install it separately, see the PHP OPcache documentation for further information.
Also, note that the official Magento documentation recommends particular PHP configuration settings, such as memory_limit, to avoid common problems when using Magento. You can find them here: Required PHP Settings.
To upgrade your e-commerce store to Magento 2.3, a valid HTTPS security certificate is required. Note that self-signed SSL certificates are not supported.
To upgrade Magento to 2.3 from the command line, your software should be installed by downloading the metapackage with the help of composer create-projector installing the compressed archive. You can use either the command line or the script to run the update procedure.
Note that both options require utilizing Composer and a command line interface. However, the script allows automating several of the upgrade steps. And don’t forget about prerequisites (we describe them below).
And if you cloned the Magento 2 GitHub repository, go right here. This article describes how to upgrade to Magento 2.3 for your particular case.
To prepare your environment to the upgrade to Magento 2.3, complete the following prerequisites:
Set the pub directory root: create a subdomain or docroot that uses the Magento installation directory as its root, and run the System Upgrade utility using that subdomain if you already set the Magento root directory to <your Magento install dir>/pub;
Check the compatibility: verify that all environment settings are compatible with the system requirements described above;
Switch to maintenance mode: this will prevent access to your store while it’s being upgraded. To do that, run the following command:
Below, we describe how to upgrade to Magento 2.3 using the command line interface with the highest control level over the process. The more manual process of upgrading requires more time but provides some additional flexibility. Upgrading using the script process is a bit easier and less intensive and we will also describe it further in this post.
The first step in your update to Magento 2.3 is the backup of the existing composer.json file in the Magento installation directory.
To run the upgrade successfully, you need to specify all the needed packages and remove any unneeded ones before going any further.
In case you are upgrading from Magento Open Source to Commerce, don’t forget to deactivate the Magento Open Source update. Use the following command to do that:
Now, you have to update autoload. Open the composer.json file and find the “autoload”: “psr-4” section. It should include “Zend\\Mvc\\Controller\\”: “setup/src/Zend/Mvc/Controller/” like in the following example:
To use a repository with non-public packages, change the URL in –repository accordingly.
Thirdly, you have to move your project to the <Magento install dir>/update directory. Utilize the following commands to achieve this goal:
mv temp_dir/update<Magento install dir>/update
Now, it is necessary to edit metadata. You have to update the “name”, “version”, and “description” fields in the <Magento install dir>/composer.json file. Note that it is a superficial process – not functional.
Finally, you can apply the updates. You might have already used the necessary command on previous upgrades:
Clean Magento Cache
Now, when the update is applied, you have to clean the cache. Use the command provided below:
You should also clear caches and generated content of the var and generated subdirectories manually:
rm-rf<Magento install dir>/var/cache/*
rm-rf<Magento install dir>/var/page_cache/*
rm-rf<Magento install dir>/generated/code/*
If you use Redis, Memcached, or another cache storage, clear the cache there too.
Update Database Schema
Now, the upgrade to Magento 2.3 requires to update the database schema and data. Use the following command:
php bin/magento setup:upgrade
Disable Maintenance Mode
If everything is ok and no errors occurred, you can disable the maintenance mode. Use this command:
php bin/magento maintenance:disable
Don’t forget to restart Varnish if you use it. Use this command:
service varnish restart
How to check whether the update to Magento 2.3 is successful? Open your storefront in a browser. If it doesn’t load correctly, the upgrade failed. We provide multiple issues and their resolutions below. If the application prompts the following error – We’re sorry, an error has occurred while generating this email – you have to:
Reset the filesystem ownership and permissions as a root user.
Clear the following directories: <your Magento install dir>/var/cache, /var/page_cache, and /generated/code.
Now, check your storefront in your web browser again. If your store still loads incorrectly, try to find the reason in the corresponding section of this article.
Upgrade to Magento 2.3 via Script
Now, we’d like to draw your attention to another approach to the Magento 2.3 upgrade. You can use a script to simplify the procedure described above make it semi-automated.
Note that to upgrade to Magento 2.3 via script, you have to update to PHP 7.1 or 7.2.
Also, don’t forget that you should use the manual process if you don’t want to override previously made updates to the values the upgrade script affects. If it is not a problem, then the script will:
Update Magento with the 2.3 requirements;
Create a backup of the composer.json file;
Specify the new Magento metapackage version;
Update the “require-dev” and “autoload”: “psr-4” sections;
Back up and update the magento/updater, if it is installed;
Update the “name”, “version”, and “description” fields.
As you can see, the script dramatically improves the standard upgrade to Magento 2.3 automating multiple processes. Let’s see how to use it.
As promised above, we provide several common issues that occur during the upgrade as well as explain how to fix them. Let’s see what disturbs Magento users when they want to get a new platform’s version.
Component Dependency Issue
This problem may occur when you upgrade Magento via Setup Wizard at the Readiness Check step. Dependency conflicts are usually caused by third-party extensions depending on some old Magento 2 components. To resolve the issue, you have to uninstall all custom extensions. Don’t worry: you will reinstall them after the system is updated.
Another reason for this issue is a changed composer.json file. Restoring composer.json to the original version usually helps. After doing that, run Setup Wizard one more time.
To prevent this error, don’t run php bin/magento setup:upgrade right after the upgrade. If it occurs, you have to delete the var/di folder. Next, change permissions of var and pub folderto 777:
Run the following two commands:
Run php bin/magento setup:upgrade
Run php bin/magento setup:di:compile
It should solve the problem.
At the beginning of this post, we mentioned that the minimum amount of RAM necessary for upgrading to Magento 2.3 is 2GB. If you have less, you will encounter the ‘Cannot allocate memory’ error during the upgrade. It means that not enough RAM is allocated to PHP processes.
Setup Namespace Issue
While upgrading to Magento 2.3, you may also face the “There are no commands defined in the “setup” namespace” message. The corresponding error is fixed as follows:
You have to give full permission to var and pub folders. Use the following command:
Next, you have to inspect your third-party extensions. Every extension’s module.xml should have setup_version in it:
You may also inspect your composer.json file. Sometimes its errors might be a reason for this issue.
Upgrade Command Issue
If php bin/magento setup:upgrade isn’t working, you have to inspect all custom modules. Usually, their internal problems cause the issue. As we’ve already mentioned, you can delete them, upgrade to Magento 2.3, and then reinstall the extensions.
Also, note that you may also try to clean generated or var/di, var/generation folders. This procedure helps sometimes.
As you might have already guessed, some steps are missed. So, follow the guide above carefully to avoid the problem. According to Daniel, the error is caused by fabpot/php-cs-fixer, so he recommends to remove unused packages with the help of the following command:
-magento/product-community-edition2.3.0requires magento/inventory-composer-metapackage^1.0.3->satisfiable by magento/inventory-composer-metapackage[1.0.3].
-magento/inventory-composer-metapackage1.0.3requires magento/inventory-composer-installer^1.0.3->satisfiable by magento/inventory-composer-installer[1.0.3].
-Installation request formagento/product-community-edition2.3.0->satisfiable by magento/product-community-edition[2.3.0].
-Atypo inthe packagename
-The packageisnotavailable inastable-enough version according toyour minimum-stability setting
see<https://getcomposer.org/doc/04-schema.md#minimum-stability> for more details.
As we’ve mentioned above, it is necessary to edit the composer.json file, since Magento 2.3 has new dependency versions. Only then, you can run the composer update command. Peter Dohogne recommends running the script update. Besides, he proposes to check whether your Composer version is compatible.
Your executable version of Composer should be
Installed composer/composer package version for Magento 2.2.6:
$composer show composer/composer|grep versions
Dependencies with composer/composer requirements and constraints:
Next, it is necessary to find your third-party extension name in the /vendor/composer/installed.json file and add the latest PHP and framework version there. To apply the changes and the update, run the composer update command.
Thoassumes that it is a problem of the local installation caused by the fact the Magento instance is running on Windows. The user recommends fixing the vendor\magento\framework\View\Element\Template\File\Validator.php file. To solve the problem, go to line 114 and change the line number and replace the following snippet
According to Sanjay, it fixes the problem only partially: the website is loading but the home page and admin login show a blank page. Go to StackExchange and help him if you know the correct resolution!
Command “Update” Failed
Borde91 describes another problem that occurs while upgrading to Magento 2.3:
Command"update"failed:You are running composer with xdebug enabled.Thishasamajor impact on runtime performance.See https://getcomposer.org/xdebug Loading composer repositories with package information Updating dependencies (including require-dev) Your requirements could not be resolved to an installable set of packages.
And don’t forget about the universal resolution of all issues related to the Magento 2.3 upgrade – you can downgrade to the previous version! Use the CLI algorithm described in this article but put an older version number instead of 2.3.
Although the Magento 2.3 upgrade seems to be a little bit complicated, especially due to the high amount of reported problems, it is still not rocket science, so you can manage everything. Choose the script installation if the CLI one seems to be too difficult. If any problems occur, always go to StackExchange for help!