Magento Open Source / Adobe Commerce のバージョンアップ手順

2022年の後半は、PHP7.4のサポート終了と、Magento Open Source / Adobe Commerce 2.3.x / 2.4.0 - 2.4.3 のサポート終了が同時に到来することもあり、Magento Open Source / Adobe Commerce界隈では新しいバージョンへのアップデート作業が急務となっています。
しかしながら、パッケージを利用したシステム構築の現場によく見られる、

カスタマイズの悪影響によるアップデートの困難化
アップデート手順の理解不足による混乱

が随所で起きているように思われます。
そこで今回は弊社が普段Magento Open Source / Adobe Commerceをアップデートする際に行っている手順をご紹介したいと思います。

アップデートの前に準備すること

アップデート作業を行う前には必ず以下のものを準備するようにしましょう。

バージョン管理ツール（git等）
作業者個別の動作検証用環境（いわゆる「ローカル開発環境」）
共有の動作検証用環境（いわゆる「テスト環境」）
利用しているサードパーティ製エクステンションの最新版

バージョン管理ツール

時折、バージョン管理ツールを利用していないサイトを見かけることがありますが、

過去の変更履歴が追えない
通常の改修・更新と、アップデート作業を並行できない
テストや本番への反映作業を自動化しにくい

といった問題が発生します。今の時点で導入されていない場合は、ぜひ導入しましょう。
Magento Open Source / Adobe Commerceが公式に利用しているのはgitなので、同じくGitを利用するのがおすすめです。

作業者個別の動作検証環境

これは必ず必要です。
アップデート作業では何が起きるか全く予想がつきません。Magento Open Source / Adobe Commerce本体のバージョンアップに伴う変更だけでなく、サードパーティ製エクステンションの仕様変更に伴う予想外の事態というのは起き得るものとして想定するべきです。

もしもアップデート作業を担当する人の環境と普段のサイト更新を担当する人の検証用の環境が同じである場合、アップデート作業によって環境が不調になってしまうと更新作業が滞る可能性が出てきてしまいます。
そういった問題を回避する意味でも、アップデート作業を行う人は個別に作業をするPC上に動作検証用の環境を構築するようにしましょう。
個人別に環境を用意しておけば、たとえアップデート作業がうまく行かなかった場合でも、影響範囲は個人にとどまります。環境を壊して作り直すということも気軽に行えます。

共有の動作検証用環境

関係者で並行して表示や動作の検証を行うためには、やはり共有の動作検証用環境が必要です。
ただし、この環境は現在稼働中のMagento Open Source / Adobe Commerceのバージョンを動かしているテスト用環境とは別に用意する必要があります。
普段使っている環境に新しいバージョンを適用した場合、テストが完了するまでの間は運用に支障を来す恐れがあります。

Adobe Commerceのクラウド版をご利用の場合は、クラウド版が持っているステージング環境の機能が利用できます。
新しく構成を作る必要がないので、クラウド版のほうがアップデートの動作検証では便利かもしれませんね。

利用しているサードパーティ製エクステンションの最新版

Magento Open Source / Adobe Commerceのアップデート時には、Magento Open Source / Adobe Commerce本体のモジュールバージョンの変更だけでなく、PHPのバージョン変更も同時に必要になることがあります。
エクステンションの中には、

動作可能なPHPバージョンの厳格な指定
動作可能なMagento Open Source / Adobe Commerceバージョンの厳格な指定

が定義されているものがあります。アップデートの実施時に対応バージョンではないサードパーティ製エクステンションが含まれている場合、アップデートが出来ないことがあります。
有償・無償を問わず、Magento Open Source / Adobe Commerceのアップデートを行う際には最新版のエクステンションを入手するようにしましょう。

アップデート作業の流れ

前段でご説明したものは、システム開発・運用保守の現場を経験されている方であれば「当たり前ではないか？」と思われるものばかりです。
実際のところ、特段に珍しいものではありません。

ここからはアップデート作業の流れについて説明していきましょう。
アップデート作業は以下の流れで行います。

git上に新しいバージョン用のブランチを作成する
composer.jsonを編集する
"composer update" を実行し、composer.jsonで定義したモジュールやライブラリが正しく更新できるか検証する
"php bin/magento setup:upgrade" を実行し、データベースを更新する
"php bin/magento setup:di:compile" を実行し、正しくビルドできるか確認する
"php bin/magento setup:static-content:deploy" を実行し、正しくテーマがビルドできるか確認する
定義済みのテストケースに沿って、動作試験を行う
検出した不具合を修正し、再テストを実施する
アップデートに伴う仕様変更・機能追加箇所を洗い出す

一つ一つの作業は特殊なものではなく、基本的には地道かつ根気のいる作業となっています。

git上に新しいバージョン用のブランチを作成する

新機能の追加や既存機能・表示の改修と同様に、アップデート作業に使用するブランチをgit上に作成しましょう。
間違っても「自分のローカルだから」とブランチを分けずに作業してはいけません。後々取り返しのつかないことになります。

composer.jsonを編集する

ブランチが作成できたら、次はcomposer.jsonを編集します。

composer.jsonはいくつかのセクションに分かれていますが、重要な部分は以下の2箇所です。

require
require-dev

requireセクション

requireセクションにはこのプロジェクトが利用するcomposer対応パッケージの名称と、バージョン番号が列挙されます。
例えばMagento Open Sourceの標準状態では、次のように定義されています。

"require": { "magento/product-community-edition": "2.4.5", "magento/composer-root-update-plugin": "~2.0", "magento/composer-dependency-version-audit-plugin": "~0.1" },

プロジェクトが利用しているモジュールの数によってこの行は増減します。
最初に行う作業は、"magento/product-community-editon" のバージョン番号をアップデート先のバージョン番号に書き換えることです。

次にその他のモジュールのバージョンを必要に応じて書き換えていきます。

require-devセクション

次に作業するのはrequire-devセクションです。
こちらのセクションでは、開発作業に必要なライブラリの指定を行っています。
Magento Open Source 2.4.5の場合は以下のようになっています。

"require-dev": {
"allure-framework/allure-phpunit": "~1.5.0",
"dealerdirect/phpcodesniffer-composer-installer": "^0.7.2",
"friendsofphp/php-cs-fixer": "~3.4.0",
"lusitanian/oauth": "~0.8.10",
"magento/magento-coding-standard": "*",
"magento/magento2-functional-testing-framework": "^3.7",
"pdepend/pdepend": "~2.10.0",
"phpmd/phpmd": "^2.12.0",
"phpstan/phpstan": "^1.6.8",
"phpunit/phpunit": "~9.5.20",
"sebastian/phpcpd": "^6.0.3",
"squizlabs/php_codesniffer": "~3.6.0",
"symfony/finder": "^5.2"
},

require-devセクションの構成やバージョン番号については、Magento Open Source / Adobe Commerceの各バージョンで少しずつ異なっています。
アップデートの際は忘れずに新しいバージョンがどのような構成になっているかを確認し、composer.jsonを書き換えるようにしましょう。

"composer update" の実行

composer.jsonの編集が終わったら、"composer update" を実行します。
composer.jsonで定義した内容に基づいて、関連するライブラリやパッケージの更新が行われます。

もし、依存関係に不適合がある場合は、不適合なライブラリやパッケージについてエラーが報告されます。
composer.jsonを修正し、"composer update" が正常終了するまで繰り返しましょう。

なお、PHPのバージョンによってはインストールされるライブラリやパッケージのバージョンが変わることがあります。
現在の2.4.4-p1 / 2.4.5 はPHP7.4とPHP8.1の両方に対応しているため、特にcomposerコマンドを実行する環境のPHPバージョンには注意しましょう。

"php bin/magento setup:upgrade" の実行

"composer update" が無事に完了したら、次はデータベースを更新します。エクステンションのインストール時にも使用する、"php bin/magento setup:upgrade" の実行です。
このとき、Magento Open Source / Adobe Commerce は developer モードで動作させるようにします。default や production モードで動作させてはいけません。

データベース更新の際、データベースに格納されているデータ量に応じて更新に必要な時間が変わります。
担当者のローカル環境であれば、多少データ量を減らした開発用のデータベースを元にして作業しても構いません。ただし、共用の検証環境や最終的なアップデートの本番適用に要する時間測定の場合は、本番環境に近いデータ量で行うようにしましょう。
サードパーティ製エクステンションの中には、バージョンアップ時にテーブル定義を大幅に変更してくるものがあり、新旧のテーブル定義間でのデータ移行に莫大な時間を要することが実際にありえます。

"php bin/magento setup:di:compile" の実行

データベースの更新ができれば、アップデート作業の一つのヤマを越えられたことになります。
次は "php bin/magento setup:di:compile" を実行して、コマンドが正常に終了するかを確認します。
ここでコマンドの実行が成功しないようであれば、エラーメッセージを確認しつつ原因の解消作業を行うことになります。

この処理が正常に完了しない場合、 production モードでの動作ができないため、アップデート後のソースを本番に反映することはできません。
（エクステンション開発をされている方にとっては普通のことですね）

"php bin/magento setup:static-content:deploy" の実行

続けて静的コンテンツのデプロイ（JSや画像の配置やlessファイルからのCSS生成など）を行います。
この処理もエラーが出る場合は原因を探して調整を行い、エラーが出なくなるまで対応を繰り返します。

テーマのカスタマイズ経験のある方にとっては馴染みのある作業ですね。

テストの実施

ここまで作業ができたら、一旦調整のできたコードをgitに反映しておきます。
その後、サイト構築時に作成したであろうテストケースに沿って、各種試験を実施します。

アップデートに伴う仕様変更などによって、想定される結果が異なるものになることがありますが、主要な機能についてはMagento Open Source / Adobe Commerceの各バージョン間で大きな違いはありません。

コアコードとセットで配布されている、各種テストケースを土台としてテストの自動化に取り組むのは非常に有効でしょう。
特にフロントエンドのE2Eテストについては、E2Eテストツールを用いた自動化が相当に効果的です。

不具合の修正と再テストの繰り返し

テストで見つかった不具合に対し、あとはひたすら修正と再テストを繰り返していきます。
不具合の検出数が収束に向かい、関係者によるリリース可能判断ができるレベルに達すれば、アップデートに伴う修正作業は完了です。

なお、アップデートに伴ってMagento Open Source / Adobe Commerce本体の不具合が発覚することがよくあります。
この場合は、

GithubでIssueが報告されていないか
既に対策のPull Requestが出されていないか、あるいはマージ済みか
Magento Quality Patchesでパッチがでていないか
Adobe Commerceのサポートに類似ケースの報告がないか（Adobe Commerceの方のみ）

という調査と対応が必要になります。

Issueは上がっているが、対応策がまだない
Pull Requestは出ているがマージされていない
Pull Requestはマージされているが、次のリリースに入るか不明

というケースは珍しくありません。

1のケースはIssueのコメントで対策が示されているケースもありますので、注意深くIssueのコメントを読む必要があります。

2と3の場合はPull Requestの実装内容を参考に、人力でコアコードにパッチを当てる必要があります。
オンプレミス版のAdobe CommerceとMagento Open Sourceの場合は比較的このあたりは柔軟に対処ができますが、クラウド版Adobe Commerceについてはクラウド環境のお作法に沿った対応が必要になります。

アップデートに伴う仕様変更・機能追加箇所を洗い出す

例えば、2.2系から2.3系への移行であれば、

非同期・バルクAPIの導入
GraphQLの導入
Multi Source Inventoryの導入
（Adobe Commerceのみ）Pagebuilderの導入
（日本語のみ）日本語化実装の変更

といった変更がありました。
2.3系から2.4系の場合は、

管理画面の二要素認証の強制化
MySQLによる商品検索機能の廃止
reCAPTCHA機能のコア実装化
Login as Customer機能の追加

といった変更があります。
もちろん更に細かいレベルや、マイナーバージョンでの仕様変更も行われているため、アップデート元バージョンとアップデート先バージョンの相違を把握しておくことは非常に重要です。

アップデートの本番適用

作業者のローカル環境での動作試験と、共有の動作検証用環境での動作試験が終わり、アップデートに要する時間についても目処が立てば、ようやくアップデートを本番適用できる運びとなります。

ここから先は

いつアップデートを行うか
メンテナンス告知をいつ出すか
作業手順に漏れや抜けがないか
万一想定通りに進まなかった場合どうするか

といった計画を詰めていくことになります。
最早この段階まで来ると、アプリケーションの不具合よりも計画や手順の漏れや抜けのチェックなどが主体になってきます。
十二分にアプリケーションのテストが行われているのであれば、滞りなく反映が行えるでしょうし、その後のトラブルも最小限に留められると思います。

まとめ

Magento Open Source / Adobe Commerceのアップデートは難しいように思われますが、手順通りにやれば他のcomposerを使用しているPHPアプリケーションと大きくは変わりません。
概してアップデートを困難にするのは以下の要因です。

安易な発想で行われたコアコードに対する改変
過剰な独自カスタマイズ
大量にインストールされたサードパーティ製エクステンション

もちろんこういったカスタマイズ・改変が行われている環境であっても、時間を掛けて一つ一つの要因を丁寧に解決していくことでアップデートの実施が可能です。