Drupalの構成ファイルを環境ごとに切り替えられる「Configuration Split」モジュールの紹介

■概要

本記事では、DrupalのConfiguration Splitモジュール[1]を紹介します。

Drupalでは、サイトの構成ファイル(コンテンツタイプやフィールド、サイトの設定など)をyml形式でDrushコマンドなどで出力し各環境で共有することができます。[2]
ここで一部の設定を、「環境ごとに切り替えたい、でもいちいち手動で変更したくない」「環境固有の設定のせいでGitに差分が出るのが嫌だ」 という時Configuration Splitを導入することで、環境ごとに有効化するファイルを切り替えたり、特定の環境では別の設定に上書きすることができるようになります。[3]

まず、Drupalにおける構成ファイルの出力方法を説明します。
その後、Configuration Splitモジュールの導入手、そして構成ファイルの分割設定と設定後の使い方を例を示して紹介します。

今回は、Configuration Splitモジュールの8.x-1.9バージョンを使用します。
2023/03/17現在最新の、2.0.0-rc4バージョンとは少し挙動や設定項目が異なるので注意してください。

■目次

• ■作業環境情報
• ■前提条件
  • ディレクトリ構造
• ■構成ファイルの出力手順
• ■構成ファイルの分割
  • Configuration Split モジュール導入手順
  • 構成ファイルの分割ルール設定手順の例
  • サイトの設定を変更し、分割構成ファイルを出力する
• ■分割した構成を環境ごと取り込むか否か制御できることを試す
  • ①分割設定を取り込まないパターン
  • ②分割構成を取り込むパターン
• ■参考文献
• ■付録
  • A. Configuration Split setting画面の各項目
  • B. Configuration Splitモジュールで追加されるDrushコマンド

■作業環境情報

• Mac: 12.6.3
  • Apple M1
• Lando: v3.11.0
  • Docker Desktop: 4.16.2
    • Engin: 20.10.22
  • PHP: 8.1.10
  • Mysql: 5.7.29
  • Drupal: 10.0.5
    • Drush: 11.5.1
• Apache: 2.4.54 (Debian)
• Git: 2.36.1

■前提条件

• Drupal環境構築済み
  • Drush インストール済み

ディレクトリ構造

drupal_config_split
├── composer.json
├── composer.lock
├── config
├── vendor
└── web
    ├── INSTALL.txt
    ├── README.md
    ├── autoload.php
    ├── core
    ├── example.gitignore
    ├── index.php
    ├── modules
    ├── profiles
    ├── robots.txt
    ├── sites
    ├── themes
    ├── update.php
    └── web.config

■構成ファイルの出力手順

Drupalでは、サイトの構成ファイル(コンテンツタイプやフィールド、サイトの設定など)をyml形式で出力し各環境で共有することができます。

構成ファイルは以下の手順で出力することができます。

1. web/sites/default/settings.php の以下の項目を変更します。

   # $settings['config_sync_directory'] = '/directory/outside/webroot';
   ↓
   $settings['config_sync_directory'] = '../config/sync';
   

   ＊この項目は、構成ファイルの出力先を指定しています。ここでは、drupal_config_split/config/sync ディレクトリの下に出力する設定にします。

2. 次のDrushコマンドをターミナルで実行します。

   • lando drush config:export -y
     • ＊lando環境の場合、一部のコマンドの頭にlandoをつける必要があります。

3. 以下のような実行結果がターミナルに表示されます。

    [success] Configuration successfully exported to ../config/sync.
   ../config/sync
   

4. config/sync ディレクトリの中を確認すると、以下のように構成ファイルが出力されていることがわかります。

   tree -L 1 config/sync
   

   config/sync
   ├── automated_cron.settings.yml
   ├── block.block.claro_breadcrumbs.yml
   ├── block.block.claro_content.yml
   ├── block.block.claro_help.yml
   ├── block.block.claro_local_actions.yml
   ├── block.block.claro_messages.yml
   ├── block.block.claro_page_title.yml
   ├── block.block.claro_primary_local_tasks.yml
   ├── block.block.claro_secondary_local_tasks.yml
   ├── block.block.olivero_account_menu.yml
   ├── block.block.olivero_breadcrumbs.yml
   ├── block.block.olivero_content.yml
   ├── block.block.olivero_help.yml
   ├── block.block.olivero_main_menu.yml
   ├── block.block.olivero_messages.yml
   ├── block.block.olivero_page_title.yml
   ├── block.block.olivero_powered.yml
   ├── block.block.olivero_primary_admin_actions.yml
   

   ＊後半省略。合計 192 個の構成ファイルが出力された。
   

これらのファイルをGitなどで他の環境に共有し、インポートすることで設定内容を同期することができます。
＊以降、ここで出力された構成ファイルをBase構成ファイルと記述します。


Note: 後々構成ファイルの差分がわかりやすいようにgit initしてここまでの作業をコミットしておきます。vendorディレクトリとweb/sites/defalt/filesディレクトリはGit管理から除外します。

■構成ファイルの分割

＊以降、Configuration Splitモジュールによって分割された構成ファイルを、分割構成ファイルと記述します。
＊以降、Base構成ファイルが保存されているディレクトリをBaseディレクトリ、分割構成ファイルが保存されているディレクトリを分割ディレクトリと記述します。

今回は、「サイトの基本設定にある、メールアドレスをローカル環境とリモート環境で切り替える」という想定で設定していきます。
リモート環境の設定がBase構成(config/sync)で、ローカル環境の時だけ分割構成ファイルを読み込んで設定を変えるというイメージです。

Configuration Split モジュール導入手順

1. モジュールをインストールします。

   lando composer require drupal/config_split 
   

2. モジュールを有効化します。

   lando drush en config_split
   

   The following module(s) will be enabled: config_split, config_filter
    Do you want to continue? (yes/no) [yes]:
   

   Enterを押下します。 次のメッセージが出力されれば成功です。
   

    [success] Successfully enabled: config_split, config_filter
   

構成ファイルの分割ルール設定手順の例

作業を始める前に、現在の構成ファイルをエクスポートしておきます。
lando drush cex -y

＊DBに保存されている構成と、出力されているBase構成ファイルに差分がないようにします。
＊ここまでの作業をコミットしておきます。

1. Configuration Split setting画面にアクセスします。
   • /admin/config/development/configuration/config-split
2. 「+ Add Configuration Split setting」ボタンを押下します。
   • 構成分割設定を追加するForm画面に遷移します。
   • 設定画面の各項目の説明は付録Aを参照してください。
3. 以下の内容で入力、保存します。記載のない項目はデフォルト値です。
   • ラベル：local
   • システム内部名称：local
   • Folder：../config/local
   • Conditional Split > Configuration items：system.site をチェック

4. Folderに指定したディレクトリを作成します。

   • mkdir config/local

   ├── config
       ├── local
       └── sync
   

5. サイトのキャッシュをリビルドします。

   • lando drush cr

これで準備は完了です。

サイトの設定を変更し、分割構成ファイルを出力する

1. サイトの基本設定画面にアクセスします。
2. 「メールアドレス」フィールドを編集して保存します。
   • 変更内容：cst@example.com → cst_local@example.com
3. 以下のコマンドで分割構成ファイルをエクスポートします。
   • lando drush config-split:export local

4. すると、config/localディレクトリに以下のような分割構成ファイルが生成されます。

   config/local
   └── system.site.yml
   

   ファイルの内容

   _core:
   default_config_hash: VDJxTZtQR21qB4lvOq8zszJZLvLKrSPQpdn2E3T71Ww
   langcode: ja
   uuid: 78e0adeb-d815-4d89-8384-535a765a55a7
   name: 'Config Split Test'
   mail: cst_local@example.com
   slogan: ''
   page:
   403: ''
   404: ''
   front: /node
   admin_compact_mode: false
   weight_select_max: 100
   default_langcode: ja
   

5. 分割設定の設定ファイルを出力します。

   • lando drush cex -y

6. ＊ここまでの作業をコミットしておきます。

7. Base構成ファイルとの差分は以下のようになりました。

   diff -U 0 config/sync/system.site.yml config/local/system.site.yml
   

   --- config/sync/system.site.yml 2023-03-17 13:40:41.000000000 +0900
   +++ config/local/system.site.yml    2023-03-17 14:47:12.000000000 +0900
   @@ -6 +6 @@
   -mail: cst@example.com
   +mail: cst_local@example.com
   

＊cst@example.com がBase構成ファイル、cst_local@example.comが分割構成ファイルの記述。

■分割した構成を環境ごと取り込むか否か制御できることを試す

①分割構成を取り込まないパターン

＊リモート環境で構成ファイルをインポートするという体で作業
＊現在サイトデータベースに保存されている構成）のアドレスは分割構成の設定になっています。

1. web/sites/default/settings.php に以下の設定を書き込んで、分割設定「local」を無効化します。

   $config['config_split.config_split.local']['status'] = FALSE;
   

2. サイトのキャッシュをリビルドします

   • lando drush cr
3. 構成をインポートします。
   • lando drush cim -y

4. サイトの基本設定にアクセスして確認します。

   

Base構成の設定が取り込まれました！

②分割構成を取り込むパターン

＊ローカル環境で構成ファイルをインポートする体で作業

＊現在サイトのアドレスはBase構成の設定になっている。
＊エクスポートしていないので、構成ファイルはパターン①から変わっていません。

1. web/sites/default/settings.php に以下の設定を書き込んで、分割設定「local」を有効化します。

   • ＊以下記述を追加することで、サイト実行時に分割設定「local」> アクティブのON/OFFを上書きできます。[4]

   $config['config_split.config_split.local']['status'] = TRUE;
   

2. サイトのキャッシュをリビルドします

   • lando drush cr
3. 構成をインポートします。
   • lando drush cim -y

4. サイトの基本設定にアクセスして確認します。

   

分割構成の設定が取り込まれました！

使い方のほんの一例ですがこれで紹介は終了です。

---

■参考文献

• [1] Configuration Split | Drupal.org
• [2] Workflow using Drush | Configuration management | Drupal Wiki guide on Drupal.org
• [3] Configuration Split | Contributed modules | Drupal Wiki guide on Drupal.org
• [4] Configuration override system | Configuration API | Drupal Wiki guide on Drupal.org

■付録

A. Configuration Split setting画面の各項目

Configuration Split setting画面の各項目について、簡易に説明します。 一部は省略しています。

入力項目名	説明
ラベル	この設定の表示名。
システム内部名称	この設定のマシン名 = Entity ID。
Static Settings > 説明	この設定に関する備考や用途、他の開発者向けのメッセージなどを記載できます。
Static Settings > Folder	分割された構成ファイルの出力先を指定します。 通常、メインの構成ファイルが出力されているディレクトリの兄弟ディレクトリになるように設定する必要があります。 また、分割構成ファイルのディレクトリ名は、システム内部名称と一致させる必要があります。
Static Settings > ウェイト	この設定の優先順位です。 昇順で適用されます。つまり大きいほど優先されます。
Static Settings > アクティブ	ON(TRUE) の時、この分割設定が有効化され、インポート時に設定が取り込まれます。 OFFにすると、インポート・エクスポートどちらも無視されます。 分割構成ファイルをエクスポートするときはONにする必要があります。
Complete Split	指定したモジュールの関連構成ファイル、または個別に指定した構成ファイルをファイルごと分割します。 Baseディレクトリから指定された構成ファイルが削除されます。
Conditional Split	指定した構成ファイルの差分のみ記録します。 baseファイルは削除されず、インポート時に差分だけ取り込まれます。

B. Configuration Splitモジュールで追加されるDrushコマンド

config-split:
  config-split:export (csex)     Export only split configuration to a directory.
  config-split:import (csim)     Import only config from a split.

• 使用例
  • drush config-split:export local