Drupal 8 入門 : カスタムモジュール作成編

（追記20151014: 本記事は執筆時点の Drupal 8 のバージョン（開発版）にもとづく古い解説となっています）

今回は以前こちらでご紹介した「インストール編」「管理画面編」に引き続き「 Drupal 8 入門」のお話ができればと思います。

前回・前々回は Drupal 8 の CMS としての基本的な使い方を見ましたので、今回は一歩進めて開発面の特徴を見ていきましょう。 かんたんなカスタムモジュールをひとつ作りながら、 Drupal 8 のモジュールの構造などをご説明していきます。

今回は Drupal 本体のセットアップが済んでおり、管理者としてログインできる状態が整っている前提で話を進めていきます。 Drupal 8 のセットアップがまだの場合はインストール編を、管理画面の見方が見たい場合は管理画面編の方をご参考にしてください。 それ以前に「 Drupal のモジュールって何だったっけ？」という場合には、 Drupal 7 のカスタムモジュール作成入門あたりの記事がご参考になるかもしれません。

また、この記事を書いている現時点で Drupal 8 の最新バージョンは安定版リリース前のアルファバージョンです。 正式リリースのときには細かな部分に若干の変更が加わっている可能性がある点をあらかじめご認識いただければと思います。

今回作る Hello World モジュールについて

今回作るのはページに「 Hello World 」と表示するシンプルなモジュールです。 名前はそのままで「 Hello World 」とします。 できあがりのページイメージはこんな感じ。

以下開発を進めていく中で実際に見ていきますが、 Drupal 7 から 8 へのバージョンアップにおいてはモジュールのファイル構造からコアの API からさまざまなポイントが積極的に（容赦なく？）更新されています。 そのあたりの変更点は実際のモジュールの作り方を Drupal 8 と Drupal 7 とで比較していただくとわかりやすいかと思います。 上掲の Drupal 7 のカスタムモジュール作成入門では Drupal 7 において同様の機能を持った Hello World モジュールを作成しているので、今回の Drupal 8 の場合と対照比較することができます。 よろしければ比較してみてください。

さて、今回作るモジュールの最終的なディレクトリ構造は次のとおりとなります。

helloworld/
  lib/
    Drupal/
      Controller/
        HelloController.php
  umi.info.yml
  umi.module
  umi.routing.yml

この具体的な中身を以下で作っていきます。

モジュール開発の流れ

具体的な作業に入る前に Drupal 8 のモジュール開発の流れを見ておきましょう。 Drupal 8 のモジュール開発の一般的な流れは次のとおりです。

1. モジュールディレクトリを作成
2. モジュールのメタ情報ファイル（ .info.yml ）を作成
3. モジュール本体ファイル（ .module ）を作成
4. モジュールのサブファイル（ lib/Drupal/*/* ）を作成
5. モジュールの情報ファイル（ .*.yml ）を作成
6. モジュールをインストール

（実装よりも前と後のステップについては割愛しています）

上記の流れに沿って以下実際にモジュールを作成しましょう。 いちど最後まで目を通した後、手を動かしながら再度読み進めていただくとより実感がわきやすいかと思います。

1. モジュールディレクトリを作成

まず最初にモジュールのファイル一式を格納するディレクトリを作成します。

Drupal プロジェクトディレクトリ以下の modules というところに「 helloworld 」というディレクトリを新規作成します。 Drupal 8 では、コントリビュート・カスタムモジュールの配置場所はプロジェクトルート直下の modules となりました。 Drupal 7 では sites/all/modules などの下だったのですっきりシンプルになりましたね。

$ cd (Drupal 8 プロジェクトのルートディレクトリ)
$ cd modules
$ mkdir helloworld
$ cd helloworld

このディレクトリ名がそのまま Drupal 内でのモジュール名となります。 モジュール名は小文字英数字にするのが決まりとなっています。 また、この名前はプロジェクト内のところどころで使うことになるため、何度も繰り返し使うことを前提とした名前にするとよいでしょう（長すぎず、短すぎず・・・）。

この後の作業はほとんどこのディレクトリ内で行っていく形になります。

2. モジュールのメタ情報ファイル（ .info.yml ）を作成

次に、作成したディレクトリ内にモジュールのメタ情報を記述する helloworld.info.yml ファイルを作成します。

$ touch helloworld.info.yml

このファイルは「 モジュール名.info.yml 」という名前にするのが決まりです。 今回はモジュール名が helloworld なのでメタ情報ファイルは helloworld.info.yml という名前にします。

ファイルが用意できたら、その中に次の内容を書き入れましょう。

name: Your first Hello World module.
type: module
description: 'This is your first module.'
core: 8.x

Drupal 7 ではこのメタ情報の役割を担うファイルは「 モジュール名.info 」という名前にするのが決まりでした。 内容的には大差ないものの、 Drupal 8 では書式が YAML （ヤムル） になっているところがポイントです。

拡張子の yml は書式が YAML であることを表すためのものです。 YAML はインデントで階層構造を表すシンプルな書式で、近年は設定ファイルなどで XML や JSON に代わる形でよく使われているということで、 Drupal でも採用されることになったようです。 ちなみに「 YAML = YAML Ain't Markup Language 」の略で、 YAML の略称に YAML そのものが入っているという言葉遊びで名付けられています。

この *.info.yml ファイルを作成すれば、ひとまず Drupal がこのモジュールを認識してくれるようになります。

3. モジュール本体ファイル（ .module ）を作成

つづいて、モジュールの本体となる helloworld.module ファイルを作成します。

$ touch helloworld.module

こちらについては Drupal 7 と変更ありません。 モジュールの中心的なコードを記述する場所がこのファイルとなります。 今回「 Hello World 」を表示するページを作成する上ではこのファイルは使用しないので中身は空のままで置いておきましょう。

4. コントローラファイル（ *Controller.php ）を作成

ここからが実際のページ作成となります。 Drupal 7 でいうところの「ページコールバック関数」を作成します。 Drupal 8 ではページコールバック関数は「コントローラクラスのメソッド」として実装するスタイルになりました。 近年の MVC ウェブフレームワークの主流のスタイルが Drupal でも採用された形になります。

まずはモジュールディレクトリ以下に lib/Drupal/Controller というディレクトリを作成し、その中に HelloController.php というファイルを作成しましょう。

$ mkdir -p lib/Drupal/helloworld/Controller
$ touch lib/Drupal/helloworld/Controller/HelloController.php

ファイルが生成できたらエディタで開き次の内容を入力します。

<?php // 名前空間の定義
namespace Drupal\helloworld\Controller;

/**
 * Hello World を表示するコントローラとメソッド
 */
class HelloController {
  public function hello() {
    return 'Hello World';
  }
}

上述のとおり、 Drupal 8 ではコールバック関数は「コントローラクラスのメソッド」として記述する形になります。

メソッドの中身は Drupal 7 のコールバック関数と同じ感覚で作成することができます。 今回は Hello World と表示したいだけなので直接文字列を return していますが、実際には Drupal 7 と同じスタイルでレンダーアレイのスタイルで構造的に HTML を組み上げる形が基本となるでしょう。

レンダーアレイで記述するパターンに興味のある方は、上記のコードの return 'Hello World'; の 1 行を次の内容に置き換えてみてください。

$builder = array(
  '#type' => 'markup',
  '#markup' => 'Hello World',
);

return $builder;

後ほど確認する段で、どちらの場合でも問題なく「 Hello World 」と画面に表示されることがご確認いただけるはずです。

5. モジュールのルーティング情報ファイル（ .routing.yml ）を作成

コントローラクラス本体とメソッドが用意できたので、次は特定のパスへのアクセスがあったときにこれを Drupal に使ってもらうためルーティング情報ファイル helloworld.routing.yml を作成し「ルーティング情報」を記述します。 Drupal 7 ではルーティング（特定の URL にアクセスがあったときにどの関数で対応するのか担当を割り当てる作業）の設定は hook_menu() と呼ばれる関数を実装する形で行いましたが、 Drupal 8 では主に *.routing.yml というファイルがその役割を担当します。

まずは helloworld.routing.yml ファイルを作成します。 こちらのファイルは helloworld.info.yml と同じくモジュールディレクトリのルート直下に置くようにしましょう。

$ touch helloworld.routing.yml

ファイルが生成できたらエディタで開いて次のコードを記入します。

helloworld.hello:
  path: 'hello'
  defaults:
    _content: 'Drupal\helloworld\Controller\HelloController::hello'
  requirements:
    _access: 'TRUE'

この設定によって、その Drupal サイトの /hello というパスにアクセスがあれば、上で作成した HelloController.php 内の HelloController::hello メソッドが対応してくれるようになります。

上述の *.info.yml と同じく *.routing.yml の場合も書式には YAML を使用します。 書き方のスタイルは Drupal 7 から変更されてはいますが、 Drupal 7 で開発を行ったことのある方であれば各行が何を意味するのかは初見で想像のつく形になっているのではないでしょうか。 Drupal 7 での開発に馴染みのある方向けにかんたんに解説すると、このコードの各行はそれぞれ次のような意味を持っています。

• 1 行目 helloworld.hello: そのルーティング設定の名前
• 2 行目 path: 対象とする URL パスの指定
• 4 行目 _content: ページコールバック関数の指定 PSR-0 に従ったスタイルにする決まり
• 6 行目 _access: アクセスコールバック関数の指定

ここまで終わればひとまず「 Hello World 」モジュールの開発は完了です。

6. モジュールをインストール

実際にモジュールを Drupal にインストールしてページを確認してみましょう。

Drupal サイトにアクセスし、管理画面にログインします。

メニューの中から「 Extend 」をクリック。

Drupal の管理下にあるモジュールの一覧が表示されるので、その中から今回作成したモジュールを探します。 Your first Hello World module というモジュール名にしたので「 Hello 」などでページ内検索すると見つかりやすいかと思います。

モジュールの横にあるチェックボックスにチェックを入れて、画面のいちばん下の「設定を保存」をクリックします。

以上でモジュールの有効化処理は完了です。

最後に、ブラウザからパス /hello にアクセスして今回作成したページが無事表示されることが確認できれば、モジュール作成は完了となります。 ここまで手を動かして実際にやってみた方は、無事に「 Hello World 」することができたでしょうか？

・・・いかがだったでしょうか？

今回はひとつひとつ詳しめに説明してみたため分量が長くなった感じがありますが、全体的な流れは Drupal 7 と同じですので、慣れてこれば数分とかからずサクサクとモジュールのベースを作成できるようになるかと思います。 コードの配置などの自由度が非常に高かった Drupal 7 に比べると Drupal 8 でのモジュール開発は PSR-0 関連の縛りなどで制約を感じるところもありますが、制約のおかげでより一貫性が高くメンテナビリティの高いモジュール開発ができるようになりそうです。エンジニアにとってはこのあたりのメリットも大きい感じがします。

先日開催された DrupalCon Austin 2014 ではもう大半のセッションが Drupal 8 関連のものでした。 Drupal 8 関連の情報も日増しに増えてきている感じがしますので、今後も引き続き Drupal 8 入門シリーズを続けていければと思います。

?>