プロジェクトコンフィグ

Craft はそれぞれのプロジェクトの設定をプロジェクトコンフィグと呼ばれる中心的な保管場所に維持します。

システム設定に変更を加えると、Craft はそれらの設定値を config/project/ フォルダの YAML ファイルに記録します。テンプレートやフロントエンドのリソースのように、それらのファイルを Git リポジトリにコミットできます。

これには2つの利点があります。

  1. プロジェクトの状態変化を時間の経過とともに追跡できるようになります。
  2. 手動で適用することなく、新しい変更内容を他の開発環境 / ステージング環境 / 本番環境に適用できます。

# プロジェクトコンフィグに保存されるもの

  • アセットボリューム、および、名前付けされた画像変換
  • カテゴリグループ
  • Craft、および、プラグインのスキーマのバーション
  • Craft のエディション
  • メールの設定
  • フィールド、および、フィールドグループ
  • グローバル設定(設定のみ、コンテンツを含みません)
  • GraphQL スキーマ、および、パブリックスキーマのアクセス設定
  • 行列ブロックのタイプ
  • プラグインのエディション、および、設定
  • 「設定 > ルート」のルート定義
  • セクション、および、入力タイプ
  • サイト、および、サイトグループ
  • システム名、タイムゾーン、および、システムのステータス(稼働中 / オフライン)
  • タググループ
  • ユーザー設定、および、ユーザーグループ

プラグインがプロジェクトコンフィグに追加情報を保存できます。どのようにするかを知るには、プロジェクトコンフィグのサポートを参照してください。

# 環境のセットアップ

環境をまたいでプロジェクトコンフィグの変更内容を伝播しはじめる前に、それぞれの環境が同じ状態になっていることを確認してください。

  1. 最新のデータを持つ、プライマリ環境を選択してください。(すでに稼働しているプロジェクトの場合、これは本番環境であるべきです。)
  2. プライマリ環境が Craft の最新版で稼働していることを確認してください。
  3. その環境で「ユーティリティ > プロジェクト構成」に移動し、「リビルド」ボタンをクリックして、プロジェクトコンフィグがデータベースのいたるところに保存されている設定と共に最新の状態であることを確認してください。
  4. プライマリ環境のデータベースをバックアップしてください。
  5. 他の環境では、前のステップで作成したデータベースのバックアップを復元し、config/project/ フォルダのコンテンツを削除してから、ブラウザでサイトを読み込んで動作確認をしてください。(Craft は初めてコントロールパネルにアクセスされた際、config/project/ に YAML ファイルを再生成します。)
  6. 将来的に変更内容が予期せず失われることを防ぐため、開発環境以外のすべての環境でコンフィグ設定 allowAdminChanges を無効にしてください。

他の環境に config/project/ フォルダの変更内容を伝播しはじめる準備ができました。

# 変更内容の伝播

開発環境で変更を加えると、config/project/ フォルダのコンテンツがその変更内容を反映して更新されていることに気づくでしょう。テンプレートやフロントエンドのリソースのように、それらのファイルを Git リポジトリにコミットしてください。

他の環境に変更内容をデプロイする場合、次の2つの方法のいずれかでプロジェクトコンフィグの変更内容を 適用 できます。

  1. コントロールパネルの「プロジェクト構成」ユーティリティから。
  2. ターミナルコマンド php craft project-config/apply を実行することによって。

いずれの方法でも、Craft はローカルの config/project/ フォルダのファイルと既に読み込まれたプロジェクトコンフィグを比較して、見つかった変更内容を取り込みます。

# 注意事項

プロジェクトコンフィグで作業する場合、注意すべきことがいつくかあります。

# Composer がいるでしょう

プロジェクトコンフィグが変更されたことを Craft が検知すると、YAML に記載された Craft およびプラグインのバージョンが実際にインストールされているものと互換性があることを確認します。

それらに矛盾があった場合、Craft がファイルの変更をプロジェクトコンフィグへ同期する前に修正する必要があります。矛盾が解消されるまでコントロールパネルへのアクセスが拒否されるため、修正する唯一の実用的な方法は composer install を実行することです。

php craft project-config/apply の前に、必ず composer install を実行すると良いでしょう。

# 機密情報はプロジェクトコンフィグの YAML に保存できます

システムコンポーネントのいくつかは、それらの設定に次のような機密情報を必要とすることがあります。

  • メール設定の Gmail / SMTP パスワード
  • AWS S3 ボリュームのシークレットアクセスキー

これらの値が YAML ファイルに保存されるのを防ぐには、フィールドに環境変数をセットしていることを確認してください。詳細については、環境設定を参照してください。

# 本番環境の変更は忘れられるかもしれません

本番環境でプロジェクトコンフィグの YAML を更新するアップデートが行われた場合、次にプロジェクトがデプロイされ config/project/ が上書きされるタイミングで、それらの変更が失われるかもしれません。そのため、シンプルな Git ベースのデプロイではこれらの変更がコンフリクトの原因となり、デプロイの成功を 妨げる でしょう。

これらの状況を防ぐために、config/general.php のコンフィグ設定 allowAdminChangesfalse に設定してください。

return [
    '*' => [],
    'production' => [
        // Disable project config changes on production
        'allowAdminChanges' => false,
    ],
];

それによって、プロジェクトコンフィグに影響を与えるほとんどの管理設定の UI が削除されます。さらに、プロジェクトコンフィグは読み取り専用状態となるため、YAML が改竄される可能性がなくなります。

# 設定データが同期しなくなる可能性があります

手動、または、適切なサービスを利用していないプラグイン / モジュール経由で、プロジェクトコンフィグによって管理されている設定がデータベースの他の場所で変更されている場合、プロジェクトコンフィグはデータベースの値と同期しなくなり、おそらくエラーになるでしょう。そうなった場合、Craft はプロジェクトコンフィグを修正するために実行できるコンソールコマンドを提供します。

php craft project-config/rebuild

プロジェクトコンフィグを同期する1つの方法は、config/project/ をバージョン管理して、Craft の変更を適用するためのコンソールコマンドを使用することです。

php craft project-config/apply

適用処理中に変更が検知されない場合、--force オプションを利用できます。

php craft project-config/apply --force

これですべてのプロジェクトコンフィグの値が追加、または、更新されたものとして扱われ、結果的に同期プロセスが長くなり、データベースで優先されることを期待された変更を上書きしてしまう可能性があります。

# オプトアウト

プロジェクトのルートにある .gitignore ファイルに次の行を加えることで、プロジェクトコンフィグのファイルを他の環境と共有しないようオプトアウトできます。

/config/project

そして、次のターミナルコマンドを実行し、リポジトリから既存の config/project/ ファイルをすべて削除します。

git rm -r --cached config/project/\*
git commit -a -m 'Remove project config files'

Craft は config/project/ フォルダ内の YAML ファイルへ変更内容を記録し続けますが、プロジェクトの Git リポジトリにコミットされたり、他の環境に共有されることはなくなります。