Drupal 8でTwigの拡張機能を作成する方法

今回はTwigの拡張機能を作成する方法をご紹介します。

Twig Tweakという便利なモジュールもありますが、
それでも物足りない場合には、カスタムモジュールを作成することで
Twigテンプレート内で使用する関数やフィルターを簡単に追加することができます。

作成するモジュール

今回は画面上に「Hello xxx」と出力するTwig関数say_helloを作成します。
作成するカスタムモジュールは以下のような構成になります。

sample_twig_extension
    ├── sample_twig_extension.info.yml
    ├── sample_twig_extension.services.yml
    └── src
        └── TwigExtension.php

各ファイルの紹介

sample_twig_extension.info.yml

info.ymlファイルについては、特別なことはなく通常のカスタムモジュール作成と同様に書いていただければ問題ありません。
詳細はこちらをご参照ください。

TwigExtension.php

Twigの拡張機能を定義するためのクラスです。 先に全体像をお見せします。

<?php

namespace Drupal\sample_twig_extension;

use Twig\Extension\AbstractExtension;
use Twig\TwigFunction;

/**
 * Twig拡張サンプル.
 */
class TwigExtension extends AbstractExtension {

  /**
   * {@inheritdoc}
   */
  public function getName() {
    return 'sample_twig_extension';
  }

  /**
   * {@inheritdoc}
   */
  public function getFunctions() {
    return [
      new TwigFunction('say_hello', [$this, 'sayHello']),
    ];
  }

  /**
   * Hello.
   *
   * @param string $name
   *    名前.
   *
   * @return string
   *    Hello 名前
   */
  public function sayHello($name) {
    return "Hello ${name}";
  }

}

それでは詳細を見ていきましょう。

このクラスはTwig\Extension\AbstractExtensionクラスを継承する必要があります。

/**
 * Twig拡張サンプル.
 */
class TwigExtension extends AbstractExtension {

続いてTwig関数を定義するためにgetFunctionsを実装します。 getFunctionsは親クラスであるAbstractExtension（厳密にはExtensionInterface）で定義されている関数で、追加したい関数のリストを返します。

  /**
   * {@inheritdoc}
   */
  public function getFunctions() {
    return [
      new TwigFunction('say_hello', [$this, 'sayHello']),
    ];
  }

戻り値はTwigFunctionクラスの配列である必要があります。

TwigFunctionコンストラクタの第1引数には、Twig内で使用する関数名を指定します。今回はsay_helloとしています。

第2引数には、Twig関数が呼ばれた際に実行する関数を指定します。
グローバル関数名を直接指定したり、無名関数を指定したりすることもできますが、今回はTwigExtensionクラスのsayHello関数を指定しています。

ちなみにgetFunctionsという名前の通り、複数の関数を一度に定義することが可能です。複数を定義した場合は以下のようになります

  /**
   * {@inheritdoc}
   */
  public function getFunctions() {
    return [
      new TwigFunction('say_hello', [$this, 'sayHello']),
      new TwigFunction('say_bye', [$this, 'sayBye']),
    ];
  }

最後に実際に処理を行うsayHello関数を定義します。と言っても今回は単純なテキストを出力するだけなので、以下のようになります。

  /**
   * Hello.
   *
   * @param string $name
   *    名前.
   *
   * @return string
   *    Hello 名前
   */
  public function sayHello($name) {
    return "Hello ${name}";
  }

以上でTwigExtension.phpの作成は終了です。

sample_twig_extension.services.yml

先ほどTwigExtension.phpを作成しましたが、まだこの段階ではモジュールを有効化してもsay_hello関数を使用できるようにはなりません。TwigExtension.phpがTwigの拡張機能であるということをシステムに伝える必要があります。 services.ymlはそのためのファイルです。

services:
  sample_twig_extension.twig_extension: # 任意の識別子
    class: Drupal\sample_twig_extension\TwigExtension # Twig拡張を提供するクラス
    tags:
      - { name: twig.extension } # Twigの拡張として認識させるためのタグ（!ここは変更してはいけない）

最も大切な部分がtagsです。
tagsを{ name: twig.extension }としないとTwigの拡張機能として認識してもらえないので要注意です。

以上でカスタムモジュールの作成は完了です。

モジュールを有効化して、twig内で

{{ say_hello('Drupal') }}

とすると、画面上にHello Drupalと出力されることが確認できるかと思います。

まとめ

いかがでしたでしょうか。
作成するファイル数も少ないので、それほどハードルも高くないかと思います。
機会がありましたら是非お試しください。