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
.
Staging
et Production
uniquement..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.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 :
Voir les notes de mise à jour pour les versions 2002.0.9 et ultérieures 2002.0.x.
Voir les notes de mise à jour pour2002.0.9 et versions ultérieures.
Voir les notes de mise à jour de 2002.0.8 et versions ultérieures.
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 :
-
Créez une copie du fichier
config.local.php
et nommez-laconfig.php
. -
Ajoutez ce fichier au dossier
app/etc
de votre projet. -
Ajoutez et validez le fichier dans votre branche.
-
Envoyez le fichier à votre branche d’intégration.
-
Passez à la procédure de mise à niveau.
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
:
-
Sur votre poste de travail local, modifiez le répertoire de votre projet.
-
Extrayez votre branche d’intégration.
-
Ouvrez le fichier
composer.json
dans un éditeur de texte. -
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/" }, }
-
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
:
-
Sur votre poste de travail local, modifiez le répertoire de votre projet.
-
Ouvrez et modifiez le fichier
magento.app.yaml
. -
Mettez à jour les options PHP.
code language-yaml type: php:8.3 build: flavor: none dependencies: php: composer/composer: '2.7.2'
-
Modifiez les commandes
hooks
propertybuild
etdeploy
.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
-
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'
-
Enregistrez le fichier. Ne validez ou n’envoyez pas encore de modifications à l’environnement distant.
-
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 :
-
Ajoutez le
allow-plugins
suivant à la sectionconfig
:code language-json "config": { "allow-plugins": { "dealerdirect/phpcodesniffer-composer-installer": true, "laminas/laminas-dependency-plugin": true, "magento/*": true } },
-
Ajoutez le module externe suivant à la section
require
:code language-json "require": { "magento/composer-root-update-plugin": "^2.0.3" },
-
Ajoutez le composant suivant à la section
extra:component_paths
:code language-json "extra": { "component_paths": { "tinymce/tinymce": "lib/web/tiny_mce_5" }, },
-
Enregistrez le fichier. Ne validez ou n’envoyez pas encore de modifications à votre branche.
-
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 :
-
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. -
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 :
-
Utilisez SSH pour vous connecter à l’environnement distant.
-
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 :
-
Sur votre poste de travail local, modifiez le répertoire de votre projet.
-
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 fichiercomposer.json
pour la version du modèle d’application que vous utilisez pour la mise à niveau. -
Mettez à jour le 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 "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
etcomposer update
stockent les fichiers du package de base (magento/magento2-base
etmagento/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.
-
Attendez que le déploiement soit terminé.
-
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 :
-
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 brancheintegration
:code language-bash ssh <project-id-integration>@ssh.us.magentosite.cloud "php vendor/bin/ece-tools config:dump"
-
Transférez le fichier
config.php
vers vos postes de travail locaux à l’aide dersync
ouscp
. Vous pouvez uniquement ajouter ce fichier à la branche localement.code language-bash rsync <SSH-URL>:app/etc/config.php ./app/etc/config.php
-
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.
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 :
-
Créez une branche sur votre poste de travail local.
-
Désactivez vos extensions selon vos besoins.
-
Lorsque disponible, téléchargez les mises à niveau d’extension.
-
Installez la mise à niveau comme indiqué dans la documentation tierce.
-
Activez et testez l’extension .
-
Ajoutez, validez et poussez les modifications de code sur la télécommande.
-
Poussez vers et testez dans votre environnement d’intégration.
-
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.
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 :
-
Sur votre poste de travail local, modifiez le répertoire de votre projet.
-
Utilisez SSH pour vous connecter à l’environnement distant.
code language-bash magento-cloud ssh
-
Ouvrez le fichier
./app/var/report/<error number>
. -
Examinez les journaux et déterminez la source du problème.
-
Ajout, validation et modification du code push.
code language-bash git add -A && git commit -m "Fixed deployment failure" && git push origin <branch-name>