前回の記事では、Craft CMS 環境を丸ごと複製する方法をご紹介しました。
既存環境と全く同じ状態を再現したいのであればそれで事足りますが、「テスト実装で開発環境に新規追加したフィールドを本番環境にも適用したい」など、システムの設定内容だけをマージしたいときはその都度管理画面を操作して反映するのが一般的かと思います。
Craft CMS では「プロジェクト構成」と呼ばれる、プロジェクトの設定内容だけを別環境に適用できる仕組みが用意され、2つの環境の差異を比較的簡単に同期できるようになっています。
そこで今回は「プロジェクト構成」機能について解説したいと思います。
これは Craft CMS Advent Calendar 2021 7日目の記事です。
「プロジェクト構成」とは
「プロジェクト構成」はデータベースに保存されているシステムの設定内容を config/project ディレクトリ配下にファイルとして出力し、それを利用して別環境へ簡単に反映できる Craft CMS の標準機能です。対象となる項目は、次の通りです。
- Craft のエディション（Solo または Pro）
- Craft 本体、および、プラグインのスキーマバージョン
- 一般設定（システム名、システムのステータス、タイムゾーン）
- サイト（サイト、サイトグループ）
- ルート
- ユーザー設定（フィールド、ユーザーグループ）
- メールの設定
- プラグイン（エディション、プラグイン設定）
- フィールド（フィールド、フィールドグループ） ※「行列」フィールドのブロックタイプを含む
- セクション（セクション、入力タイプ）
- アセット（ボリューム、画像変換）
- グローバル設定（設定のみ）
- カテゴリ（カテゴリグループ）
- タグ（タググループ）
- GraphQL スキーマ
開発環境に追加した設定を本番環境に反映するといった運用中の差分をマージする用途はもちろん、「ブログ」や「製品データ検索」などジャンルや目的別にあらかじめ用意しておいた各種設定をインストール直後にまとめて反映するいわゆる「テーマ」的な使い方もできる（別途テンプレートは要アップロード）、便利な仕組みです。
英文になりますが、公式リファレンスにも目を通してみてください。
Project Config | Craft CMS Documentation | 3.x
https://craftcms.com/docs/3.x/project-config.html#what-s-stored-in-project-config
反映するための準備
適用先環境へ反映するには、4つの工程が必要です。
- 適用先環境に既存環境と同じシステム本体、および、プラグインを準備
- 既存環境からプロジェクト構成データをダウンロード
- 適用先環境でデータベースをバックアップ
- 適用先環境にプロジェクト構成データをアップロード
順番に見ていきましょう。
適用先環境に既存環境と同じシステム本体、および、プラグインを準備
はじめに、既存環境と適用先環境の composer.json を比較し、Craft CMS 本体やプラグインの種類・バージョン指定に差異がないか確認します。
「プロジェクト構成」ではプラグインのインストール状況やプラグイン設定の内容なども同期対象となるため、適用前後の環境で同じパッケージが用意されていないとエラーで処理が止まってしまいます。 厳密にすべて同じバージョンでなくても反映できる場合があるものの、揃えておくとスムーズに進められるでしょう。
もし差分があった場合は、適用先環境の composer.json を調整後、composer install コマンドを実行しパッケージをインストールしておいてください。
既存環境からプロジェクト構成データをダウンロード
適用元となる既存環境の管理画面で「ユーティリティ > プロジェクト構成」に移動し、「構成をリビルドする」ブロックにある リビルド ボタンをクリックします。
これによりデータベースに保存された設定内容で config/project ディレクトリ配下のファイルが上書きされます。（ごく稀にデータベースと出力ファイルで差分が生じる場合があることから、念のための操作です。）
次に、同じ画面の下段「ロードされたプロジェクト構成データ」ブロックにある ダウンロード ボタンをクリックし、project.zip を取得します。なお、「ロードされたプロジェクト構成」とはデータベースに保存されている内容を指します。
適用先環境でデータベースをバックアップ
これ以降の適用先環境の操作により万一問題が生じた場合でも元の状態に戻せるよう、データベースをバックアップしておきます。
サンプルはインストール直後の Solo エディションに Environment Label プラグインをインストールしただけの状態のため、左側のメニューが4項目しかありません。これを適用元と同じ状態にするのが「プロジェクト構成」機能だとイメージいただければと思います。
適用先環境にプロジェクト構成データをアップロード
既存環境からダウンロードした projext.zip を展開し、適用先環境の config ディレクトリ直下にアップロードします。config/project が既に存在する場合、project ディレクトリごと上書きして問題ありません。
これで「プロジェクト構成」を適用先環境に反映するための準備が整いました。
プロジェクト構成を適用する
Craft CMS ではデータベースの設定内容と config/project 配下のファイルに定義された内容が異なる場合、管理画面のヘッダーに警告テキストが表示されます。そこに含まれる 確認 ボタンをクリックするか、「ユーティリティ > プロジェクト構成」に移動してください。
「YAMLの変更を適用する」ブロックに表示されている差分を確認し、問題なければ 変更箇所のみ適用する または すべてを再適用する ボタンをクリックします。どちらにするか迷うときは「すべての変更を表示する」をクリックし、差分を精査して判断するとよいでしょう。
いずれかのボタンをクリックすると、最終確認の画面になります。
アップロードした config/project の内容を適用してよければ YAMLファイルを使用する ボタンをクリックします。
登録データはありませんが、既存環境と同じ構造を持つ Craft CMS 環境ができました。
適用先環境でプラグインバージョンなどに問題がある場合
新しいプロジェクト構成を適用する際、プラグイン本体のデータが存在しなかったり、バージョン違いで互換性がなかったりすると警告が表示され処理が中断します。
前述の通り、適用前後の環境にある composer.json を同じ状態にしてcomposer install コマンドを実行すれば解消されます。
その他、解消できないエラーに見舞われた場合は、事前に取得しておいたバックアップデータでデータベースをリストアし元の状態に戻しましょう。
まとめ
今回は、異なる Craft CMS 環境のシステム設定の差分を同期する方法について解説しました。
システム設定の差分を手作業で反映する場合、作業の抜け・漏れやテンプレートから参照するハンドル名の TYPO など、ちょっとしたミスで期待した動作にならない（とはいえ、どこに原因があるのか...）ということは起こりがちですよね？
その点 Craft CMS の「プロジェクト構成」機能を利用すれば、ケアレスミスの防止や作業の効率化を図るだけでなく、「Craft CMS を安全に利用するために」で触れた、環境設定 allowAdminChanges を無効化した状態でもシステム設定を変更することが可能です。
気になる方は、ぜひ一度試してみてください。