Upgrade Commerce version

Create a copy of config.local.php file and name it config.php.

Add this file to the app/etc folder of your project.

Add and commit the file to your branch.

Push the file to your integration branch.

Continue with the upgrade process.

On your local workstation, change to your project directory.

Check out your integration branch.

Open the composer.json file in a text editor.

Check the autoload:psr-4 section for the Zend plugin manager implementation for controllers dependency.

 "autoload": {
    "psr-4": {
       "Magento\\Framework\\": "lib/internal/Magento/Framework/",
       "Magento\\Setup\\": "setup/src/Magento/Setup/",
       "Magento\\": "app/code/Magento/",
       "Zend\\Mvc\\Controller\\": "setup/src/Zend/Mvc/Controller/"
    },
}

If the Zend dependency is missing, update the composer.json file:

• Add the following line to the autoload:psr-4 section.

  code language-json
  "Zend\\Mvc\\Controller\\": "setup/src/Zend/Mvc/Controller/"

• Update the project dependencies.

  code language-bash
  composer update

• Add, commit, and push code changes.

  code language-bash
  git add -A

  code language-bash
  git commit -m "Add Zend plugin manager implementation for controllers dependency for Laminas support"

  code language-bash
  git push origin <branch-name>

• Merge changes to the Staging environment, and then to Production.

On your local workstation, change to your project directory.

Open and edit the magento.app.yaml file.

Update the PHP options.

type: php:8.3

build:
    flavor: none
dependencies:
    php:
        composer/composer: '2.7.2'

Modify the hooks property build and deploy commands.

hooks:
    # We run build hooks before your application has been packaged.
    build: |
        set -e
        composer install
        php ./vendor/bin/ece-tools run scenario/build/generate.xml
        php ./vendor/bin/ece-tools run scenario/build/transfer.xml
    # We run deploy hook after your application has been deployed and started.
    deploy: |
        php ./vendor/bin/ece-tools run scenario/deploy.xml
    # 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 run scenario/post-deploy.xml

Add the following environment variables to the end of the file.

For Adobe Commerce 2.2.x through 2.3.x–

variables:
    env:
        CONFIG__DEFAULT__PAYPAL_ONBOARDING__MIDDLEMAN_DOMAIN: 'payment-broker.magento.com'
        CONFIG__STORES__DEFAULT__PAYMENT__BRAINTREE__CHANNEL: 'Magento_Enterprise_Cloud_BT'
        CONFIG__STORES__DEFAULT__PAYPAL__NOTATION_CODE: 'Magento_Enterprise_Cloud'

For Adobe Commerce 2.4.x–

variables:
    env:
        CONFIG__DEFAULT__PAYPAL_ONBOARDING__MIDDLEMAN_DOMAIN: 'payment-broker.magento.com'
        CONFIG__STORES__DEFAULT__PAYPAL__NOTATION_CODE: 'Magento_Enterprise_Cloud'

Save the file. Do not commit or push changes to the remote environment yet.

Continue with the upgrade process.

Add the following allow-plugins to the config section:

"config": {
   "allow-plugins": {
      "dealerdirect/phpcodesniffer-composer-installer": true,
      "laminas/laminas-dependency-plugin": true,
      "magento/*": true
   }
},

Add the following plugin to the require section:

"require": {
    "magento/composer-root-update-plugin": "^2.0.3"
},

Add the following component to the extra:component_paths section:

"extra": {
   "component_paths": {
      "tinymce/tinymce": "lib/web/tiny_mce_5"
   },
},

Save the file. Do not commit or push changes to your branch yet.

Continue with the upgrade process.

Create a local backup of the remote database.

magento-cloud db:dump

Back up code and media.

php bin/magento setup:backup --code [--media]

Optionally, you can omit [--media] if you have a large number of static files that are already in source control.

Use SSH to log in to the remote environment.

Create a database dump. To choose a target directory for the DB dump, use the --dump-directory option.

vendor/bin/ece-tools db-dump

The dump operation creates a dump-<timestamp>.sql.gz archive file in your remote project directory. See Back up database.

On your local workstation, change to your project directory.

Set the upgrade version using the version constraint syntax.

composer require "magento/magento-cloud-metapackage":">=CURRENT_VERSION <NEXT_VERSION" --no-update

Update the project.

composer update

Review the patches that are currently applied:

• If there are any patches installed in the m2-hotfixes directory, submit an Adobe Commerce Support ticket and work with Adobe Commerce Support to verify which patches can still be applied to the new version. Remove the non-applicable patch(es) from the m2-hotfixes directory.

• If there are any [Quality Patches] applied in the .magento.env.yaml file, verify whether they can still be applied to the new version. Remove the non-applicable patch(es) from the QUALITY_PATCHES section of the .magento.env.yaml file.

Method 1: Verify the applicable versions in the Quality Patches release notes

Method 2: View available patches and status

Method 3: Search for patches

Add, commit, and push code changes.

git add -A

git commit -m "Upgrade"

git push origin <branch-name>

git add -A is required to add all changed files to source control because of the way Composer marshals base packages. Both composer install and composer update marshal files from the base package (magento/magento2-base and magento/magento2-ee-base) into the package root.

The files that Composer marshals belong to the new version of Adobe Commerce, to overwrite the outdated version of those same files. Currently, marshaling is disabled in Adobe Commerce, so you must add the marshaled files to source control.

Wait for deployment to complete.

Verify the upgrade in your Integration, Staging, or Production environment by using SSH to log in and check the version.

php bin/magento --version

From the terminal, use an SSH command to generate the /app/etc/config.php file for the environment.

ssh <SSH-URL> "<Command>"

For example for Pro, to run the scd-dump on the integration branch:

ssh <project-id-integration>@ssh.us.magentosite.cloud "php vendor/bin/ece-tools config:dump"

Transfer the config.php file to your local workstations using rsync or scp. You can only add this file to the branch locally.

rsync <SSH-URL>:app/etc/config.php ./app/etc/config.php

Add, commit, and push code changes.

git add app/etc/config.php && git commit -m "Add system-specific configuration" && git push origin master

This generates an updated /app/etc/config.php file with a module list and configuration settings.

Create a branch on your local workstation.

Disable your extensions as needed.

When available, download extension upgrades.

Install the upgrade as documented by the third-party documentation.

Enable and test the extension.

Add, commit, and push the code changes to the remote.

Push to and test in your integration environment.

Push to the Staging environment to test in a pre-production environment.

On your local workstation, change to your project directory.

Use SSH to log in to the remote environment.

magento-cloud ssh

Open the ./app/var/report/<error number> file.

Examine the logs and determine the source of the issue.

Add, commit, and push code changes.

git add -A && git commit -m "Fixed deployment failure" && git push origin <branch-name>