アイキャッチ画像: デスクの上でパソコンを使用している

Drupal （ドルーパル）ドキュメントの日本語訳シリーズの一環で、今回は「 Writing module .info files (Drupal 7.x) 」という記事を翻訳してご紹介できればと思います。

こちらは Drupal のモジュールになくてはならない「 .info ファイル」の書き方を詳しく説明した記事です。 このページをひととおり読むと、モジュールの .info ファイルの書き方がわかるようになります。 .info ファイルの作成は Drupal での開発には欠かせないプロセスなので、 .info ファイルについてまだあまり知らないぞという方はぜひご参考にしてみてください。

オリジナルの記事はこちらです。

では、以下が日本語訳となります。 日本語としてのわかりやすさを心がけ、一部意訳、一部直訳となっています。 正確な原文のニュアンスが知りたい場合には原文の方にあたってみてください。 ちなみに、本翻訳は2013年11月15日が最終更新日のバージョンを元にしています。

概要

Drupal ではテーマやモジュールのメタデータを格納するために .info ファイルを利用します。

モジュールの場合 .info ファイルはこんな用途に利用されています:

  • Drupal Web GUI 管理ページの情報のレンダリング
  • モジュールの有効化 / 無効化のコントロール基準の提供
  • モジュールの存在の Drupal への通知
  • 他のコンテクストでの全般的な管理に関すること

この .info ファイルというのはシステムがモジュールの存在を認識するために不可欠なものとなっています。

例

次のコードは .info ファイルのサンプルです:

name = Really Neat Widget
description = Provides a really neat widget for your site's sidebar.
core = 7.x
package = Views
dependencies[] = views
dependencies[] = panels
files[] = tests/example.test
configure = admin/config/content/example

.info ファイルは .module ファイルと同じ名前で同じディレクトリに存在する必要があります。 例えば、モジュールの名前が example.module の場合 .info ファイルは example.info という名前でなくてはなりません。

このファイルは標準の .ini ファイルと同じフォーマットで、キー/バリューのペアを等号で分けて（ キー = バリュー として）プロパティを定義します。 値をラップするために引用符を使うことも可能です。 引用符に囲まれた値には改行を含めることもできます。

.info ファイルにはコメントを含めることができます。 行の先頭にセミコロン（ ; ）があるとその行はコメントとなり、パースされません。

メモ: .info ファイルを作成あるいは変更したときは、変更を反映するには必ずサイトのキャッシュをクリアする必要があります。

プロパティ

.info ファイルには以下のプロパティを含めることができます:

目次

  • name （名前） 必須
  • description （説明） おすすめ
  • core （コア） 必須
  • stylesheets （スタイルシート）
  • scripts （スクリプト）
  • files （ファイル）
  • dependencies （依存）
  • package （パッケージ）
  • php （ PHP ）
  • version （バージョン） 非推奨
  • configure （設定）
  • required （必須）
  • hidden （非表示）
  • project 非推奨 パッケージ利用時のみ
  • project status url drupal.org に送信されていないカスタムモジュールのみで使用

name （必須）

これはモジュールの名前を表示するためのものです。 モジュールページに表示されます。 モジュール名は正式なものなので、正式な名前として大文字始まりで（たとえば、「 really neat widget 」や「 Really neat widget 」ではなく「 Really Neat Widget 」）、人間が読むための名前（ really_neat_widget ではなく）にしましょう。 もしモジュール名が短縮形（ CSS WYSIWYG UI など）やサードパーティの商品名（ jQuery JavaScript ）を含む場合はもちろんそれらの標準的な表記に従いましょう。

name = Really Neat Widget

description （必須）

そのモジュールが何をするものなのかをモジュール管理ページで管理者に伝えるための説明です。 できれば一行の短い名前にします。 説明が長すぎるとページでうまく表示されないので、簡潔になるように心がけてください。 このフィールドは 255 文字までに制限されています。

description = Provides a really neat widget for your site's sidebar.

説明にはドキュメントやリソースへのリンクを含めることができます。 次の例は作者へのリンクを示しています。 リンクは Drupal.org のドキュメントノードへのリンクにしても大丈夫です。 オンラインのドキュメントが readme ファイルよりもよい場合、有効化する前にモジュールについて理解したい場合にはこのリンクは有用です。 description = Domain manager by <a href="http://petermoulding.com">Peter Moulding .com</a> 。

core （必須）

これはモジュールが対象とする Drupal のバージョンです。 Drupal 7 なら 7.x などという感じにします。 Drupal のマイナーバージョンを指定することができません。 6.x は正しいですが 6.2 は正しくありません。

core = 7.x

stylesheets （オプション）

Drupal 7 では、全ページで追加したい CSS ファイルはモジュールの .info ファイルで追加することができます。 テーマの .info ファイルと同様です。 こちらは node モジュールの .info ファイルから取ってきた例です。

stylesheets[all][] = node.css

scripts （オプション）

全ページで追加したい JavaScript はモジュールの .info ファイルで追加することができるようになりました。 これを使うと JavaScript が最適な方法でアグリゲートされます。 これは大部分のサイト訪問者が行う典型的なサイト訪問パターンに対して JavaScript を追加する場合におすすめの方法です。

scripts[] = somescript.js

さらに詳しい情報は Managing JavaScript in Drupal 7 をご覧ください。

files （オプション）

Drupal はコードレジストリのダイナックローディングをサポートするようになりました。 ダイナミックローディングを利用するには、クラスやインタフェース宣言を含むすべてのコードファイルを .info ファイルで宣言する必要があります。 このような感じです。

name = Really Neat Widget
...
files[] = tests/example.test

Drupal は、モジュールが有効化される際に宣言された files をすべてスキャンし直し、見つかったクラスとインタフェースをすべてインデックスします。 クラスは初めてアクセスされたときに PHP が自動的に読み込みます。

dependencies （オプション）

モジュールが必要とする他のモジュールの配列です。 その中にあるモジュールが存在しなければ当該モジュールを有効化することはできません。 モジュールは存在するけれど有効化されていない場合は、追加で有効化すべきモジュールのリストが管理者に提示されます。 管理者はそこで、必要なモジュールもあわせて有効化するかキャンセルするかを選択することができます

各依存の文字列の値はモジュールの（「 module 」抜きの）ファイル名でなくてはなりません。 また、次の例のように小文字で書くひつヨガあります。 スペースを使うことはできません。

dependencies[] = taxonomy
dependencies[] = comment

さらに、 test_dependencies[] を使って、任意だけど推奨される依存関係を示すことができます。 この記述を使うと Drupal.org の自動テストシステムがサポートしてくれます。 これを使うとテストボットに提案されたプロジェクトをチェックしてもらえることになります。 一般的に、モジュールのテストの getInfo() 関数内の 「 dependencies 」配列でリストアップされたモジュールは test_dependencies[] に追加されます。

test_dependencies[] = autoload

特定のモジュールのバージョン番号を指定する必要がある場合、 Drupal 7 にはそのための方法が用意されています。 バージョン番号はオプションで、モジュールが他のモジュールの特定のバージョンやブランチをどうしても必要とする場合のみ必要となります。

dependencies[] フィールドのシンタックスは次のとおりです:

dependencies[] = modulename (major.minor)

ここで、 major は数字で表されるメジャーバージョン番号で、 minor は数字あるいはアルファベットで表されるマイナーバージョン番号です。 どのマイナーバージョンでもよい場合は x を使うことができます。 例をいくつか以下に示します。

name = Really Neat Widget
description = An example module
dependencies[] = exampleapi (1.x)
test_dependencies[] = autoload (>7.x-1.5)
...

上の .info コードでは、「 Example 」モジュールは「 Example API 」モジュールのメジャーバージョン 1 、マイナーバージョン不問のものを必須としています。

dependencies[] = exampleapi (1.0)

これは、モジュールは Example API モジュールの 1.0 （ 1.0 のみ）が必要であることを意味します。

dependencies[] = exampleapi (1.x)

上のモジュールは Example API モジュールの 1.x ブランチのものを必須としています（ 1.0 、 1.1 、 1.2-beta4 など）。

.info ファイルの dependencies[] プロパティはオプションでバージョンを指定することもできます:

  • = or == イコール（オプション: デフォルトはイコール）
  • > 大なり
  • < 小なり
  • >= 大なりイコール
  • <= 小なりイコール

  • != 等しくない

    dependencies[] = exampleapi (>1.0)

上のモジュールはバージョン 1.0 より大きなバージョンのいずれかを必須とします。

オプションでコアのバージョン番号を指定することもできます。

dependencies[] = exampleapi (>7.x-1.5)

上のモジュールは 7.x バージョン互換のモジュールで、バージョンが 1.5 よりも大きいものを必須とします。

さらに、かっこの中でコンマ区切りの値を使ってバージョン依存情報を複数示すこともできます:

dependencies[] = exampleapi (>1.0, <=3.2, !=3.0)

モジュール名に system を使うことで、最低限のコアのバージョンを示すために使うこともできます。

dependencies[] = system (>=7.53)

こうすると、モジュールは最低でも Drupal のバージョン 7.53 を必須とすることになります。

package （オプション）

あなたのモジュールが他のモジュールとセットになっている場合や相補的に使うものである場合、パッケージ名をここに入れましょう。 空の場合、モジュールは「 Other 」としてリストされます。 一般的にこのプロパティは大規模なマルチモジュールパッケージやマルチモジュールパッケージを拡張するモジュールだけに使うべきです。 例としては Fields 、 Views 、 Commerce 、 Organic Groups などがあります。 その他すべてのモジュールではここは空のままにしておきましょう。 ガイドラインとして、 4 つ以上の互いに依存する（あるいはどれかに依存する）モジュールがパッケージのよい候補となるでしょう。 それ未満のものはパッケージ候補ではありません。 このルールの例外は「 Development 」パッケージです。 Development パッケージはコード開発ツールモジュールとなるすべてのモジュールで使うことができます。

パッケージがある場合、そのパッケージのモジュールはモジュール管理ページ（ admin/modules ）でいっしょにまとめられます。 パッケージ名はモジュールを含めたい部分の見出しとなるので、そのパッケージ名を使うすべての .info ファイルの中で（スペルや大文字小文字の使い方において）一貫したものにする必要があります。 句読点は使わず、上述の Drupal の大文字小文字の使い方のスタンダードに従うべきです。

パッケージ名の文字列は大文字小文字を区別するため、大文字小文字の使い方は重要です。 あるパッケージでは package = fields として別のパッケージでは package = Fields とするとふたつの異なるパッケージがモジュール管理ページで現れることになります。 これは、 Seven （デフォルトの管理テーマ）がフィールドセットのラベルで fields と Fields を区別なしに使っているのと同様に非常に紛らわしいことになります。 package = Fields が正しい方法です。

package = Views

package フィールドの適切な項目のおすすめ例は次のとおりです:

  • Administration
  • Commerce
  • Development
  • Fields
  • Media
  • User interface
  • Views
  • Voting (if it uses/requires VotingAPI)

Package names for contributed modules wiki のページでは、現在あるパッケージ名をトラックしようという試みがなされています。 ただしこれがおすすめというわけではありません。

php （オプション）

バージョン 6.x では、モジュールやテーマは必要とする最小の PHP のバージョンを指定することができます。 次の例に似た行を .info ファイルに追加するとこれを行うことができます:

php = 5.3

これは、モジュール / テーマが 5.3 よりも前のバージョンの PHP では動作しないということを意味します。 モジュールが新しいバージョンの PHP で追加された機能（改善された XML ハンドリング、オブジェクトのイテレータ、 JSON など）を利用している場合に有用です。 バージョンが指定されない場合は Drupal コアが必要とする PHP バージョンと同じという意味にみなされます。 一般に、コアで必要なバージョンの PHP よりも新しい上位のバージョンを特に利用するということでなければ、必須バージョンを示すべきではありません。 PHP バージョンを示す文字列についてのより詳しい情報については PHP マニュアルをご覧ください。

version （非推奨）

バージョンを表す文字列は、リリースが作成され tarball パッケージが作られるときに drupal.org によって追加されます。 しかし、drupal.org のインフラでホスティングしない場合は、意味のあるバージョン名であればどんなバージョンでもつけることができます（たとえば Release naming conventions をご覧ください）。

git にアップされた .info ファイルではバージョンが定義されていないので、 git から直接モジュールを取得した場合は .info ファイルにバージョンを表す文字列は付いていません。 そういう場合は git deploy モジュールを使えばモジュールの正確なバージョン文字列を admin/build/modules ページでつけることができます。

Drupal コアはコントリビュートモジュールとはわずかに異なるパッケージングプロセスをとっているので、コアモジュールではバージョンの行はあらかじめ定義されています。 これは例外であり、コントリビュートモジュールの参考にはなりません。

configure （オプション）

バージョン 7.x では、モジュールの（主な）設定ページのパスを表します。 モジュールが有効化されると、「 Configure 」と「 Permissions 」のリンクが現れます。 ここの値はその該当モジュールの「 Configure 」リンクのパスとなります。

configure = admin/config/content/example

required （オプション）

バージョン 7.x では、 required = TRUE を追加することで、そのモジュールやテーマは絶対に欠かせないものであり無効化すべきでないということを表すことができます。 これらのモジュールはインストール中に自動的に有効化されます。 ほとんどの場合、これは Drupal コアが必要とするモジュール（たとえば Node や User など）でのみ利用するべきです。

hidden （オプション）

バージョン 7.x では、 hidden = TRUE を追加することで、そのモジュールやテーマをモジュールページに表示すべきでないことを表すことができます。 これは一般に、エンドユーザが有効化すべきでない SimpleTest を含んだテスト用モジュールで使用されます。

project （非推奨 パッケージング用途限定）

モジュールメンテナはこれを使うべきではありません。 drupal.org のパッケージングのためのスクリプトはモジュールがどのプロジェクトに所属するものなのかを明示するための文字列をここに入れます。 これは主に Update status モジュールのためのものです。 これがあると、 Drupal インストール機能によって、インストールされたパッケージのバージョンの監視と新しいバージョンが利用可能なときの管理者への通知ができるようになります。

project status url （drupal.org にアップされていないカスタムモジュール限定）

このフィールドを使うと、モジュールのメンテナが Update status モジュールを使ってモジュールの更新をチェックするための URL を定義することができます。 drupal.org 上にリリースされたモジュールではこのパラメータを定義すべきではありません。 URL は http://my.domain.com/projects/{project}/{core} というフォーマットでリクエストを受け付ける XML フィードを指すべきです。 この例では、 project status url は http://my.domain.com/projects に設定されるべきです。

info ファイルのフォーマットに関するさらに詳しい情報は、 drupal_parse_info_file() documentation をご覧ください。

Troubleshooting

core = 7.x という行を追加したのに、「このバージョンは Drupal コアの 7.x バージョンに対応していません」というメッセージが出ます。どうすればよいでしょうか？

dependencies フォーマットは Drupal 5.x と 6.x の間で変更されたことに注意してください。

間違い:

name = Really Neat Widget
...
dependencies = foo bar   ; 5.x の依存情報のフォーマット。
core = 6.x

正解:

name = Really Neat Widget
...
; [] がある点と各依存情報は別の行にわかれている点に注意してください:
dependencies[] = foo
dependencies[] = bar
core = 7.x

説明フィールドと非 ASCII 文字

.info ファイルの description フィールドの中でアクセントのついたアルファベット文字や非 ASCII 文字を使いたい場合は HTML エスケープ記法を使いましょう。 たとえば、「 ö 」を 表すには &ouml 、「 © 」を表すには「 &copy; 」を使います。

・・・翻訳は以上です。

今回は Drupal モジュールの .info ファイルの書き方に関する記事を翻訳してご紹介しました。

.info ファイルは Drupal のモジュール開発になくてはならないものなので、ぜひこのあたりは正しく押さえてよりよいモジュール開発をしてきたいところです。

今後も引き続き日本語としてあれば有用と思われる記事を見つけてご紹介していきたいと思います。

関連リンク
Writing module .info files (Drupal 7.x) | Drupal.org
Drupalでテーマ作成に必須な.infoファイルについて
共に働く新しい仲間を
募集しています

スタジオ・ウミは「Drupal」に特化したサービスを提供する Drupal のエキスパートチーム。
フルリモート＆フレックス制だから、働く場所を選ばず時間の使い方も自由です。
そんなワークライフバランスの整った環境で、当ブログに書かれているような
様々な技術を共に学びながら、Drupalサイト開発に携わってみたい方を募集しています。
まずはお話だけでも大歓迎！ぜひお気軽にご連絡ください。

採用情報を見る