今回は Drupal （ドルーパル）の開発をはじめて間もない方がよく陥りがちな「カスタムモジュールとフック関数を作成したのに Drupal に認識してもらえない」という問題を解決するためのヒントをご紹介できればと思います。 Drupal 開発をはじめて間もない方が特によく陥りがちですが、経験者の方でもときどきハマるポイントかと思います。 私もつい先日ハマりました。
はじめに
弊社で愛用している CMS 「 Drupal 」には開発者が自由に機能を拡張できる「モジュール」という仕組みが備わっています。
Drupal の「モジュール」は WordPress でいうところの「プラグイン」に相当するもので、「フック」と呼ばれる仕組みを使って CMS コアのコードに一切手を加えることなくコアの処理の合間にオリジナルの処理を差し込める機能を提供しています。
モジュールが Drupal に認識されない原因
開発の初期によく（開発をしばらく経験していてもときどき）陥りがちなのが「モジュールを正しく作成したはずなのに Drupal が認識してくれない」という問題です。 Drupal 経験の多い方であれば比較的短時間で解決することができますが、初期の頃にはハマるときは大ハマりすることもあるところなので、モジュール開発に挑戦する方は解決の糸口をある程度知っておいた方がよい問題かと思います。
結論から先に言いますと、作成したモジュールが Drupal に認識されない問題の原因としては次のようなものがあります。
- モジュールの配置場所の問題
- モジュール名の問題
- モジュール .info ファイルの問題
- モジュール .module ファイルの問題
- フック関数名の問題
- キャッシュの問題
以下順番にご説明していきます。
モジュールの配置場所の問題
こちらはモジュールの配置場所がおかしいために Drupal が正しく認識してくれないパターンです。
Drupal 7 のモジュールはサイトルート以下の sites/all/modules 以下に入れるのが基本です。
sites/all/modules の下にあれば、さらにサブディレクトリに入っていても問題ありません。
ベストプラクティスは次のとおりでしょうか。
- コントリビュートモジュール:
sites/all/modules/contrib以下に入れる - カスタムモジュール:
sites/all/modules/custom以下に入れる
Drupal でマルチサイト機能を使う場合なんかにはプラスアルファの工夫が必要になってきたりもします。 そのケースについては次の記事などが参考になるかと思います（英語です）。
ときどきあるのは、ブラウザやターミナルでチェックしている Drupal サイトとファイラでチェックしている Drupal サイトが実は違ったという失敗パターンです。 本当は A というサイトにモジュールを入れたいのに B というサイトにモジュールを入れていた、という場合はもちろんうまく行きません。 これはサイトが A B で異なる場合もそうですし、ローカル環境とステージング環境、本番環境などひとつのサイトに複数の環境がある場合なんかでもありがちです。 初歩的ですが、ハマるときには大ハマリするので要注意です。
モジュール名の問題
こちらはモジュールのマシン名が正しくないパターンです。
原則 Drupal のモジュール名はフック関数のプリフィックスとなるため PHP の変数名（関数名）として有効な名前である必要があります。
アンダースコア（ _ ）も含めることができますが、フック関数のプリフィックスになった場合に紛らわしいためアンダースコアはなるべく使わないのがベストプラクティスです。
1. これがベスト OK
mymodulemymodule123
2. これも OK （だけど非推奨）
my_modulemy_module_123
3. これは NG （ PHP の変数名として無効）
my-module123_module
モジュール .info ファイルの問題
こちらは .info ファイルの問題です。
Drupal ではモジュールのメタ情報を モジュール名.info というファイルに記述するスタイルをとっていますが、こちらもモジュール名と正確に一致する必要があります。
また、 .info ファイルの中には記入が必須となっているフィールドがあるため、これらを必ず記入しなくてはなりません。
具体的な必須フィールドは次の 2 つです。
- name: そのモジュールの管理者用の名前
- core: 対象となる Drupal のバージョン（ただし、なくても admin/modules のリストにはあがってくる）
モジュール .module ファイルの問題
こちらは .module ファイルの名前が間違っているパターンです。
こちらも最低限「ファイルが存在する」ことが必要になってくるため .info ファイルと同様に モジュール名.module という名前にしましょう。
モジュール名を開発の途中で変更したときなんかには、 .info ファイルと .module ファイルの両方を正しく変更したかを確認する必要があります。
フック関数名の問題
こちらはフック関数名が間違っているというパターンです。 「モジュール自体は認識されて有効化できた。だけど、フック関数を書いても処理が実行されない。」という場合はまずフック関数名の間違いを疑うのがよいでしょう。
Drupal.org や Stack Overflow でよく見るのは、サンプルをそのまま取ってきて「フック関数が認識されないんだけど・・・」と質問しているパターンです。
Drupal のフック関数は「特定の関数をフック関数として登録する」という関数を書く一手間が必要ないかわりに、厳密な命名規則を持っています。
たとえば、 hook_page_alter というフック関数を実装したい場合は モジュール名_page_alter という名前の関数を書かなくてはなりません。
仮にモジュール名が studioumi だとするとフック関数名は studioumi_page_alter になります。
ですので、フック関数のサンプルコードを自分で書いたモジュールに取り込む場合には必ずプリフィックスの部分を変更する必要があります。
キャッシュの問題
最後は Drupal コアが提供するキャッシュ機能に起因する問題です。 フックによっては、「フックを書いてファイルを保存する」だけでは足りなくて、 Drupal のキャッシュをクリアしないことには Drupal に認識してもらえないものがあります。
キャッシュのクリアは Drupal の管理画面の「パフォーマンス」（ /admin/config/development/performance ）のところにある「キャッシュクリア」というボタンをクリックする方法と Drush のサブコマンド cc を使う方法があります。
Drush に馴染みのない方は管理画面の「パフォーマンス」のページからやってみてください。
Drush に興味のある方は以下の記事などをご参考に導入してみてください。
トラブルシューティング方法
Drupal がモジュールを認識してくれないパターンは、おおよそ上記のパターンのいずれかにあてはまります。 ですので、怪しいところから順番に見てみてください。 まずはモジュールが認識されるかどうかをチェックして、認識されない場合は次の 4 つをチェックする。
- モジュールの配置場所の問題
- モジュール名の問題
- モジュール .info ファイルの問題
- モジュール .module ファイルの問題
上記のポイントはいずれもクリアでき、モジュールを無事有効化できたその後に問題がある場合は、以下の 2 つのポイントをチェックされるとよろしいかと思います。
- フック関数名の問題
- キャッシュの問題
フック関数名も問題ない、キャッシュも問題ない、だけど適切なタイミングで処理が行われないという場合は、そもそも利用するフックが間違っていないかどうかをチェックされるとよいかと思います。
hook_boot() と hook_init() など、名前が似通っており、ちがいときちんと理解していないとハマる関数などもあるので、そのあたりはあとはドキュメントを読んで Drupal の処理の流れとフックシステムへの理解を深めるしかない、という感じです、かね。
以上です。 いかがだったでしょうか？
おわりに
本日は Drupal 7 で「モジュールを作ったのに Drupal に認識されないときのトラブルシューティング方法」をご紹介しました。
開発をしばらく経験してもハマることがときどきありますが、開発の初期には特によく遭遇するつまづきポイントだと思います。 Drupal 開発をはじめて間もない方などはぜひご参考にしてみていただければと思います。
募集しています
スタジオ・ウミは「Drupal」に特化したサービスを提供する Drupal のエキスパートチーム。
フルリモート＆フレックス制だから、働く場所を選ばず時間の使い方も自由です。
そんなワークライフバランスの整った環境で、当ブログに書かれているような
様々な技術を共に学びながら、Drupalサイト開発に携わってみたい方を募集しています。
まずはお話だけでも大歓迎！ぜひお気軽にご連絡ください。