Mettre à niveau la version de Commerce

Vous pouvez mettre à niveau la base de code Adobe Commerce vers une version plus récente. Avant de mettre à niveau votre projet, consultez la Configuration requise du guide Installation pour connaître les dernières exigences en matière de version logicielle.

Selon la configuration de votre projet, les tâches de mise à niveau peuvent inclure les éléments suivants :

  • Les services de mise à jour, tels que MariaDB (MySQL), OpenSearch, RabbitMQ et Redis, sont compatibles avec les nouvelles versions d’Adobe Commerce.
  • Convertissez un ancien fichier de gestion de configuration.
  • Mettez à jour le fichier .magento.app.yaml avec de nouveaux paramètres pour les hooks et les variables d’environnement.
  • Mettez à niveau les extensions tierces vers la dernière version prise en charge.
  • Mettez à jour le fichier .gitignore.
TIP
Avant de commencer une mise à niveau ou un processus de correction, créez une branche active à partir de l’environnement d’intégration et extrayez la nouvelle branche vers votre poste de travail local. Le fait de dédier une branche à la mise à niveau ou au processus de correctif permet d’éviter toute interférence avec votre travail en cours.
TIP
Pour les projets Pro, vous devez envoyer un ticket d’assistance Adobe Commerce pour installer ou mettre à jour services dans les environnements Staging et Production uniquement.
Indiquez les modifications de service nécessaires, incluez vos fichiers .magento.app.yaml et services.yaml mis à jour et indiquez la version PHP dans le ticket. Pour les modifications en libre-service apportées à la version PHP, aux extensions ou aux paramètres d’environnement, voir Paramètres PHP dans la configuration de l’application.
Pour les modifications apportées à un environnement de production live (Pro uniquement), vous devez fournir un préavis d’au moins 48 heures afin de permettre à l’équipe d’infrastructure Cloud de disposer de suffisamment de temps pour mobiliser des ressources et réaliser une mise à niveau sécurisée.

Mise à niveau à partir d’anciennes versions

Si vous commencez une mise à niveau à partir d’une version de Commerce antérieure à 2.1, certaines restrictions dans la base de code Adobe Commerce peuvent affecter votre capacité à mettre à jour vers une version spécifique de CEE-Outils ou à mettre à niveau vers la prochaine version de Commerce prise en charge. Utilisez le tableau suivant pour déterminer le meilleur chemin d’accès :

Version actuelle
Chemin de mise à niveau
2.1.3 et versions antérieures
Effectuez la mise à niveau d’Adobe Commerce vers la version 2.1.4 ou ultérieure avant de continuer. Effectuez ensuite une mise à niveau unique pour installer les outils ECG.
2.1.4 - 2.1.14
Mettre à jour le package CEE-Outils.
Voir les notes de mise à jour pour les versions 2002.0.9 et ultérieures 2002.0.x.
2.1.15 - 2.1.16
Mettre à jour le package CEE-Outils.
Voir les notes de mise à jour pour2002.0.9 et versions ultérieures.
2.2.x et versions ultérieures
Mettre à jour le package CEE-Outils.
Voir les notes de mise à jour de 2002.0.8 et versions ultérieures.
NOTE
Si vous utilisez une version d’Adobe Commerce sur l’infrastructure cloud qui ne contient pas le package ece-tools, vous devez effectuer une mise à niveau unique vers votre projet cloud pour supprimer les packages obsolètes. Si vous utilisez actuellement le package ece-tools et que vous devez le mettre à jour, reportez-vous à la section Mise à jour du package EC-Tools.

Gestion des configurations

Les versions plus anciennes d’Adobe Commerce, telles que la version 2.1.4 ou ultérieure à la version 2.2.x ou ultérieure, utilisaient un fichier config.local.php pour la gestion de la configuration. Adobe Commerce version 2.2.0 et ultérieure utilise le fichier config.php, qui fonctionne exactement comme le fichier config.local.php, mais qui comporte différents paramètres de configuration qui incluent une liste de vos modules activés et d’autres options de configuration.

Lors de la mise à niveau à partir d’une ancienne version, vous devez migrer le fichier config.local.php pour utiliser le fichier config.php plus récent. Procédez comme suit pour sauvegarder votre fichier de configuration et en créer un.

Pour créer un fichier config.php temporaire :

  1. Créez une copie du fichier config.local.php et nommez-la config.php.

  2. Ajoutez ce fichier au dossier app/etc de votre projet.

  3. Ajoutez et validez le fichier dans votre branche.

  4. Envoyez le fichier à votre branche d’intégration.

  5. Passez à la procédure de mise à niveau.

WARNING
Après la mise à niveau, vous pouvez supprimer le fichier config.php et générer un nouveau fichier complet. Vous ne pouvez supprimer ce fichier que pour le remplacer cette fois-ci. Après avoir généré un nouveau fichier config.php, vous ne pouvez pas supprimer le fichier pour en générer un nouveau. Voir Configuration Management et déploiement de pipeline.

Vérification des dépendances du compositeur Zend Framework

Lors de la mise à niveau vers 2.3.x ou version ultérieure à partir de 2.2.x, vérifiez que les dépendances Zend Framework ont été ajoutées à la propriété autoload du fichier composer.json pour prendre en charge Laminas. Ce module externe prend en charge de nouvelles exigences pour Zend Framework, qui a migré vers le projet Laminas. Voir Migration de Zend Framework vers le projet Laminas sur le Magento DevBlog.

Pour vérifier la configuration auto-load:psr-4 :

  1. Sur votre poste de travail local, modifiez le répertoire de votre projet.

  2. Extrayez votre branche d’intégration.

  3. Ouvrez le fichier composer.json dans un éditeur de texte.

  4. Consultez la section autoload:psr-4 de l’implémentation du gestionnaire de modules externes Zend pour connaître la dépendance des contrôleurs.

    code language-json
     "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/"
        },
    }
    
  5. Si la dépendance Zend est manquante, mettez à jour le fichier composer.json :

    • Ajoutez la ligne suivante à la section autoload:psr-4 .

      code language-json
      "Zend\\Mvc\\Controller\\": "setup/src/Zend/Mvc/Controller/"
      
    • Mettez à jour les dépendances du projet.

      code language-bash
      composer update
      
    • Ajout, validation et modification du code push.

      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>
      
    • Fusionnez les modifications dans l’environnement d’évaluation, puis dans l’environnement de production.

Fichiers de configuration

Avant de mettre à niveau l’application, vous devez mettre à jour les fichiers de configuration de votre projet afin de tenir compte des modifications apportées aux paramètres de configuration par défaut d’Adobe Commerce sur l’infrastructure cloud ou l’application. Les derniers paramètres par défaut sont disponibles dans le référentiel GitHub magento-cloud.

.magento.app.yaml

Vérifiez toujours les valeurs contenues dans le fichier .magento.app.yaml pour votre version installée, car il contrôle la manière dont votre application crée et se déploie vers l’infrastructure cloud. L’exemple suivant concerne la version 2.4.7 et utilise Composer 2.7.2. La propriété build: flavor: n’est pas utilisée pour le compositeur 2.x ; voir Installation et utilisation du compositeur 2.

Pour mettre à jour le fichier .magento.app.yaml :

  1. Sur votre poste de travail local, modifiez le répertoire de votre projet.

  2. Ouvrez et modifiez le fichier magento.app.yaml.

  3. Mettez à jour les options PHP.

    code language-yaml
    type: php:8.3
    
    build:
        flavor: none
    dependencies:
        php:
            composer/composer: '2.7.2'
    
  4. Modifiez les commandes hooks property build et deploy .

    code language-yaml
    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
    
  5. Ajoutez les variables d’environnement suivantes à la fin du fichier.

    Pour Adobe Commerce 2.2.x à 2.3.x-

    code language-yaml
    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'
    

    Pour Adobe Commerce 2.4.x-

    code language-yaml
    variables:
        env:
            CONFIG__DEFAULT__PAYPAL_ONBOARDING__MIDDLEMAN_DOMAIN: 'payment-broker.magento.com'
            CONFIG__STORES__DEFAULT__PAYPAL__NOTATION_CODE: 'Magento_Enterprise_Cloud'
    
  6. Enregistrez le fichier. Ne validez ou n’envoyez pas encore de modifications à l’environnement distant.

  7. Passez à la procédure de mise à niveau.

composer.json

Avant de procéder à la mise à niveau, vérifiez toujours que les dépendances du fichier composer.json sont compatibles avec la version Adobe Commerce.

Pour mettre à jour le fichier composer.json pour Adobe Commerce version 2.4.4 et ultérieure :

  1. Ajoutez le allow-plugins suivant à la section config :

    code language-json
    "config": {
       "allow-plugins": {
          "dealerdirect/phpcodesniffer-composer-installer": true,
          "laminas/laminas-dependency-plugin": true,
          "magento/*": true
       }
    },
    
  2. Ajoutez le module externe suivant à la section require :

    code language-json
    "require": {
        "magento/composer-root-update-plugin": "^2.0.3"
    },
    
  3. Ajoutez le composant suivant à la section extra:component_paths :

    code language-json
    "extra": {
       "component_paths": {
          "tinymce/tinymce": "lib/web/tiny_mce_5"
       },
    },
    
  4. Enregistrez le fichier. Ne validez ou n’envoyez pas encore de modifications à votre branche.

  5. Passez à la procédure de mise à niveau.

Sauvegarde du projet

Nous vous recommandons de créer une sauvegarde de votre projet avant une mise à niveau. Procédez comme suit pour sauvegarder vos environnements d’intégration, d’évaluation et de production.

Pour sauvegarder votre base de données et votre code d’environnement d’intégration :

  1. Créez une sauvegarde locale de la base distante.

    code language-bash
    magento-cloud db:dump
    
    note note
    NOTE
    La commande magento-cloud db:dump exécute la commande mysqldump avec l’indicateur --single-transaction, ce qui vous permet de sauvegarder votre base de données sans verrouiller les tables.
  2. Sauvegardez le code et le média.

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

    Vous pouvez éventuellement omettre [--media] si vous disposez d’un grand nombre de fichiers statiques qui sont déjà dans le contrôle de code source.

Pour sauvegarder votre base de données d’environnement d’évaluation ou de production avant le déploiement :

  1. Utilisez SSH pour vous connecter à l’environnement distant.

  2. Créez un vidage de base de données. Pour choisir un répertoire cible pour le vidage DB, utilisez l’option --dump-directory.

    code language-bash
    vendor/bin/ece-tools db-dump
    

    L’opération de vidage crée un fichier d’archive dump-<timestamp>.sql.gz dans votre répertoire de projet distant. Voir Sauvegarde de la base de données.

Mise à niveau des applications

Passez en revue les versions de service pour connaître les dernières exigences en matière de version logicielle avant de mettre à niveau votre application.

Pour mettre à niveau la version de l’application :

  1. Sur votre poste de travail local, modifiez le répertoire de votre projet.

  2. Définissez la version de mise à niveau à l’aide de la syntaxe de contrainte de version.

    code language-bash
    composer require "magento/magento-cloud-metapackage":">=CURRENT_VERSION <NEXT_VERSION" --no-update
    
    note note
    NOTE
    Vous devez utiliser la syntaxe de contrainte de version pour mettre à jour le package ece-tools avec succès. Vous pouvez trouver la contrainte de version dans le fichier composer.json pour la version du modèle d’application que vous utilisez pour la mise à niveau.
  3. Mettez à jour le projet.

    code language-bash
    composer update
    
  4. Ajout, validation et modification du code push.

    code language-bash
    git add -A
    
    code language-bash
    git commit -m "Upgrade"
    
    code language-bash
    git push origin <branch-name>
    

    git add -A est nécessaire pour ajouter tous les fichiers modifiés au contrôle de code source en raison de la manière dont le compositeur d’expérience associe les packages de base. composer install et composer update stockent les fichiers du package de base (magento/magento2-base et magento/magento2-ee-base) dans la racine du package.

    Les fichiers marshals du compositeur appartiennent à la nouvelle version d’Adobe Commerce, pour remplacer la version obsolète de ces mêmes fichiers. Actuellement, la mise en grappe est désactivée dans Adobe Commerce. Vous devez donc ajouter les fichiers mis en grappe au contrôle source.

  5. Attendez que le déploiement soit terminé.

  6. Vérifiez la mise à niveau dans votre environnement d’intégration, d’évaluation ou de production en utilisant SSH pour vous connecter et vérifier la version.

    code language-bash
    php bin/magento --version
    

Créer un fichier config.php

Comme mentionné dans Gestion de la configuration, après la mise à niveau, vous devez créer un fichier config.php mis à jour. Effectuez d’autres modifications de configuration par l’intermédiaire de l’administrateur de votre environnement d’intégration.

Pour créer un fichier de configuration spécifique au système :

  1. Depuis le terminal, utilisez une commande SSH pour générer le fichier /app/etc/config.php pour l’environnement.

    code language-bash
    ssh <SSH-URL> "<Command>"
    

    Par exemple, pour Pro, exécutez scd-dump sur la branche integration :

    code language-bash
    ssh <project-id-integration>@ssh.us.magentosite.cloud "php vendor/bin/ece-tools config:dump"
    
  2. Transférez le fichier config.php vers vos postes de travail locaux à l’aide de rsync ou scp. Vous pouvez uniquement ajouter ce fichier à la branche localement.

    code language-bash
    rsync <SSH-URL>:app/etc/config.php ./app/etc/config.php
    
  3. Ajout, validation et modification du code push.

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

    Cela génère un fichier /app/etc/config.php mis à jour avec une liste de modules et des paramètres de configuration.

WARNING
Pour une mise à niveau, vous supprimez le fichier config.php. Une fois ce fichier ajouté à votre code, vous devez le supprimer et non. Si vous devez supprimer ou modifier des paramètres, modifiez le fichier manuellement.

Mettre à niveau les extensions

Passez en revue vos pages d’extension et de module tierces dans Marketplace ou d’autres sites d’entreprise et vérifiez la prise en charge d’Adobe Commerce et d’Adobe Commerce sur l’infrastructure cloud. Si vous devez mettre à niveau des extensions et modules tiers, Adobe recommande de travailler dans une nouvelle branche d’intégration avec vos extensions désactivées.

Pour vérifier et mettre à niveau vos extensions :

  1. Créez une branche sur votre poste de travail local.

  2. Désactivez vos extensions selon vos besoins.

  3. Lorsque disponible, téléchargez les mises à niveau d’extension.

  4. Installez la mise à niveau comme indiqué dans la documentation tierce.

  5. Activez et testez l’extension .

  6. Ajoutez, validez et poussez les modifications de code sur la télécommande.

  7. Poussez vers et testez dans votre environnement d’intégration.

  8. Poussez vers l’environnement d’évaluation pour effectuer un test dans un environnement de pré-production.

Adobe recommande vivement de mettre à niveau votre environnement de production avant, y compris les extensions mises à niveau dans le processus de lancement de votre site.

NOTE
Lorsque vous mettez à niveau la version de votre application, le processus de mise à niveau se met automatiquement à jour vers la dernière version du module CDN Fastly.

Dépannage de la mise à niveau

En cas d’échec de la mise à niveau, un message d’erreur s’affiche dans le navigateur pour vous indiquer que vous ne pouvez pas accéder à votre vitrine ou au panneau d’administration :

There has been an error processing your request
Exception printing is disabled by default for security reasons.
  Error log record number: <error-number>

Pour résoudre l’erreur :

  1. Sur votre poste de travail local, modifiez le répertoire de votre projet.

  2. Utilisez SSH pour vous connecter à l’environnement distant.

    code language-bash
    magento-cloud ssh
    
  3. Ouvrez le fichier ./app/var/report/<error number>.

  4. Examinez les journaux et déterminez la source du problème.

  5. Ajout, validation et modification du code push.

    code language-bash
    git add -A && git commit -m "Fixed deployment failure" && git push origin <branch-name>
    
recommendation-more-help
05f2f56e-ac5d-4931-8cdb-764e60e16f26