Twig テンプレートの変数のデバッグ

Drupal テーマ作成ガイド
この記事は「 Discovering and Inspecting Variables in Twig Templates 」の翻訳です。
Table of content

はじめに

最終更新日 2018年12月28日

Twigテンプレートファイルを操作する場合、利用可能な変数はテンプレートファイルのコメントに記載されます。しかし、記載されていなかったり、テーマやモジュールで、別途変数定義されている場合、テンプレート内で利用可能な変数を検出する必要があります。Twigでは、dump()関数を使って、テンプレートファイルで利用可能な変数を検出できます。

Twig が提供する dump() 関数により、テンプレートファイルから利用可能な変数の発見と検査が可能です。

dump() 関数は、デバッグが有効になっていないと使用できません。(参考:Twigでデバッグを有効にする方法

有効になると、dump() 関数は、テンプレート内の1つまたは複数の変数の情報を出力します。

1つの変数を調査する

テンプレートで利用可能な変数「title」がある場合、次のコードで、その内容がテンプレートに出力されます。

{{ dump(title) }}

テンプレート内で利用可能な変数をすべて調査する

利用可能なすべての変数とその内容をテンプレートに出力するには、(デバッグを有効にした後で)テンプレートに次の行を追加します。

{{ dump() }}

Twig で利用可能な変数名のみを出力するには、以下を使用します。

{{ dump(_context|keys) }}

すべての Twig テンプレートで利用可能なグローバル変数があります:

  • _self

    現在のテンプレートに関する詳細な情報、コンパイルされたテンプレートクラス名と Twig 環境に関する情報を参照します。ただし、「_self」変数は廃止され、Twigバージョン2.xから削除されました。

  • _context

    theme() から送られた変数、前処理で準備された変数、テンプレート内で設定された変数など、現コンテキストでテンプレートに渡されるすべての変数を参照します。変数を指定せずに {{ dump() }} と指定するのは {{ dump(_context) }} と指定するのと同義になります。

  • _charset

    現在の文字セットを参照します。

dump() を使用する際の注意点

すべての変数を出力したいが、再帰処理などで、dump() がメモリを使い果たす場合は、_context をループさせることで、すべてのキー(変数名)を表示可能です。

<ol>
  {% for key, value in _context  %}
    <li>{{ key }}</li>
  {% endfor %}
</ol>

たとえば {% if loop.index == 2 %} のような条件を指定し、その条件に合う場合のみ、その値を出力することも可能です。

詳しくは

詳細は、Twig の dump関数ドキュメント を参照してください。

xdebug を使ったデバッグ

デバッグには、xdebug プラグインを IDE 内で使用することをお勧めします。

PHPstorm(商用ソフトウェア)では、xdebug を 簡単に導入できます。マイクロソフト製 VSCode は、商用ソフトウェアではなく、同等の機能のプラグインがある無料のオープンソース IDE です。

xdebug を使用すると、プロセスを段階的に実行し、変数の内容を出力し、dump、kint の使用時に発生するかもしれない無限ループを防ぐと同時に、隠れたバグを解消することが可能です。

twig_xdebug モジュールは、xdebug を使い、利用可能な変数を出力します。

kint を使ったデバッグ

Twig の dump() 機能は、ページ内にたくさんのテキストを出力することが多く、その中から使用したい変数を探すのが大変です。

PHPのデバッグツール kint は、dump() の代わりに使えます。kint() 関数は dump() 関数と同じように機能し、さらに出力される変数を折りたたみ・展開ができる表示形式で出力します。

devel project には、テーマ開発者が dump() の代わりに kint() が使用できる devel kint モジュールがあります。

  1. develモジュール をダウンロードします。
  2. "devel kint" モジュールを有効にします。
  3. dump 関数と同様、kint()もデバッグが有効になっていないと変数を表示しません。(参考:Twigでデバッグを有効にする方法
  4. Twig ファイルでは、dump() と同様、kint() で変数を検出します。
  5. 必要に応じて、Search Kintモジュール をダウンロード・インストールして、ネストされた変数リストを検索します。

メソッドとクラスのホワイトリストポリシー

オブジェクトを扱う際には、TwigSandboxPolicy クラスを使って特定の getter と setter オブジェクト一式の呼び出しをホワイトリストに追加します。これは、誤ったメソッドがテンプレート内で呼び出されないようにするためです。例えば、ノードオブジェクトの {{ node.delete }} メソッドは、ホワイトリストが設定されてない場合、そのノードを削除する可能性があるためです。settings.php へ以下のように追記することでホワイトリストを拡張することができます。

$settings['twig_sandbox_whitelisted_methods'] = [
  'id',
  'label',
  'bundle',
  'get',
  '__toString',
  'toString',
  'referencedEntities',
];

'referencedEntities' のように、テンプレート内で使用したいメソッドを指定します。

 
フッターの採用情報