Craft CMS をアップグレードする際に注意するポイント

先日公開された Another Sky さんの記事を読んで、「自分もそこにハマりました...」と勝手に共感。

CraftCMSのエントリフィケーション計画対応をする際に遭遇したエラー | Another Sky
https://www.anothersky.jp/2024/12/craftcms-entrification-plan.html

システム本体やプラグイン側で適切なマイグレーション処理が用意される Craft CMS では、クラスメソッドの統廃合やデータベーススキーマの変更など、アップグレードに伴ってドラスティックな変更が加えられることがあり、思わぬところでつまずきがちです。

そこで、今回は Craf CMS をアップグレードする際に注意しているポイントについて、まとめてみます。
これは Craft CMS Advent Calendar 2024 4日目の記事です。

プラグインの対応状況を確認する

新バージョンの Craft CMS がリリースされると、旧バージョンの管理画面の ユーティリティ からインストールしているプラグインの対応状況を確認できるようになります。ローカルナビゲーションにリンクが表示されない場合は、Craft CMS 本体に最新のアップデートを適用しましょう。

管理画面でプラグインの対応状況を確認

準備完了 は新バージョンに対応済み、準備ができていません は未対応、ABANDONED は開発が中止されているプラグインです。

プロジェクトの要件として必須のプラグインが未対応の場合は、対応するバージョンがリリースされるまでアップグレードを見送るか、代替プラグインを検討する必要があります。

参考までに、キャプチャ画像の例では Redactor プラグインは Craft 5 で CKEditor フィールドへコンバートする際に必要となるため、ひとまず継続利用します。Two-Factor Authentication プラグインは、Craft 5 で2要素認証が標準機能として組み込まれるため、アンインストールしても問題ありません。

公式ドキュメントを確認する

プラグインの対応状況に問題がなければ、次に公式ドキュメントのアップグレードガイドを確認しましょう。

Upgrading from Craft 3 | Craft CMS Documentation | 4.x
https://craftcms.com/docs/4.x/upgrade.html

Upgrading from Craft 4 | Craft CMS Documentation | 5.x
https://craftcms.com/docs/5.x/upgrade.html

環境変数の設定方法やテンプレートの変更方法など、アップグレードに伴う変更点が記載されていますので、事前に目を通しておくのがオススメです。

アップグレード後にフロントエンドのブラウザ表示でエラーが発生した場合も、これらのページを参考にすると大抵の問題は解決できます。

システム本体の差分を確認する

アップグレードに伴い、システム本体のファイル構成やコードが変更されることがあります。
そこで、次のコマンドでバージョンごとのプロジェクトを作成し、差分を確認しておきましょう。

Craft 3

composer create-project "craftcms/craft=^3.0.0" _craft3_default

Craft 4

composer create-project "craftcms/craft=^4.0.0" _craft4_default

Craft 5

composer create-project "craftcms/craft=^5.0.0" _craft5_default

プロジェクト作成直後のプロンプト

Welcome メッセージが表示されたら、no でコマンドを中断しておきます。

重要なポイントだと思われる差分について、いくつか抜粋してみます。

ファイル構成の差分：Craft 3 → Craft 4

ファイル構成の差分：Craft 3 → Craft 4

Craft 4 では config/db.php がなくなり、.env や web/.htaccess、bootstrap.php に変更が加えられています。ブログ記事執筆時点の Craft 5 のファイル構成は Craft 4 と同等のため、割愛します。

.env の差分：Craft 3 → Craft 4

.env の差分：Craft 3 → Craft 4

Craft 4 以降、.env に定義する定数の接頭辞を CRAFT_ とすることで、一部の環境変数や PHP 定数を直接指定できるようになりました。config/db.php が削除されたのは、この影響ですね。

Configuration
https://craftcms.com/docs/5.x/configure.html#environment-overrides

web/.htaccess の差分：Craft 3 → Craft 4

web/.htaccess の差分：Craft 3 → Craft 4

Apache 2.4 でエラーになる場合があるとのことで、Craft 4.2.0 / Craft 5.3.2 から変更になったようです。webroot が別階層にある場合、更新漏れがないように注意ですね。

[5.x]: Craft's .htaccess rewrite rule has conflicts with Apache 2.4 · Issue #15825 · craftcms/cms
https://github.com/craftcms/cms/issues/15825

bootstrap.php の差分：Craft 3 → Craft 4

bootstrap.php の差分：Craft 3 → Craft 4

PHP dotenv の初期化と PHP 定数の定義に関する変更があります。

これだけ見ると軽微に感じるのですが、過去の PHP dotenv 3.4.0 → 5.4.0 の大きな変更の際、原因に気づけずに時間を浪費したことがあります。

Moved to shared bootstrap and bump phpdotenv to 5.4 · craftcms/craft@309136a
https://github.com/craftcms/craft/commit/309136a5abb3ba48018caf10ea03b61fa4a4b744

そのため、公式に配布されている最新バージョン同士の差異だけでなく、実際にアップグレードしたいプロジェクトファイルとの差分も確認しておきましょう。

まとめ

今回ご紹介した Craft CMS のアップグレード時に注意したいポイントは、次の4点です。

  • 既存環境を最新バージョンにアップデートする
  • プラグインの対応状況を確認し、必要なら代替プラグインを検討する
  • 公式ドキュメントのアップグレードガイドを確認し、変更点を把握・対応する
  • システム本体の差分を確認し、反映漏れがないか確認する

アップグレードガイドを確認してテンプレートなどを調整していくステップが一番大変ではありますが、これらのポイントを押さえることで、思わぬトラブルを未然に防ぐことができます。