【Drupal】モジュール開発者が知っておくべき18の黄金律（ベストプラクティス）
この記事は以下の記事を参考に一部加筆してご紹介しています。
Drupal 8 Module Development: 18 Best Practices to Follow
(That Most Drupal Developers Seem to Agree Upon)
翻訳には当サイトのテンプレート「DeepL版プロの翻訳家 」を使用しています。AI翻訳のため一部訳がおかしい箇所がありましたらご容赦ください。
Drupal をカスタム機能で拡張し、コーディングの標準を守り、新しいモジュールがDrupalのアーキテクチャに完璧にフィットすることは、非常に困難です。
そこで、Drupal カスタムモジュール開発のベストプラクティスが役立ちます。27人のDrupal開発者にインタビューし、彼らがDrupal で新しいモジュールを作成する際に守っている "黄金ルール "を教えていただきました。
彼らの回答の中で最も多く登場した18の推奨事項をご紹介します。
黄金律1：モジュールのデバッグにはXdebugを使用する
Zend Studio あるいは Eclipse 、最近ではVisual Codeを使用することも可能です。 また有償ですがPHPSORMを使用すると作業がはかどります。
コードをデバッグして、次のことを確認しましょう：
PHP コードのボトルネックが残っていないか。
最新のコードのみを使用している
Drupalカスタムモジュールを開発するときに守るべき黄金律の1つです。
XDEBUGは、IDE（統合開発環境）で利用することで効果を発揮します。おススメのIDEはPHPSTORMです。有償ですが開発効率は桁違いです。IDEにお金をかけたくない方は、Visual CodeにDrupal用プラグインをアドオンして追加いましょう。
XDEBUGの設定等に関する記事はこちらです。
【WSL2】LANDOで構築したアプリをXDEBUGとPHPSTORMでデバッグする
黄金律2：カスタムモジュールは一箇所にまとめる
例えば、あなたがモジュール名を..."E_shop "とします。
この場合、新しい専用フォルダを"/module/custom/E_shop "と名付けます："/module/custom/E_shop" とします。
"/custom "フォルダをスキップして、代わりに"/sites/all/modules/E-shop "というフォルダ名をつけたくなるかもしれません。
しかし、このタイプのモジュール専用の場所を作った方が、カスタムモジュールを探す必要があるときに、すべてのモジュール（Drupal.orgからダウンロードしたものも含む）を探し回る必要がなくなります。
黄金律3：マシン名には適切な名前をつける
「適切な名前」とは、Drupal におけるモジュール名の黄金ルールに従ったものという意味です：
- 文字で始まること
- 一意であること
- 小文字 + アンダースコア」式に従うこと。
- すでに使われている用語（例えば "misc"、"src"、"Drupal"、"files "など）を含まない。
- スペースを含まない
これらのルールはすべてGithubに掲載されています。
以下の点に注意してマシン名を命名してください。
- モジュールのマシン名に大文字が含まれていないことを確認してください。
- あなたのプロジェクトで実装する他のコアモジュールやコントリビュートモジュールですでに使われている名前を使わないようにしてください。
マシン名等の命名はDrupalのコーディング規約できるだけ則って行うべきです。
こちらの記事では、Drupalのコーディング規約を紹介しています。
黄金律4：moduleファイルにhook_themeフックを追加する
Twig テンプレートをカスタムブロックと一緒に使っている場合の素晴らしいプラクティスです。
注意: テーマ関数の名前を "block_..." にするのは避けてください。別の方法として、モジュールの名前をプレフィックスとして使ってください。
TWIGテンプレートはもともとSymphonyのViewテンプレートとして存在していて、Drupal8がSymphonyをベースフレームワークとして採用したことで利用できるようになりました。
TWIGテンプレートはフォームからでもコントローラからでも利用することができますが、hook_themeに登録しておくことが必須条件です。
この記事では、DRUPAL標準で備わっているコンテンツタイプノード（基本ページや記事など）を表示する場合に特定のTWIGテンプレートを使用する方法を説明しています。
【Drupal】NODEを表示時にカスタムモジュールで用意したTWIGテンプレートを使用する
黄金律5：エラーをすべて表示するように設定する
Drupal のモジュール開発に入る前に、PHPのエラーレポートをオンにすることを忘れないでください。
こうすることで、モジュールのビルド中にコードに潜り込んだエラーについてアラートを受け取ることができます。
ヒント: もしすべてのエラーを公開することにそれほど興味がなく、Drupalサイトによって生成されたエラーについてのみアラートを受け取りたい場合は、そのまま実行してください：
tail -f /var/log/apache2/error.log を実行してください。
Drupal開発者がDrupalのデバッグをする場合は、PHPのエラーモードだけでなくDrupalのデバッグモードも有効にしておく必要があります。
この記事では、Drupalのデバッグモードを有効にして、デバッグを効率よく行うための方法を紹介しています。
黄金律6：moduleファイルは最低限のコードのみ書く
.module ファイルはHTTPリクエストごとにロードされます。 そのためファイルが肥大化するとパフォーマンスが落ちます。最低限のコードのみ書くようにしましょう。
黄金律7：カスタムモジュール作成時はは必ず info.yml ファイルを作る
これは「Drupal 8のステップバイステップでカスタムモジュールを作成する方法」のガイドにある推奨事項です。
基本的に、このファイルは新しいカスタムモジュールに関するメタデータを保存し、新しくアップロードしたモジュールについてDrupalにモジュールの内容を通知します。DrupalCoreはこのメタ情報を元に機能拡張にてインストールまたはアンインストールを実施します。
黄金律8：新規モジュール作成は本当に必要なときだけにする
私がインタビューした開発者の99％が同意したもうひとつの黄金律があります。
可能な限り、まったく新しいモジュールを一から書くのではなく、既存のモジュールを再利用することです。
それは、カスタムモジュールの "負荷 "が大きくなればなるほど、Drupal のウェブサイトをメンテナンスしたり更新したりするのが難しくなるからです。
※Drupal モジュール開発の良いプラクティスは、モジュールをGithubで公開することです。こうすることで、将来のプロジェクトのために、適切な設定をすでに含んだ再利用可能なコードを手元に置くことができます。
黄金律9：新しくモジュールを作る前にすでに存在しないか確認する
これは前の黄金律と強く結びついています。
そして、Drupal開発者が陥りやすい落とし穴の一つでもあります：
あなたのプロジェクトのために急いでカスタム機能を作成する前に、そのためのモジュールがまだ存在しないかどうかをチェックし、そして...ダブルチェックしてください。
黄金律10：カスタムモジュールは modules ディレクトリに置く
Drupal 7のように、カスタムモジュールを"/sites/all/modules "ディレクトリに置くという制限はもうありません。
Drupal 8では、すべてのコアモジュールは"/core "ディレクトリに入るので、"/modules "ディレクトリにcontribとカスタムモジュールを置くための "十分なスペース "があります。
黄金律11：サーバーサイドでバリデーションを行う
インタビューした開発者全員が同意した、もう一つのグッドプラクティスです：
クライアントサイドでバリデーションを行うときは、必ずサーバーサイドでもバリデーションを行うことを忘れないでください。
つまり、データが正しいかどうかを確認するためにJavaScriptだけを信頼するのではなく、サーバー側でも検証することを忘れないということだ。
黄金律12：論理的な集約階層を目指す
「集約階層」とは、情報やデータを整理する段階のことを指します。複雑な情報をシンプルにまとめるために、階層的な構造が存在して、その階層構造が論理的なつながりを持っていることを意味します。つまり、上から下までの関係性や順番が合理的であり、整理された情報をスムーズにたどることができます。
黄金律13：UPDATE_HOOKを使用する
もう一つの "黄金律 "は、私が彼らに "Drupal 8でのモジュール開発 "のルーチンについて尋ねたときに、ほとんどの開発者が言及したことです：
カスタムモジュールの機能の多くはブロックの中にあります。したがって、更新フックを使用することで、その場所と可視性をコントロールすることができます。
そのため、更新フックを使用することで、それらの位置と可視性をコントロールすることができます。
黄金律14：Coderのような自動コードチェックツールを使う
あなたが書いているコードを100％確実にしたい場合、自動化が鍵となります。
- クリーンである
- 保守可能である
- チームメイトやDrupalコミュニティの開発者が読むことができる
- Drupalのコーディング標準に準拠している
- 使用しているPHPバージョンのベストプラクティスに従っている
Coder のようなモジュールは、チェックリストでこれらのコードチェック作業を効率化するのに役立ちます。
※PHPSTORMにはCorderなど主要なツールが組み込まれているため、開発効率は極めて優れています。筆者もPHPSTORMを使用しています。おススメのツールです。
黄金律15：ベンダーファイルをコミットする
これは「良い」習慣というよりむしろ「しなければならない」習慣です。
Drupal のモジュール開発で、ベンダーのコンポーネントに依存するカスタム機能を実装する場合は、ベンダーのファイルをコミットすることを忘れないでください。
黄金律16：モジュールで環境設定を実施するようにする
更新のたびにコードを書き直す手間が省けるからです。
言い換えれば、テーマにクラスをハードコードする代わりに、コンフィギュレーションで値を設定し、コードと一緒に適用するだけです。
Drupal 8のカスタムモジュールを開発する際に設定をコードに含める主な利点は？
コーディングの高速化
再利用可能なコード（別名、より高品質なソフトウェア）
より良い品質のコード
「更新しやすい」機能
より複雑な機能
例えば、あなたの設定管理システムはコンテンツタイプの作成と管理プロセスを扱うとします。
その場合、正しく命名され構造化された設定ファイルをセットアップするだけで、新しいカスタムモジュールにコンテンツタイプを追加できます。
Drupal では、フィールド設定、ビュー、コンテンツタイプのようなデフォルトの設定は、他の設定と同様、YAMLファイルで設定することができます。
PHPコードを使用して各種設定をする必要があったDrupal 7とは異なり、DrushでエクスポートしたYAMLファイルをそのままデフォルト設定用に使用することが可能です。
黄金律17：キャッシュを必ず使用する
Drupal 8は何をキャッシュし、何をスキップすべきかを知っています。
キャッシュは必ず利用しましょう。
黄金律18：Drupal APIサービスを利用する
Drupalは、多くの管理機能が存在します。新しいモジュールを作成したら最大限に活用できるようにしましょう。
それらを使って、モジュールの設定やデータを保存したり、表示したりしましょう。
そして、ここではどのように正確に設定を保存するかを説明します：
フックメニュー "を使って設定ページを定義します。
drupal_get_form "ページコールバックを使用して、保存する必要があるモジュール設定を定義し、返します。
レンダリングAPIを使用すると動的なHTMLタグを安全にかつ簡単に作成することが可能です。
Drupal APIサービスを使用するには、DI（Dependency injection）によるインスタンス化が推奨されています。
DIによるインスタンス化の方法はこちらの記事をご覧ください。
この記事に関するご質問やご意見などございましたらお問い合わせフォームからお気軽にご連絡ください。
