/twig-ja

Permalink
Switch branches/tags
Nothing to show
Find file
twig-ja/02-Twig-for-Template-Designers.markdown
c4bb21c Jan 6, 2010
Raw Blame History
835 lines (548 sloc) 36.5 KB

テンプレートデザイナーのための Twig

このドキュメントではテンプレートエンジンの構文とセマンティックスを説明します。これによって Twig テンプレートを作るためにもっとも役に立つリファレンスになります。

概要

テンプレートはシンプルなテキストファイルです。これは任意のテキストベースのフォーマット (HTML、XML、CSV、LaTeX など) を生成できます。特定の拡張子、.html もしくは .xml はとてもよいものです。

テンプレートは変数もしくは式を収めます。これらはテンプレートが評価されるとき、値、テンプレートのロジックをコントロールするタグに置き換えられます。

下記のコードはごくわずかな基本を描写するための最小のテンプレートです。詳細はこのドキュメントの後のほうで説明します:

[twig]
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN">
<html lang="en">
  <head>
    <title>My Webpage</title>
  </head>
  <body>
    <ul id="navigation">
    {% for item in navigation %}
      <li><a href="{{ item.href }}">{{ item.caption }}</a></li>
    {% endfor %}
    </ul>

    <h1>My Webpage</h1>
    {{ a_variable }}
  </body>
</html>

2種類の区切り文字: {% ... %} と {{ ... }} があります。前者は for ループなどを実行するのに使われ、後者は式の結果をテンプレートに表示します。

変数

アプリケーションはテンプレートに変数を渡します。テンプレートのなかで変数を扱うことができます。変数は属性もしくは要素 を収めることが可能でこれらにアクセスすることもできます。変数の見た目は、アプリケーションがどのように提供するのかに大いに依存します。

変数の属性にアクセスするためにドット (.) を使うことができます。代わりにいわゆる"添字"構文 ([]) を使うこともできます。次の行は同じものです:

[twig]
{{ foo.bar }}
{{ foo['bar'] }}

NOTE 波かっこが変数の一部ではなく print ステートメントであることを知っていることが大切です。タグ内部の変数にアクセスする場合かっこで囲まないでください。

変数もしくは属性が存在しない場合、null の値が返ってきます (この値は none 式でテストできます)。

SIDEBAR 実装

利便性のために foo.bar は PHP レイヤーで次のことを行います:

  • foo が配列で bar が有効な要素であることをチェックします;
  • そうではない場合、かつ foo がオブジェクトである場合、bar が有効なプロパティであることをチェックします;
  • そうではない場合、かつ foo がオブジェクトである場合、bar が有効なメソッドであることをチェックします;
  • そうではない場合、かつ foo がオブジェクトである場合、getBar が有効なメソッドであることをチェックします;
  • そうではない場合、null の値を返します。

一方で foo['bar'] は次の順序での小さな違い以外ほとんど同じように機能します:

  • foo が配列で bar が有効な要素であることをチェックします;
  • そうでなければ、null の値を返します

代替構文を使うことは配列から動的に属性を取得するのにも役立ちます:

[twig]
foo[bar]

フィルター

変数はフィルターによって修正されます。フィルターはパイプ記号 (|) によって変数から区切られかっこのなかでオプション引数を記入することができます。複数のフィルターをつなげることができます。ひとつのフィルターの出力は次のフィルターに適用されます。

たとえば {{ name|striptags|title }} は name からすべての HTML タグを除去しタイトルケースバージョンに置き換えます。引数を受け取るフィルターは関数呼び出しのように引数をかっこで囲みます。次の例ではコンマによってリストをつなげます: {{ list|join(', ') }}

下記の組み込みフィルターのセクションですべてのフィルターを説明します。

コメント

テンプレートのなかで行の一部をコメントアウトするには、コメント構文: {# ... #} を使います。これはデバッグ作業のためにテンプレートの一部をコメントアウトするもしくはほかのテンプレートデザイナーもしくはあなた自身の情報を追加するのに便利です:

[twig]
{# note: disabled template because we no longer use this
  {% for user in users %}
      ...
  {% endfor %}
#}

空白文字のコントロール

デフォルトのコンフィギュレーションではホワイトスペースはテンプレートエンジンによってさらに修正されないので、それぞれのホワイトスペース(スペース、タブ、改行など)は未変更のまま返されます。アプリケーションが trim_blocks を使うよう Twig を設定する場合テンプレートタグの後の最初の改行は (PHP のように) 自動的に削除されます。

エスケーピング

Twig に通常は変数もしくはブロックとして処理される部分を無視させることが望ましいもしくは必要である場合があります。たとえばデフォルトの構文が使われテンプレートのなかで {{ を生の文字列として使い変数で始まらない場合、トリックを使わなければなりません。

変数の式を利用して変数の区切り文字 ({{) を出力するやり方です:

[twig]
{{ '{{' }}

より大きなセクションで raw ブロックとしてマークするのは合理的です。たとえば Twig 構文をテンプレートに入れるには次のスニペットが使えます:

[twig]
{% raw %}
  <ul>
  {% for item in seq %}
    <li>{{ item }}</li>
  {% endfor %}
  </ul>
{% endraw %}

テンプレート継承

Twig のもっとも協力な部分はテンプレート継承です。テンプレート継承はサイトのすべての共通要素を収める基本的な"スケルトン"テンプレートを作り上げ子テンプレートがオーバーライドできるブロックを定義することを可能にします。

ややこしく聞こえるかもしれませんがとても基本的です。具体例で始めるのがもっとも簡単です。

基底テンプレート

このテンプレート base.html と呼びますが、シンプルな2カラムページに使える HTML スケルトンドキュメントを定義します。空のブロックに内容を満たすのは"子"テンプレートの仕事です:

[twig]
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN">
<html lang="en">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
  {% block head %}
    <link rel="stylesheet" href="style.css" />
    <title>{% block title %}{% endblock %} - My Webpage</title>
  {% endblock %}
</head>
<body>
  <div id="content">{% block content %}{% endblock %}</div>
  <div id="footer">
    {% block footer %}
      &copy; Copyright 2009 by <a href="http://domain.invalid/">you</a>.
    {% endblock %}
  </div>
</body>

この例では、{% block %} タグは子テンプレートが満たすことができる 4 つのブロックを定義します。block タグが行うことはテンプレートエンジンに子テンプレートがテンプレートのこれらの一部をオーバーライドできることを伝えることです。

子テンプレート

子テンプレートは次のようになります:

[twig]
{% extends "base.html" %}

{% block title %}Index{% endblock %}
{% block head %}
  {% parent %}
  <style type="text/css">
    .important { color: #336699; }
  </style>
{% endblock %}
{% block content %}
  <h1>Index</h1>
  <p class="important">
    Welcome on my awesome homepage.
  </p>
{% endblock %}

ここでは {% extends %} タグがキーです。これはテンプレートエンジンにこのテンプレートが別のテンプレートを"継承する"よう指示します。テンプレートシステムがこのテンプレートを評価するとき、最初にこれらは親テンプレートを割り出します。extends タグはテンプレートの最初のタグになります。

テンプレートのファイル名はテンプレートローダーに依ります。たとえば Twig_Loader_Filesystem はファイル名を提供することでほかのテンプレートにアクセスすることを可能にします。スラッシュつきのサブディレクトリのなかのテンプレートにアクセスできます:

[twig]
{% extends "layout/default.html" %}

しかしこのふるまいは Twig を組み込むアプリケーションに依ります。子テンプレートが footer ブロックを定義しない場合、代わりに親テンプレートからの値が使われることに注意してください。

同じテンプレートのなかで同じ名前の {% block %} タグを複数定義することはできません。この制約が存在するのは block タグが"両方"の方向で働くからです。つまり、block タグは満たす穴を提供するだけでなく - 親の穴を満たす内容も定義します。1つのテンプレートのなかに似たような名前を持つ2つの{% block %} タグがあれば、そのテンプレートの親は使う block の内容の一方がwかりません。

1つのブロックを複数回表示したい場合は display タグを使います:

[twig]
<title>{% block title %}{% endblock %}</title>
<h1>{% display title %}</h1>
{% block body %}{% endblock %}

PHP のように、Twig は多重継承をサポートしません。ですのでレンダリングごとにタグを拡張するものを呼び出すことのみできます。

親ブロック

parent タグを使って親タグの内容をレンダリングすることは可能です。これは親ブロックの結果を戻します:

[twig]
{% block sidebar %}
  <h3>Table Of Contents</h3>
  ...
  {% parent %}
{% endblock %}

名前つきブロック終了タグ

Twig はよりよい可読性のために終了タグの後にブロックの名前をつけることができます:

[twig]
{% block sidebar %}
  {% block inner_sidebar %}
      ...
  {% endblock inner_sidebar %}
{% endblock sidebar %}

しかしながら単語の endblock の後の名前はブロックの名前にマッチしなければなりません。

ブロックのネストとスコープ

より複雑なレイアウトのためにブロックをネストにすることができます。デフォルトでは、ブロックは外側のスコープから変数にアクセスできます:

[twig]
{% for item in seq %}
  <li>{% block loop_item %}{{ item }}{% endblock %}</li>
{% endfor %}

ブロックのショートカット

わずかな内容を伴うブロックに対して、省略構文を用意することが可能です。次のコンストラクトは同じことを行います:

[twig]
{% block title %}
  {{ page_title|title }}
{% endblock %}

[twig]
{% block title page_title|title %}

2番目の引数を指定すると同時にこれはショーとブロックとして扱われ Twig は閉じタグとみなさなくなることに注意してください。

コンテキストのふるまいのインポート

デフォルトではインクルードされるテンプレートは現在のコンテキストに渡されます。

インクルードされたテンプレートに渡されるコンテキストはそのテンプレートで定義される変数をインクルードします:

[twig]
{% for box in boxes %}
  {% include "render_box.html" %}
{% endfor %}

インクルードされたテンプレートの render_box.html は box にアクセスできます。

HTML エスケーピング

テンプレートから HTML を生成するとき、HTML のレンダリングに影響を及ぼす文字が変数に含まれる危険性が常にあります。2つのアプローチがあります: 手動でそれぞれの変数をエスケーピングするかもしくはデフォルトですべてを自動的にエスケーピングするかです。

Twig は両方をサポートしますが、使われる方法はアプリケーションのコンフィギュレーションに依ります。さまざまな理由からデフォルトのコンフィギュレーションは自動エスケーピングではありません:

  • 安全な値以外のすべての値をエスケープすることは Twig が数字など HTML に含まれないことがわかっているものもエスケーピングし、余分な大きいな負荷がかかることを意味します。

  • 変数の安全性に関する情報はきわめて危ういものです。安全な値と安全ではない値を強制することで戻り値が二重にエスケーピングされた HTML になることもありえます。

NOTE エスケーピングは escaper エクステンションが有効である場合のみサポートされます。

手動エスケーピングに取り組む

手動エスケーピングが有効な場合、必要に応じて変数をエスケーピングするのはあなたの責任です。何をエスケーピングすればよいのか？変数が次の文字: (>, <, &, or ") のどれかを含むことがある場合変数が適格で信頼できる HTML を収めていない限りこの変数をエスケーピングしなければなりません。エスケーピングは |e フィルター: {{ user.username|e }} を通して変数をパイプすることで機能します。

自動エスケーピングに取り組む

escaper エクステンションが有効になっているとき自動エスケーピングが有効になります。

自動エスケーピングの有効無効に関わらず、autoescape タグを使うことでテンプレートのセクションをエスケーピングするかしないかを示すことができます:

[twig]
{% autoescape on %}
  Everything will be automatically escaped in this block
{% endautoescape %}

{% autoescape off %}
  Everything will be outputed as is in this block
{% endautoescape %}

自動エスケーピングが有効なとき安全なものとして明確にマークされた値以外のすべてがエスケープされます。safe フィルターを使うことでこれらをテンプレートのなかでマークすることができます。

(マクロと parent のように) テンプレートのデータを返す関数は常に安全なマークアップを返します。

NOTE Twig は escape フィルターによってすでにエスケープされた値をエスケープするほど賢くありません。

NOTE 開発者の章では自動エスケーピングがどのように適用されるのか詳しい情報を提供します。

制御構造の一覧

制御構造は、ブロックと同じように、プログラムのフローをコントロールするすべてのもの - 条件文 (すなわち if/elseif/else)、for-ループをサポートします。制御構造は {% ... %} ブロックの内側に現れます。

for

それぞれの項目を順番にループします。たとえば、users という名前の変数に提供されるユーザーの一覧を表示するには:

[twig]
<h1>Members</h1>
<ul>
  {% for user in users %}
    <li>{{ user.username|e }}</li>
  {% endfor %}
</ul>

NOTE シーケンスは配列もしくは Iterator インターフェイスを実装するオブジェクトのどちらかです。

数のシーケンスをイテレートする必要があれば、.. 演算子を使います (Twig 0.9.5 以降):

[twig]
{% for i in 0..10 %}
  * {{ i }}
{% endfor %}

上記のコードスニペットは 0 から 9 までのすべての数字を表示します (上限の値は生成される配列の一部にはなりません)。

これは文字にも役立ちます:

[twig]
{% for letter in 'a'..'z' %}
  * {{ letter }}
{% endfor %}

.. 演算子は両端で任意の式をとります:

[twig]
{% for letter in 'a'|upper..'z'|upper %}
  * {{ letter }}
{% endfor %}

差分が 1 とは異なるステップが必要な場合、代わりに range フィルターを使うことができます:

[twig]
{% for i in 0|range(10, 2) %}
  * {{ i }}
{% endfor %}

for ループブロックの内側ではいくつかの特別な変数にアクセスすることができます:

変数 説明
loop.index ループの現在のイテレーション (インデックスが1)
loop.index0 ループの現在のイテレーション (インデックスが0)
loop.revindex ループの終わりからのイテレーションの数 (インデックスが1)
loop.revindex0 ループの終わりからのイテレーションの数 (インデックスが0)
loop.first イテレーションが最初の場合 True
loop.last イテレーションが最後の場合 True
loop.length シーケンスのなかのアイテムの個数

NOTE PHP のものとは異なり、ループのなかで break もしくは continue することはできません。

シーケンスが空であるためにイテレーションが行われない場合、else を使って置き換えブロックをレンダリングすることができます:

[twig]
<ul>
  {% for user in users %}
    <li>{{ user.username|e }}</li>
  {% else %}
    <li><em>no user found</em></li>
  {% endfor %}
</ul>

デフォルトでは、ループはシーケンスの値をイテレートします。keys フィルターを使ってキーでイテレートすることができます:

[twig]
<h1>Members</h1>
<ul>
  {% for key in users|keys %}
    <li>{{ key }}</li>
  {% endfor %}
</ul>

キーと値の両方にアクセスすることもできます:

[twig]
<h1>Members</h1>
<ul>
  {% for key, value in users %}
    <li>{{ key }}: {{ user.username|e }}</li>
  {% endfor %}
</ul>

NOTE Twig 0.9.3 以前では、キーと値の両方にアクセスするには items フィルターを使う必要があります ({% for key, value in users|items %})。

if

Twig の if ステートメントは PHP の if ステートメントと互換性があります。もっともシンプルな形式において変数が定義され、空もしくは False ではないことをテストするためにこれを使うことができます:

[twig]
{% if users %}
  <ul>
    {% for user in users %}
      <li>{{ user.username|e }}</li>
    {% endfor %}
  </ul>
{% endif %}

複数の分岐には elseif と else を PHP のように使うことができます。より複雑な expressions を使うこともできます:

{% if kenny.sick %}
  Kenny is sick.
{% elseif kenny.dead %}
  You killed Kenny!  You bastard!!!
{% else %}
  Kenny looks okay --- so far
{% endif %}

マクロ

マクロは通常のプログラミング言語の関数と互換性があります。これらは同じ作業を繰り返さないようによく使われる HTML イディオムを再利用可能な関数にします。

フォーム要素をレンダリングするマクロの小さな例は次のとおりです:

[twig]
{% macro input(name, value, type, size) %}
  <input type="{{ type|default('text') }}" name="{{ name }}" value="{{ value|e }}" size="{{ size|default(20) }}" />
{% endmacro %}

いくつかの点でマクロはネイティブの PHP 関数とは異なります:

  • デフォルトの引数の値はマクロのボディで default フィルターを使って定義されます;

  • マクロの引数は常にオプションです。

PHP 関数ではありますが、現在のテンプレート変数にアクセスできません。

マクロは任意のテンプレートで定義可能で、使われる前に "import" される必要があります (詳細な情報は import のセクションを参照):

[twig]
{% import "forms.html" as forms %}

上記の import は "forms.html" ファイルのインポートを呼び出し (マクロのみ、もしくはテンプレートといくつかのマクロ)、forms 変数の項目として関数をインポートします。

マクロは意のままに呼び出すことができます:

[twig]
<p>{{ forms.input('username') }}</p>
<p>{{ forms.input('password', none, 'password') }}</p>

フィルター

フィルターセクションによって通常の Twig フィルターをテンプレートデータのブロックに適用することができるようになります。コードを特別な filter セクションに包みます:

[twig]
{% filter upper %}
  This text becomes uppercase
{% endfilter %}

フィルターを結びつけることもできます:

[twig]
{% filter lower|escape %}
  <strong>SOME TEXT</strong>
{% endfilter %}

&lt;strong&gt;some text&lt;/strong&gt; が返されます。

割り当て

コードブロック内部で値を変数に割り当てることもできます。割り当てには set タグを使い複数のターゲットを用意できます:

[twig]
{% set foo as 'foo' %}

{% set foo as [1, 2] %}

{% set foo as ['foo': 'bar] %}

{% set foo as 'foo' ~ 'bar' %}

{% set foo, bar as 'foo', 'bar' %}

extends

extends タグは1つのテンプレートが別のテンプレートを継承するのに使うことができます。1つのファイルにこれらを複数入れることができますが一度に実行されるのはこれらの1つのみです。多重継承はありません。上記のテンプレート継承を参照してください。

ブロック

ブロックは継承に使われプレースホルダーとしてふるまい置き換えが同時に行われます。これらは上記のテンプレート継承のセクションで詳しく記述されています。

include

include ステートメントはテンプレートをインクルードしてそのファイルのレンダリングされた内容を現在の名前空間に返します:

[twig]
{% include 'header.html' %}
  Body
{% include 'footer.html' %}

インクルードされるテンプレートはアクティブなコンテキストの変数にアクセスできます。

インクルードされるファイルは escaper エクステンションが有効にされている場合に行の終わりに sandboxed を追加することでサンドボックス環境のななかで評価されます:

[twig]
{% include 'user.html' sandboxed %}

変数を配列として明確に渡すことでテンプレートに渡される変数を制限することもできます:

[twig]
{% include 'foo' with ['foo': 'bar'] %}

{% set vars as ['foo': 'bar'] %}
{% include 'foo' with vars %}

テンプレートをインクルードするためのもっともセキュアな方法は sandboxed モードを使い、テンプレートを正しくレンダリングするために必要最小限の変数を渡すことです:

[twig]
{% include 'foo' sandboxed with vars %}

NOTE with キーワードは Twig 0.9.5 でサポートされます。

import

Twig はよく使われるコードをマクロにまとめます。これらのマクロは異なるテンプレートに入れてそこからインポートできます。

フォームをレンダリングするヘルパー (forms.html) がある状況を想像してください:

[twig]
{% macro input(name, value, type, size) %}
  <input type="{{ type|default('text') }}" name="{{ name }}" value="{{ value|e }}" size="{{ size|default(20) }}" />
{% endmacro %}

{% macro textarea(name, value, rows) %}
  <textarea name="{{ name }}" rows="{{ rows|default(10) }}" cols="{{ cols|default(40) }}">{{ value|e }}</textarea>
{% endmacro %}

テンプレートのなかでこれらのマクロをインポートするのは簡単で import タグを使います:

[twig]
{% import 'forms.html' as forms %}
<dl>
  <dt>Username</dt>
  <dd>{{ forms.input('username') }}</dd>
  <dt>Password</dt>
  <dd>{{ forms.input('password', none, 'password') }}</dd>
</dl>
<p>{{ forms.textarea('comment') }}</p>

マクロが使いたいテンプレートのなかで定義されている場合でも、これらをインポートする必要があります:

[twig]
{# index.html template #}

{% macro textarea(name, value, rows) %}
  <textarea name="{{ name }}" rows="{{ rows|default(10) }}" cols="{{ cols|default(40) }}">{{ value|e }}</textarea>
{% endmacro %}

{% import "index.html" as forms %}

<p>{{ forms.textarea('comment') }}</p>

デバッグ

テンプレートが期待どおりに動かないときは、現在のコンテキストの内容を出力するためにデバッグタグを使うことができます:

[twig]
{% debug %}

特定の変数もしくは式を出力することもできます:

[twig]
{% debug items %}

{% debug post.body %}

このタグは環境の debug オプションが true にセットされる場合のみ機能することに注意してください。

式

Twig では基本的な式はどこでも使うことができます。これらは通常の PHP ととても似た動きをし PHP に取り組んでいない場合、これを使うのが快適に感じるでしょう。

演算子の優先順位が低い順の一覧は次のとおりです: or、and、==、!=、<, >、>=、<=、in、+、-、~、 *、/、%、//、not、そして [

リテラル

式のもっともシンプルな形式はリテラルです。リテラルは PHP の型の表現で、たとえば文字列、数字、配列などです。次のリテラルが存在します:

  • "Hello World": 2つのダブルクォートもしくはシングルクォートで囲まれるものはすべて文字列です。これらはテンプレートのなかで文字列が必要なときに便利です (たとえば関数呼び出しの引数、もしくはフィルターもしくはテンプレートを継承もしくはインクルードするため)。

  • 42 / 42.23: 数字を書き留めるだけで数字と浮動小数点が作られます。ドットがあれば浮動少数点で、さもなければ整数です。

  • [foo, bar]: 配列はコンマ (,) によって区切られる式の文字列によって定義され角かっこ ([]) によって囲まれます。配列の要素は任意の有効な式になることが可能なので、配列をネストにすることができます。配列の表記は Twig 0.9.5 以降でのみ可能です。

  • true / false / none: true は真の値を表し、false は偽の値を表します。

  • none: none は特定の値を表しません (PHP の null と同等)。これは変数が存在しない場合に返される値です。

数学

Twig は値で計算することを可能にします。これはめったに使いませんが完全性のために存在します。次の演算子がサポートされます:

  • +: 2つのオブジェクトを一緒に加えます。通常オブジェクトは数字ですが両方が文字列もしくはリストの場合この方法でこれらを連結させることができます。しかしながらこの方法は文字列を連結するのに望ましくありません！文字列の連結の例として ~ 演算子を見てみましょう。{{ 1 + 1 }} は 2 になります。

  • -: 最初の数値から2番目の数値を引きます。{{ 3 - 2 }} は 1 です。

  • /: 2つの数値で割ります。返される値は浮動少数点です。{{ 1 / 2 }} は {{ 0.5 }} です。

  • %: は整数の割り算の余りを計算します。{{ 11 % 7 }} は 4 です。

  • *: 左側のオペランドと右側のオペランドを掛けます。{{ 2 * 2 }} は 4 を返します。これは文字列を複数回繰り返すのにも使われます。{{ '=' * 80 }} は80の等号記号を表示します。

  • **: 左側のオペランドを右側のオペランドでべき乗した値を算出します。{{ 2**3 }} は8を返します。

論理学

if ステートメント、for フィルタリングもしくは if 式です。これは複数の式を組み合わせるのに役立ちます:

  • and: 左と右側のオペランドが true である場合 true を返します。

  • or: 左側と右側のオペランドのどちらかが true である場合 true を返します。

  • not: ステートメントを否定します。

  • (expr): Group an expression.

比較

次の演算子は任意の式でサポートされます: ==、!=、<, >、>=、と <=

TIP PHP の古典的な比較演算子に加えて、Twig は値が指定の範囲のなかに収まるのかテストするための省略記法もサポートします:

[twig]
{% if 1 < foo < 4 %}foo is between 1 and 4{% endif %}

その他の演算子

次の演算子はとても便利ですがその他の2つのカテゴリには当てはまりません:

  • in (Twig 0.9.5 の新しい機能): 包含関係のテストを実行します。左側のオペランドが右側のオペランドに含まれる場合 true を返します。たとえば、{{ 1 in [1, 2, 3] }} は true を返します。逆のテストを行うには、式全体にプレフィックスとして not をつけます({{ not 1 in [1, 2, 3] }} は false を返します)。

  • .. (Twig 0.9.5 の新しい機能): 演算子前後のオペランドをもとにシーケンスを作ります (使い方のいくつかの例は for タグを参照)。

  • |: フィルターを適用する。

  • ~: すべてのオペランドを文字列に変換して連結します。{{ "Hello " ~ name ~ "!" }} は (name は 'John' とします) Hello John! を返します。

  • ., []: オブジェクトの属性を取得します。

  • ?:: Twig は PHP の三項演算子をサポートします:

     [twig]
 {{ foo ? 'yes' : 'no' }}

組み込みフィルターの一覧

date

date フィルターは日付を任意の書式に置き換えることができます:

[twig]
{{ post.published_at|date("m/d/Y") }}

date フィルターはタイムスタンプと DateTime インスタンスの両方を受け取ります。

format

format フィルターはプレースホルダーを置き換えることで任意の文字列をフォーマッティングします:

[twig]
{# string is a format string like: I like %s and %s. #}
{{ string|format(foo, "bar") }}
{# returns I like foo and bar. (if the foo parameter equals to the foo string) #}

even

even フィルターは渡される値が偶数の場合、true を返し、そうでなければ false を返します:

[twig]
{{ var|even ? 'even' : 'odd' }}

odd

odd フィルターは渡される値が奇数の場合 true を返し、そうでなければ false を返します:

[twig]
{{ var|odd ? 'odd' : 'even' }}

floor

floor フィルターは2つの数を割り整数の商を返します:

[twig]
{{ 20|floor(7) }} {# returns 2 #}

encoding

encoding フィルターは任意の文字列を URL エンコーディングします。

title

title フィルターは値のタイトルケースバージョンを返します。すなわち、単語は大文字で始まり、残りの文字は小文字になります。

capitalize

capitalize フィルターは値の最初の文字を大文字にしその他の文字を小文字にします。

upper

upper フィルターは値を大文字に変換します。

lower

lower フィルターは値を小文字に変換します。

striptags

striptags フィルターは SGML/XML タグを剥ぎ取り隣接するスペースを1つのスペースに置き換えます。

join

join フィルターはシーケンスの文字列の連結である文字列を返します。デフォルトでは要素の区切り文字は空の文字列で、オプションパラメーターで定義することができます:

[twig]
{{ [1, 2, 3]|join('|') }}
{# returns 1|2|3 #}

{{ [1, 2, 3]|join }}
{# returns 123 #}

reverse

reverse フィルターは配列もしくはオブジェクトが Iterator インターフェイスを実装する場合これを逆転させます。

length

length フィルターはシーケンスもしくはマッピングのアイテムの数、もしくは文字列の長さを返します。

sort

sort フィルターは配列をソートします。

in (Twig 0.9.5 の新しい機能)

値が別のものの範囲に収まっている場合 true を返します。

[twig]
{# returns true #}

{{ 1|in([1, 2, 3]) }}

{{ 'cd'|in('abcde') }}

文字列、配列、もしくは Traversable インターフェイスを実装するオブジェクトで包含テストを実施するためにこのフィルターを使うことができます。

in 演算子は in フィルターの構文糖衣です:

[twig]
{% if 1 in [1, 2, 3] %}
  TRUE
{% endif %}

{# is equivalent to #}

{% if 1|in([1, 2, 3]) %}
  TRUE
{% endif %}

range (Twig 0.9.5 の新しい機能)

数のシーケンスを含むリストを返します。フィルターの左側は小さいほうの値を表します。フィルターの最初の引数は必須で大きいほうの値を表します。2 番目の引数はオプションでステップを表します (デフォルトは 1)。

数のシーケンスをイテレートする必要がある場合:

[twig]
{% for i in 0|range(10) %}
  * {{ i }}
{% endfor %}

TIP range フィルターは PHP ネイティブの range 関数として機能します。

.. 演算子 (上記を参照) は range フィルターの構文糖です (ステップは 1):

[twig]
{% for i in 0|range(10) %}
  * {{ i }}
{% endfor %}

{# is equivalent to #}

{% for i in 0..10 %}
  * {{ i }}
{% endfor %}

default

default フィルターは値が定義されていなければ渡されるデフォルト値を返し、そうでなければ変数の値を返します:

[twig]
{{ my_variable|default('my_variable is not defined') }}

keys

keys フィルターは配列のキーを返します。配列のキーをイテレートしたい場合に便利です:

[twig]
{% for key in array|keys %}
    ...
{% endfor %}

escape、e

escape フィルターは文字列のなかの次の文字: &、<、>、'、 と " を安全な HTML シーケンスに変換します。これらのような文字が含まれる可能性があるテキストを HTML で表示する必要がある場合はこれを使います。

NOTE 内部では、escape は PHP の htmlspecialchars 関数を使います。

safe

safe フィルターは変数を安全なものとしてマークします。このことは自動エスケーピングが有効な環境でこの変数がエスケープされないことを意味します。

[twig]
{% autoescape on }
  {{ var|safe }} {# var won't be escaped #}
{% autoescape off %}