Structure Sync
構造的コンテンツ（タクソノミーターム、カスタムブロック、メニューリンク）を設定としてエクスポート・インポートし、環境間で同期します。
structure_sync
インストール
composer require 'drupal/structure_sync:^2.0'
概要
Structure Syncは、Drupal開発における一般的な課題に対応します。それは、本質的に構造的でありながら、設定エンティティではなくコンテンツエンティティとして保存されるコンテンツの同期です。DrupalのConfiguration Managementシステムはコンテンツタイプやビューなどの設定エンティティを処理しますが、タクソノミーターム、カスタムブロック、メニューリンクなどのコンテンツエンティティは管理しません。
このモジュールは、管理インターフェースとDrushコマンドの両方を提供することで、そのギャップを埋めます。これらの構造的コンテンツアイテムを設定ファイル（structure_sync.data.yml）にエクスポートできます。エクスポートされたデータはバージョン管理にコミットし、他の環境でインポートすることで、開発、ステージング、本番サイト間で一貫した構造的コンテンツを実現できます。
このモジュールは3つの異なるインポートモードをサポートしています：Full（新規アイテムの作成、既存アイテムの更新、設定にないアイテムの削除）、Safe（既存アイテムの変更や削除なしに新規アイテムのみ作成）、Force（既存アイテムをすべて削除し、設定から再作成）。この柔軟性により、チームはワークフローに適した同期戦略を選択できます。
Features
- すべてまたは選択したボキャブラリーからタクソノミータームを設定にエクスポート（カスタムフィールドや階層的な親子関係を含む）
- カスタムブロック（block_contentエンティティ）をすべてのフィールド値とともに設定にエクスポート
- メニューリンクを完全なメタデータ（リンクオプション、ウェイト、展開状態、親関係）とともにエクスポート
- 3つの異なるモードでコンテンツをインポート：Full（同期）、Safe（追加のみ）、Force（破壊的再作成）
- CI/CDパイプラインの自動化とスクリプトによるデプロイメントのためのDrushコマンド統合
- どのボキャブラリー、ブロック、メニューを同期するかを細かく制御できる選択的エクスポート/インポート
- UUIDベースのエンティティマッチングにより、環境間で一貫した識別を保証
- タクソノミータームのエンティティ参照フィールドをIDではなく名前/ボキャブラリーのペアで保存して処理
- 監査証跡用にすべてのエクスポート/インポート操作のオプションのログ記録
- タイムアウトを防ぐための大規模インポート用バッチ処理
- 変更が即座に反映されるようインポート後に自動的にキャッシュをクリア
Use Cases
複数環境へのデプロイメントワークフロー
複数の環境（ローカル、開発、ステージング、本番）を持つサイトを開発する場合、Structure Syncを使用してタクソノミーターム、メニュー構造、再利用可能なブロックの一貫性を確保します。開発環境でターム、メニュー、ブロックを作成・整理し、'drush export:all'に続いて'drush config:export'を実行します。結果のstructure_sync.data.ymlをリポジトリにコミットします。ステージング/本番環境では、変更をプルし、'drush config:import'に続いて'drush import:all --choice=full'を実行して構造的コンテンツを同期します。
事前定義された構造での初期サイトセットアップ
特定のタクソノミー構造（カテゴリ、タグ、地域など）を必要とする新しいサイトを構築する場合、開発サイトですべてのタームを作成し、エクスポートして、サイトのインストールプロファイルまたは設定に含めます。新しいインストールでは、設定インポートとstructure syncインポートを実行した直後に完全なタクソノミー構造が利用可能になります。
選択的同期によるコンテンツステージング
既存のコンテンツに影響を与えずに開発から本番に新しい構造的コンテンツを追加したい場合は、Safeインポートモードを使用します。これは、コンテンツ編集者によって作成された追加のタームやメニューアイテムが本番にあり、それらを削除すべきでない場合に便利です。
サイトの移行とクローン
サイトをクローンしたり、ホスティングプロバイダー間で移行する場合、Structure Syncは構造的コンテンツが保持され、復元できることを保証します。移行前にすべての構造的コンテンツをエクスポートし、設定で新しい環境をセットアップした後、構造的コンテンツをインポートしてサイトの組織を完全に復元します。
CI/CDパイプラインの統合
Structure Syncを継続的デプロイメントパイプラインに統合します。設定インポートが完了した後、'drush import:all --choice=full'を実行して構造的コンテンツが自動的に同期されるようにします。これにより手動ステップが不要になり、一貫したデプロイメントが保証されます。
共有構造的コンテンツによるチームコラボレーション
チーム開発環境では、Structure Syncによりチームメンバーがタクソノミー構造、メニュー設定、再利用可能なブロックをバージョン管理を通じて共有できます。ある開発者が機能に必要な新しいタームやメニューアイテムを作成したら、エクスポートしてコミットし、他の開発者はインポートして同じ構造を取得できます。
Tips
- 構造的コンテンツをエクスポートした後は必ず'drush config:export'を実行して、structure_sync.data設定をファイルに保存してください
- 本番サイトに初めて同期する場合は、ユーザーが作成したコンテンツを誤って削除しないようにSafeインポートモードを使用してください
- 完全な同期には、既存アイテムを更新し設定にないアイテムを削除するFullインポートモードを使用してください
- Forceインポートモードは開発環境のリセットに便利ですが、本番サイトでは細心の注意を払って使用してください
- エクスポートとインポートの順序が重要です：タクソノミーは通常、それらを参照するコンテンツより先にインポートする必要があります
- カスタムブロックはインポート前にブロックタイプ（バンドル）が設定されている必要があります - これは通常の設定インポートで処理されます
- メニューリンクをインポートした後、メニューが正しく表示されるようにキャッシュをクリアしてください：drush cache:rebuild
- 初期セットアップ中はログ記録を有効にしてモジュールの動作を追跡し、本番環境のパフォーマンスのために無効にすることを検討してください
- モジュールはタクソノミーとメニューリンクのインポート後に自動的にすべてのキャッシュをフラッシュして、変更が表示されるようにします
Technical Details
Admin Pages 4
/admin/structure/structure-sync/general
Structure Syncモジュールのグローバルオプションを設定します。現在、操作をDrupal watchdogに記録するかどうかを制御できます。
/admin/structure/structure-sync/taxonomies
すべてのボキャブラリーのタクソノミータームをエクスポートおよびインポートします。親子関係を持つ階層的なタームとタームに添付されたカスタムフィールドをサポートします。
/admin/structure/structure-sync/blocks
カスタムブロックコンテンツ（block_contentエンティティ）をエクスポートおよびインポートします。本文コンテンツやカスタムフィールドを含む、ブロックタイプに添付されたすべてのフィールドを処理します。
/admin/structure/structure-sync/menu-links
メニューリンクコンテンツアイテムをエクスポートおよびインポートします。メニュー階層、リンクオプション、ウェイト、有効/展開状態を保持します。
権限 1
Drush Commands 8
drush export:taxonomies
すべてのタクソノミータームを設定にエクスポートします。すべてのボキャブラリーからフィールド、階層、メタデータとともにタームをエクスポートします。
drush import:taxonomies
設定からタクソノミータームをインポートします。オプションで指定しない限り、インポートスタイル（Full、Safe、またはForce）の入力を求めます。
drush export:blocks
すべてのカスタムブロック（block_contentエンティティ）をすべてのフィールド値とともに設定にエクスポートします。
drush import:blocks
設定からカスタムブロックをインポートします。オプションで指定しない限り、インポートスタイルの入力を求めます。
drush export:menus
すべてのメニューリンクコンテンツアイテムを完全なメタデータと階層とともに設定にエクスポートします。
drush import:menus
設定からメニューリンクをインポートします。オプションで指定しない限り、インポートスタイルの入力を求めます。
drush export:all
すべての構造的コンテンツ（タクソノミー、ブロック、メニューリンク）を1回の操作で設定にエクスポートします。
drush import:all
設定からすべての構造的コンテンツ（タクソノミー、ブロック、メニューリンク）をインポートします。インポートスタイルを1回入力すると、すべてのコンテンツタイプに適用されます。
Troubleshooting 7
インポートする前にまずコンテンツをエクスポートする必要があります。'drush export:taxonomies'（またはblocks/menus）を実行し、その後'drush config:export'を実行してデータを設定ファイルに保存してください。
タクソノミータームをインポートする前にボキャブラリー設定をインポートする必要があります。まず'drush config:import'を実行してボキャブラリー定義をインポートし、その後structure syncインポートを実行してください。
親参照を持つメニューリンクでは、まず親が存在する必要があります。Structure Syncはリンクをソートして子の前に親を作成することでこれを処理します。問題が続く場合は、Forceインポートスタイルを試してメニュー構造全体を再作成してください。
'field_'で始まる名前のフィールドのみがエクスポートされます。ベースフィールドと計算フィールドは除外されます。カスタムフィールドがDrupalのフィールド命名規則に従っていることを確認してください。
大規模なインポートではタイムアウトを防ぐためにDrupalのバッチAPIを使用します。Web UIを使用してもタイムアウトが発生する場合は、Webサーバーのタイムアウト制限がないDrushコマンドを代わりに使用してください。
Safeインポートモードは、名前とボキャブラリーの組み合わせで既存のタームをチェックするだけです。既存のタームを更新する必要がある場合は、代わりにFullインポートモードを使用してください。Forceモードはすべての既存タームを最初に削除します。
Structure Syncは、TIDではなく名前/vidペアを保存することでターム参照フィールドを特別に処理します。モジュールは初期インポート後に2回目のパスを実行してこれらの参照を解決します。問題が続く場合は、インポートを再度実行してください。
Security Notes 4
- このモジュールは「サイト設定を管理」権限を必要とします。これは強力な権限であり、信頼できる管理者にのみ付与すべきです
- ブロックに非公開コンテンツが含まれている場合、エクスポートされた設定に機密情報が含まれる可能性があります - 公開リポジトリにコミットする前にstructure_sync.data.ymlを確認してください
- Forceインポートモードはそのタイプの既存コンテンツをすべて削除します - 細心の注意を払い、バックアップが存在することを確認してから使用してください
- モジュールは設定ファイルの整合性を信頼します - デプロイメントパイプラインがインポート前に設定を検証することを確認してください