Drupal サイトの更新を成功させるための更新フックと更新後フックについて

コアの更新またはモジュールの更新中に、Drupal Web サイトの安定性と完全性を確保することが重要です。 幸いなことに、Update API モジュールと Update/Post Update フックが役に立ちます。

Update API モジュールは、Drupal サイトのコードとモジュールを更新するために必要なフックを提供します。 これらのフックは、開発者が必要に応じて更新をカスタマイズできるようにする Update および Post-Update フックに他なりません。

この記事では、更新 API、更新および更新後のフックとは何か、いつ、どのように使用する必要があるかについて説明します。 両方のタイプのフックを理解することで、最小限の労力で Drupal サイトを正常に更新できます。 始めましょう！

更新 API

既存のサイトで作業しているときに、モジュール内のコードを更新するときに、保存されたデータが新しいコードと互換性を持つように、保存されたデータを更新する必要がある場合があります。 「Web サイトで予期しないエラーが発生しました」などのエラーが目の前で点滅することに気付いたかもしれません。 怖いでしょ!? 知っている！ ここで Drupal の Update API が助けになります。

Drupal コアの同じメジャー バージョン内のモジュールの 2 つのマイナー バージョン間の更新である場合は、Update API を使用してデータを更新できます。 Update API を使用すると、モジュールがデータ モデルを変更するたびに、保存されたデータの更新を実行するコードを提供できます。 データ モデルの変更とは、既存のサイトに保存されているデータが、そのサイトの更新されたコードベースと互換性がなくなるような変更を指します。 これらのデータ モデルの変更には、次のものが含まれます。

構成スキーマの更新

• 構成キーの追加/削除/名前変更。
• 構成キーのデータ型の変更。
• 構成キーの期待されるデフォルト値の変更など。

データベース スキーマの更新

• データベース テーブルまたはフィールドの追加/変更/削除。
• 格納されたデータを別のフィールドまたはテーブルに移動する。
• 保存データのフォーマット変更など

エンティティとフィールドの更新

• 新しい基本フィールドを既存のエンティティ タイプに追加します。
• 古いタイプから新しいタイプへのフィールドの更新など。

データの更新

• 既存のサイトに保存されているデータを操作します。

更新フックの操作

フック hook_update_N() は、モジュールのマイナー バージョン間の更新を導入するために使用されます。 これらのフックは、モジュール内の*.installファイルに配置されます。

hook_update_N() は (モジュール名)_update_(番号) の形式で記述します。 ここで、 N は次のもので構成されます。

• 1 桁または 2 桁は、Drupal コアの互換性を表します (Drupal 8、9、10 など)。
• 次の 1 桁は、モジュールのメジャー リリース バージョンです。
• 01 から始まる連続カウントの下 2 桁

例：

example_update_9201(): 9.x-2.x バージョンの最初の更新。
ここで、「example」はモジュールの名前で、最初の数字は Drupal コア バージョン「9」を指し、数字「2」はモジュールのメジャー リリース バージョンを指し、最後の 2 桁「01」は最初に記述された更新関数を示します。モジュール「例」。

フック実装関数の数値部分 (つまり、上記の例では 9201) はデータベースに格納され、どの更新が既に実行されたかを追跡します。 したがって、更新関数の番号を付け直すべきではありません。
モジュール「データベースに保存された例」の現在のスキーマバージョンを知るには、次を使用します。

drush php-eval "echo drupal_get_installed_schema_version('example');"

モジュール 'example' の現在のスキーマ バージョンを手動で '9201' に戻すには、次を使用します。

drush php-eval "echo drupal_set_installed_schema_version('example', '9201');"

注: drupal_set_installed_schema_version() 関数はデータベースを直接更新するため、本番サイトでは使用しないようにしてください。 開発中にローカルまたは下位のテスト環境で使用して、スキーマ バージョンをリセットできます。

実行中にユーザー向けに出力されるため、更新フック関数の前にドキュメント ブロック コメントに適切な説明を追加します。

 Structure of hook_update_N(): /** * A aimple hook_update_N() hook. */ function example_update_9201() { // Code goes here. }

これらのフックはソートされた順序で実行されます。つまり、example_update_9201() フックは example_update_9202() の前に実行され、次は 9203、9204 などです。

フック間に依存関係を導入することで、これらのフックのソート順を変更することもできます。 フック hook_update_dependencies() を使用して、2 つの更新フック間で更新を実行します。

すべての更新フックはバッチで実行され、アイテムのバッチ処理もサポートしています。 すべての更新フックは $sandbox パラメーターにアクセスできます。これを使用して更新フックでバッチ プロセスを作成し、PHP をタイムアウトさせることなく大量のデータを一度に処理できます。

新しい構成キーを追加する更新フックの簡単な例:

現在、example_module.settings.yml ファイルには以下が含まれています。

新しいキーの「説明」を構成に追加するには:

• 設定ファイルに「説明」キーを追加します

• example_module.install ファイルに update_hook を追加します。

• drush updb を使用してフックを実行します。

• 更新された構成を確認すると、新しいキーの「説明」が更新されます。

Post Update フックの操作

update フックに似たフック hook_post_update_NAME() は、更新を導入するために使用されます。 ただし、このフックは主に、エンティティなどのデータを更新することを目的としています。 これらのフックは、すべての hook_update_N() フックが実行された後に実行されます。 この段階では、Drupal はすでに完全に修復されているため、サイト内の任意の API を使用できます。

これらのフックは、モジュールの *.post_update.php ファイルに配置されます。

hook_post_update_NAME() は (モジュール名)_post_update_(任意の名前) の形式で記述します。 ここで、 NAME は任意のマシン名にすることができます。 ファイル内の関数のこの英数字による命名は、このフックの実行順序を保証する唯一のものです。

update フックと同様に、post_update フックの前に docblock コメントに適切な説明を追加します。 また、同じフック名を再使用しないでください。

hook_post_update_NAME() の構造:

 /** * A aimple hook_post_update_NAME() hook. */ function example_post_update_test() { // Code goes here. }

update フックと同様に、$sandbox パラメーターを使用して、post_update フックに Batch API を使用する必要があることを示します。

post-update フックを使用して用語データを更新する簡単な例:

• 現在、タグの語彙の下にあるすべての用語の「テスト例」フィールドは無効になっています。

• example_module.post_update.php ファイルに post_update フックを追加して、既存のすべての用語の「Test example」フィールドを有効にします。

• drush updb を使用してフックを実行します。

• 更新された用語データを確認します。チェックボックス「テスト例」を有効にする必要があります。

これらのフックを実行する方法!

Drush コマンドを使用して、これらのフック drush updb を実行できます。次の手順でバッチをビルドします。

• すべての更新フックが検出されます。
• 依存関係を解決し、その順序を並べ替えます。
• フックはバッチ処理用に配置されます。
• 次に、すべての Post フックが検出されます。
• post_update フックがあり、 update_hook が以前に実行された場合、キャッシュはクリアされます。
• 次に、各 post_update フックをバッチにプッシュします。
• バッチを実行します。

post-update フックが update フックより優れている主な利点の 1 つは、Drupal が post-update の実行時に完全に機能することです。 これにより、開発者は post update フックを使用しながら任意の Drupal サービスを使用できます。 update フックでは、Drupal が完全に修復されたと仮定してはならず、他のフックやエンティティ API などの呼び出しを避ける必要があります。

最終的な考え

config/database スキーマを更新してサイトを修正しようとするときは、更新フックを使用してみてください。 保存されたデータの操作、構成の再保存、コンテンツ エンティティの更新、キャッシュのクリアなどに関しては、更新後のフックを使用するのがより適切です。

正直に言うと、Drupal.org には、どのフックをいつ使用するかに関する明確なドキュメントはありません。 これら 2 つのフックの使用法に関するドキュメントの改善を求める未解決の問題があり、必要に応じて貢献できます。

ただし、開発者の経験に基づいて、例として Drupal 9 & 10 コア モジュールを見て、更新フックを使用して構成またはデータベースで CRUD 操作を実行し (つまり、サイトを修復します)、CRUD コンテンツ エンティティに対して更新後フックを使用します (更新後のフックは更新フックの後に実行されるため、更新されたサイトのデータを修正します)。

この記事を読んでよかったですか？ 愛を示して、今すぐ週刊ニュースレターを購読してください!