Helper
設定、Entity、メニュー、Theme、Layout Builder などの操作を支援するユーティリティサービス、Drush コマンド、開発ツールを提供する包括的な開発ヘルパーモジュール。
helper
インストール
composer require 'drupal/helper:8.x-1.40'
composer require 'drupal/helper:8.x-1.39'
概要
Helper モジュールは、一般的な Drupal 開発タスクを簡素化するユーティリティサービスと開発ツールのコレクションを提供します。設定管理、Entity 操作、メニュー構築、Theme 管理、Layout Builder、テキストフォーマット、ファイル処理などのための幅広いヘルパークラスとサービスを提供します。
このモジュールは、コンテンツ Entity の一括更新、設定のインポート/エクスポート、インストールプロファイルの切り替え、Plugin 管理、各種の配列/HTML/レンダー要素操作に再利用可能なユーティリティ関数を必要とする開発者に特に役立ちます。また、キャッシュ管理とモジュールスキーマバージョン制御のための追加の Drush コマンドや、素早いキャッシュクリア操作のための Admin Toolbar Tools との統合も提供します。
このモジュールには、一意の Field 値を保証するためのバリデーション制約、開発/テスト用のロギングメールバックエンド、Entity 選択用のフォーム要素、Node Field をレンダリングするための Block が含まれています。また、サブ Theme がベース Theme からリージョンを継承できる Theme 継承機能も追加されています。
Features
- シンプルな設定と Config Entity の両方のインポート、エクスポート、管理をサポートする設定ヘルパーサービス(モジュールベースおよびディレクトリベースの操作に対応)
- post-update hook で大量の Entity を効率的に処理するためのコンテンツ Entity 一括更新ユーティリティクラス(エラーハンドリングと進捗追跡機能付き)
- プロファイル切り替え前に依存関係、要件、拡張機能の可用性を検証するインストールプロファイル切り替えサービス
- メニューをプログラム的に構築し、Link Field をメニュー構造に変換し、メニュー項目属性を管理するためのメニューヘルパーサービス
- アクティブ/デフォルト Theme の確認、ベース Theme 継承の管理、デフォルト Theme のプログラム的設定のための Theme ヘルパーサービス
- Entity のレイアウト状態の確認、オーバーライドされたレイアウトの管理、レイアウト Plugin の抽出のための Layout Builder ヘルパーサービス
- filter_html 制限からタグと属性を追加/削除するためのテキストフォーマットヘルパーサービス
- ファイル Entity の作成/再利用およびファイル URI からデータ URI への変換のためのファイルヘルパーサービス
- Node プレビュー、REST エンドポイント、Layout Builder ページを含むルートマッチから現在のページ Entity を検出するための現在 Entity サービス
- セレクトフィールド用の Entity オプションを生成するための Entity タイプヘルパー
- Plugin コールバックの呼び出しと Plugin オプションリストの生成のための Plugin ユーティリティクラス
- 値/キーの置換、一意性チェック、フィルタリング、均等分割のためのメソッドを持つ配列ヘルパー
- 要素のラッピング、ライブラリのアタッチ、ヘッダー、フィード、アクセス管理のためのレンダー要素ユーティリティ
- マークアップから HTML コメントを削除するための HTML ヘルパー
- 一意のシャットダウン関数登録、ネストされたバッチ実行、文字列のキャメルケース変換のためのユーティリティクラス
- テンプレートでファイルをデータ URI として埋め込むための file_data_uri() 関数を提供する Twig 拡張
- Flush PHP、Flush Libraries、Flush Bootstrap メニュー項目を追加する Admin Toolbar Tools 統合
- ライブラリ/ブートストラップキャッシュのクリア、インストールプロファイルの切り替え、モジュールスキーマバージョンの管理、post-update hook のリセットのための Drush コマンド
- コンテンツエリア外の Block リージョンで任意の Node Field をレンダリングするための Node Field Block
- 指定されたタイプの Entity で入力されたセレクトフィールドを作成するための Entity Select フォーム要素
- Entity Field 内の一意の値を保証するためのバリデーション制約
- 送信する代わりにメールをログにキャプチャするロガーメールバックエンド(開発/テストに便利)
- 自動エンコードを行う PSR-7 レスポンス用の JSON レスポンスクラス
- JSON データの読み書き用のキャッシュサポート付き JSON および Composer ファイルヘルパー
- 設定変更時の簡単なキャッシュ無効化のための Config キャッシュタグ無効化イベントサブスクライバ
- 型付き設定バリデーションを持つ設定フォームを作成するための ValidatableConfigFormBase 抽象クラス
- inherit_regions フラグを介して Theme がベース Theme からリージョンを継承できるサブ Theme リージョン継承機能
- コンテンツ依存を避けるためにデフォルトレイアウトでのインラインブロックを防止する Layout Builder インラインブロックバリデーション
- フォームの novalidate 属性を無効にするための Core フォーム HTML5 バリデーショントグル
- textarea_widget_for_text モジュールの代替としてテキストフィールドタイプ用のテキストエリアウィジェット有効化
- プロバイダモジュールによる不要なレイアウト Plugin のフィルタリングのための Core レイアウトプロバイダ非表示機能
Use Cases
post_update hook でコンテンツ Entity を一括更新する
ContentEntityUpdater を使用して、データベース更新中に大量の Entity を効率的に処理します。このユーティリティはバッチ処理、エラーハンドリング、進捗追跡を自動的に処理します。例:post_update 関数ですべてのタクソノミータームの名前を小文字に更新する場合など。
プログラム的に設定をインポート/エクスポートする
helper.config サービスを使用して、ファイルやディレクトリから設定をインポートしたり、アクティブな設定をファイルにエクスポートしたり、モジュール設定を同期したりします。デプロイスクリプト、インストールプロファイル、設定管理ワークフローに便利です。
再インストールなしでインストールプロファイルを切り替える
install-profile:switch Drush コマンドまたは helper.install_profile サービスを使用して、あるインストールプロファイルから別のものに切り替えます。バリデーションにより、すべての依存関係が満たされ、切り替え前に拡張機能が孤立しないことが保証されます。
Link Field からメニューを構築する
helper.menu サービスを使用して、Link Field の値をナビゲーションメニューとしてレンダリングします。これにより、コンテンツ編集者は Entity 上の Link Field を通じてメニューのようなナビゲーションを作成できます。
プログラム的にデフォルト Theme を確認・設定する
インストールプロファイルや update hook で helper.theme サービスを使用して、Theme がアクティブかどうかを確認し、プログラム的にデフォルト Theme を設定します。
テキストフォーマットの許可 HTML タグを変更する
helper.text_format サービスを使用して、モジュールのインストールや更新時にテキストフォーマット設定の許可タグと属性をプログラム的に追加または削除します。
Entity セレクトフォーム要素を作成する
helper_entity_select フォーム要素を使用して、特定のタイプの Entity で入力されたセレクトフィールドを作成します。Entity を参照する必要がある設定フォームに便利です。
Block リージョンに Node Field を表示する
Node Field Block を使用して、通常のコンテンツエリア外の Block リージョンに任意の Node Field を表示します。フッターコンテンツ、サイドバー、または Node 固有のデータを表示する必要がある他のリージョンに便利です。
サブ Theme リージョンの継承
サブ Theme の info.yml ファイルに inherit_regions: true を追加して、ベース Theme からすべてのリージョンを自動的に継承し、リージョン定義を複製する必要を回避します。
開発用メールロギング
helper_logger メール Plugin をデフォルトのメールバックエンドとして設定し、すべてのメールを送信する代わりにデータベースログにキャプチャします。開発およびテスト環境に便利です。
再実行のために post-update hook をリセットする
module:post-update:reset Drush コマンドを使用して、再度実行する必要がある post-update hook をリセットします。update hook の開発とデバッグに便利です。
Twig テンプレートでファイルをデータ URI として埋め込む
file_data_uri() Twig 関数を使用して、小さなファイル(アイコンやロゴなど)を base64 エンコードされたデータ URI としてテンプレートに直接埋め込み、HTTP リクエストを削減します。
Tips
- post_update hook でのバッチ処理には ContentEntityUpdater を使用 - バッチ処理、エラー回復、進捗追跡を自動的に処理します
- helper.config サービスはシンプルな設定と Config Entity の両方を透過的にサポート - それらを異なる方法で処理する必要はありません
- 開発中のデバッグを容易にするため、helper.settings で core_form_novalidate を true に設定してグローバルに HTML5 バリデーションを無効化
- 開発中は helper_logger メール Plugin を使用して、すべてのメールを送信する代わりにログにキャプチャ
- サブ Theme の info.yml ファイルに inherit_regions: true を追加して、ベース Theme のリージョンを自動的に継承
- ContentEntityUpdater は「entity_type:bundle1:bundle2」形式を使用して特定のバンドルへの制限をサポート
Technical Details
Admin Pages 3
/admin/flush/php
opcache、APC キャッシュ、ファイルステータスキャッシュを含む PHP キャッシュをクリアします。Admin Toolbar Tools モジュールがインストールされている場合のみ利用可能です。
/admin/flush/libraries
ライブラリキャッシュをクリアし、CSS/JS アセットを無効化します。Admin Toolbar Tools モジュールがインストールされている場合のみ利用可能です。
/admin/flush/bootstrap
Drupal ブートストラップキャッシュをクリアします。Admin Toolbar Tools モジュールがインストールされている場合のみ利用可能です。
Hooks 1
hook_helper_current_entity_from_route_match_alter
モジュールがルートマッチから現在のページ Entity として検出された Entity を変更できるようにします。
Drush Commands 8
drush cache:clear libraries
ライブラリキャッシュをクリアし、CSS/JS アセットを無効化します
drush cache:clear bootstrap
ブートストラップキャッシュをクリアします
drush install-profile:switch
サイトを現在のインストールプロファイルから新しいものに切り替えます。切り替え前に依存関係と要件を検証します。
drush module:schema-version:get
モジュールの現在のスキーマバージョンを取得します
drush module:schema-version:set
モジュールのスキーマバージョンを設定します。current+1 や current-3 のような相対値をサポートします。
drush module:schema-version:delete
モジュールのスキーマバージョンを削除します。削除されたモジュールの残りスキーマをクリーンアップするのに便利です。
drush module:schema-version:cleanup
存在しなくなったモジュールのスキーマバージョンをクリーンアップします
drush module:post-update:reset
次のデータベース更新時に再度実行されるように post-update hook をリセットします
Troubleshooting 3
切り替えを試みる前に、新しいインストールプロファイルに必要なすべてのモジュールがすでにインストールされていることを確認してください。validateProfile() メソッドを使用して、最初に要件を確認してください。
これは Config Entity に関する Drupal Core の既知の問題です。この問題を解決するパッチについては https://www.drupal.org/project/drupal/issues/3367492 を参照してください。
Flush PHP、Flush Libraries、Flush Bootstrap ルートは、Admin Toolbar Tools モジュールがインストールされ有効になっている場合にのみ表示されます。
Security Notes 3
- インストールプロファイル切り替え機能は、完全なシステムアクセス権を持つ管理者のみが使用すべきです
- helper_logger メール Plugin は、ログにメール内容が公開されるため、開発/テスト環境でのみ使用すべきです
- Composer ファイルヘルパーにはシェルコマンドを実行する exec() メソッドが含まれています - 使用時は適切な入力エスケープを確認してください