Magento Open Source / Adobe Commerce 2.4.4がでてはや3ヶ月。来月には2.4.5がリリースされる告知が出ています。

また、MarketplaceではPHP8.1非対応のエクステンションがリストから削除され、現在掲載されているものはPHP8.1対応のものだけになっています。
（何もそこまで強行にやらなくても、とは思いますが）

さて、Magento Open Source / Adobe Commerce 2.4.4はPHP8.1に初めて対応したバージョンであり、PHP7.4が年内で公式サポート終了であることを踏まえると、それなりにアップデート作業を急がなければいけない状況にあることは間違いありません。

そこでこのエントリでは、Magento Open Source / Adobe Commerce 2.4.4とPHP8.1移行に潜む罠について解説したいと思います。

Magento Open Source / Adobe Commerce 2.4.4へのアップデート

アップデート作業自体は特に今までと大きな変更は無いのですが、2.4.4では以下のような地雷が埋まっています。

  1. composerのバージョンが違う
  2. メールテンプレートの互換性がなくなっている
  3. 都道府県のリスト表示の仕様が変わっている
  4. knockout.jsテンプレートの仕様が変わっている
  5. JavaScriptをminifyするとエラーが起きる

どれもなんだかなぁ・・・な問題ではありますが、1つずつ潰していけば対処できるものばかりなので、順に解説していきましょう。

Composerのバージョンが違う

公式のdevdocsに書いてありますが、2.4.4からはComposer 2系を使用するようになりました。
2.4.3-p2までは1系だったのですが、密かに変わっていることに注意が必要です。

2.4.3-p2以前からのアップデートの際は、composer.jsonに

"magento/composer-dependency-version-audit-plugin": "~0.1",
"magento/composer-root-update-plugin": "~2.0"

を忘れずに追記するようにしましょう。うっかり忘れるとPHP8.1にしたときに色々とエラーが出て面倒なことになります。

メールテンプレートの互換性がなくなっている

この変更自体は実は2.3.5ですでに導入されていたものです。
ただ、レガシーモードを有効にしておけば従来のテンプレートも利用可能だったので、そこまで大きな問題ではありませんでした。

2.4.4ではレガシーモードが廃止されたことによって、

  • メールテンプレートにオブジェクト型変数を渡せなくなった
  • メールテンプレートでオブジェクトのメソッドを呼べなくなった

という変化が生じています。
例えば以下のような変更ですね。

旧形式：{{var order.getEmailCustomerNote()|escape|nl2br}}

新形式：{{var order_data.email_customer_note|escape|nl2br}}

また、layoutハンドラを使う場合（例えば注文メールの明細部分など）は、以下のように表記を改める必要があります。（記事用に一部スペースを混ぜています）

旧形式：{ {layout handle="sales_email_order_items" order=$order area="frontend"} }

新形式：{ {layout handle="sales_email_order_items" order_id=$order_id area="frontend"} }

うっかりメールテンプレートの修正を忘れたままアップデートしてしまうと、自動送信メールの内容がすっぽり抜けたりするので十分注意が必要です。

都道府県のリスト表示の仕様が変わっている

「Magento 2.4.1/2.3.6以降で都道府県の並びが日本語でおかしくなる現象が発生中」で取り上げた問題が2.4.4では修正されているのですが、この修正に関連してJavaScript周りの実装が少し変わったため、2.4.3-p2までで利用できていたphtmlテンプレートが使えなくなっています。

日本語化エクステンションについては、この問題に対応したものを最新リビジョンとして公開していますので、2.4.4へのアップデートと合わせて更新が必要です。

knockout.jsテンプレートの仕様が変わっている

まず、下記の差分表示を見てください。

少し読みにくいですが、左が2.4.3−p2までの記述。右が2.4.4での記述です。
2.4.4ではknockout.jsテンプレートの記述で閉じタグを書き忘れると、うまく動かない現象が発生しています。
（もちろん<br/>のようにもともと閉じタグのないものは書かなくてもOKです）

2.4.3-p2以前からのアップデートの場合、特にカスタムテーマの調整を忘れないようにしましょう。うっかり忘れると、チェックアウト画面の住所選択ができなくなります。

JavaScriptをminifyするとエラー出る

この問題はなかなか嫌らしい問題です。

第一に、minifyをしない環境では発生しません。Productionモードでminifyを有効にしていると発生します。
現象が発生すると、以下のような問題が起きます。

  • 管理画面が正しく動かなくなる

メニューが動かなくなったり、いろいろな機能に動作不良が起きます。
この問題はすでにGithub上に報告が上がっており、2022/07/14現在では対応が完了してることになっています（ただし、関連する修正はまだマージされていません）。
つまりこの問題は2.4.4だけでなく2.4.5でも起きる可能性がある、ということになります。

対応する場合は関連する修正の内容を参考に、人力で修正を行う必要があります。
2.4.4で起きる問題の中で、一番迷惑なのはこの問題ではないかと個人的には思います。

PHP8.1へのアップデート

2.4.4へのアップデートとは別で一応作業できるものではありますが、PHP8.1へのアップデートもそれなりに面倒な作業になっています。
よく起きる問題としては、

  • インストールしているエクステンションがPHP8.1に対応していない
  • 独自開発したエクステンションがPHP8.1に対応していない
  • カスタムテーマがPHP8.1に対応していない

というものです。要はすべて同じ理由によるものです。

PHP8.1にアップデートすると、頻発する問題としてPHP公式サイトにある「推奨されなくなる機能」に関連したエラーが頻発します。
特によく目にするのは「nullableでない引数にnullを渡してしまう」というものです。

このエラーはコードを書くときに変数の型について常に意識を払わないとやってしまう系のものです。
静的型付け言語であればコンパイル時点で検出できるものですが、PHPは動的型付け言語なので、実行時にエラーが出てしまいます。

PHP8.1にアップデートすると何が嬉しい？

それなりに面倒なPHP8.1へのアップデート作業ですが、もちろんメリットもあります。
例えば以下のようなものですね。

  • PHPそのもののメンテナンス期限が延びる（2024年12月まで）
  • パフォーマンスが改善する（JITコンパイラの導入）

現在のPHPは各バージョン3年間のメンテナンスサイクルとなっているので、Magento Open Source / Adobe Commerce 本体のアップデートと合わせて、定期的にアップデートしていくようにしましょう。

まとめ

Magento Open Source / Adobe Commerce 2.4.4へ以前のバージョンからアップデートする場合、それからPHP8.1に移行する際の罠について解説しました。
きちんとテストをしておけば比較的容易に対処できるものばかりではありますが、どうしてもアプリケーション規模が大きいので作業が大変です。

事前にわかっていることについてはテスト環境に反映する前に可能な限り対処しておくほうが良いですね。

もうすぐ2.4.5もリリースされます（おそらく8月上旬）。
2.3系のメンテナンス期限も迫っていますので、アップデートを計画的に進めていきましょう。