Upgrade to ece-tools

If you still use a version of Magento Commerce Cloud that does not contain the ece-tools package, then your project requires an upgrade. We deprecated the magento/magento-cloud-configuration and magento/ece-patches packages in favor of the ece-tools package.

You must perform a one-time, manual step to update the magento/magento-cloud-metapackage version constraint in the composer.json file, located in the root directory. This constraint enables updates for Magento Commerce Cloud metapackages—including removing deprecated packages—without upgrading your current Magento Commerce version. If your project contains the ece-tools package and you have updated the metapackage, you can skip the following upgrade and see Update ece-tools.

Before beginning an upgrade or a patching process, create an active branch from the Integration environment and checkout the new branch to your local workstation. Dedicating a branch to the upgrade or the patch process helps to avoid interference with your work in progress.

Remove deprecated packages

Before performing an upgrade to use the ece-tools package, check the composer.lock file for the following deprecated packages:

• magento/magento-cloud-configuration
• magento/ece-patches

Update the metapackage

Each Magento Commerce version requires a different constraint based on the following:

1
>=current_version <next_version

You can always find the latest metapackage constraint in the magento-cloud template.

The following example places a constraint for the Magento Commerce Cloud metapackage to any version greater than or equal to the current version 2.3.4 and lower than next version 2.3.5:

1
2
3
"require": {
    "magento/magento-cloud-metapackage": ">=2.3.4 <2.3.5"
},

Upgrade the project

To upgrade your project to use the ece-tools package, you need to update the metapackage, update the .magento.app.yaml hooks properties, and perform a Composer update.

To upgrade project to use ece-tools:

1. Update the magento/magento-cloud-metapackage version constraint in the composer.json file.

   1
    composer require "magento/magento-cloud-metapackage":">=2.3.4 <2.3.5" --no-update
   

2. Update the metapackage.

   1
   composer update magento/magento-cloud-metapackage
   

3. Modify the hook commands in the magento.app.yaml file.

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   hooks:
       # We run build hooks before your application has been packaged.
       build: |
           set -e
           php ./vendor/bin/ece-tools build:generate
           php ./vendor/bin/ece-tools build:transfer
       # We run deploy hook after your application has been deployed and started.
       deploy: |
           php ./vendor/bin/ece-tools deploy
       # We run post deploy hook to clean and warm the cache. Available with ECE-Tools 2002.0.10.
       post_deploy: |
           php ./vendor/bin/ece-tools post-deploy
   

4. Check for and remove the deprecated packages. The deprecated packages can prevent a successful upgrade.

   1
   composer remove magento/magento-cloud-configuration
   

   1
   composer remove magento/ece-patches
   

5. It may be necessary to update the ece-tools package.

   1
   composer update magento/ece-tools
   

6. Add and commit the code changes. In this example, the following files were updated:

   1
   2
   3
   .magento.app.yaml
   composer.json
   composer.lock
   

7. Push your code changes to the remote server and merge this branch with the integration branch.

   1
   git push origin <branch-name>