Twig фильтры

Другие статьи серии Twig

Для вывода переменной в Twig шаблоне ее нужно заключить в двойные фигурные скобки {{ var }}. Если же переменную перед выводом нужно изменить (модифицировать), то для этого предусмотрены Twig фильтры. Фильтры отделяются от переменной символом | и могут опционально принимать аргументы. К одной переменной можно применить несколько фильтров, которые будут применены последовательно в порядке их указания. Абстрактный пример применения фильтров выглядит так:


{{ var|filter1(arg1, arg2)|filter2 }}

Twig шаблонизатор имеет большой набор фильтров "на все случаи жизни", но и Drupal тоже добавляет свои специфичные фильтры.

Рассмотрим фильтры, которые предоставляет сам Twig:

Фильтр abs

Фильтр abs возвращает абсолютное значение числа (использует PHP функцию abs()):


{# number = -5 #}
{{ number|abs }}
{# Результат: 5 #}

Фильтр batch

Фильтр batch разбивает массив на подмассивы с количеством элементов равным первому переданному аргументу. Второй параметр используется, чтобы заполнить недостающие элементы:


{% set items = ['a', 'b', 'c', 'd', 'e', 'f', 'g'] %}
<table>
  {% for row in items|batch(3, 'No item') %}
    <tr>
      {% for column in row %}
        <td>{{ column }}</td>
      {% endfor %}
    </tr>
  {% endfor %}
</table>

Результат применения фильтра:


<table>
  <tr>
    <td>a</td>
    <td>b</td>
    <td>c</td>
  </tr>
  <tr>
    <td>d</td>
    <td>e</td>
    <td>f</td>
  </tr>
  <tr>
    <td>g</td>
    <td>No item</td>
    <td>No item</td>
  </tr>
</table>

Фильтр capitalize

Фильтр capitalize преобразует входную строку. Первый символ будет в верхнем регистре, остальные - в нижнем:


{{ 'drupal 8'|capitalize }}
{# Результат: 'Drupal 8' #}

Фильтр convert_encoding

Фильтр convert_encoding преобразует строку из одной кодировки в другую. Первым аргументом является текущая кодировка, вторым - ожидаемая кодировка. Для использования данного фильтра должны быть установлены расширения Iconv или MBstring. В случае, если установлены оба, MBstring используется по умолчанию.


{{ data|convert_encoding('UTF-8', 'iso-2022-jp') }}

Фильтр date

Фильтр date формирует дату в заданном формате (использует php функцию date()):


{{ node.getCreatedTime()|date('m/d/Y') }}

По умолчанию, дата отображается с применением часового пояса (часовой пояс указан в php.ini), но вы можете заменить его, явно указав часовой пояс:


{{ node.getCreatedTime()|date('m/d/Y', 'Europe/Minsk') }}

В Drupal 8 имеется свой фильтр форматирования даты format_date.

Фильтр date_modify

Фильтр date_modify изменяет дату по заданному модификатору. Фильтр принимает аргументом строку (она должна быть в формате, поддерживаемом php функцией strtotime()) или экземпляр php класса DateTime. Его можно легко объединить с фильтром date для форматирования даты.


{{ node.getCreatedTime()|date_modify('+1 day')|date('m/d/Y') }}

Фильтр default

Фильтр default возвращает переданное значение по умолчанию, если значение не определено или пусто, в противном случае значение переменной:


{{ var|default('var is not defined') }}
{{ var.foo|default('foo item on var is not defined') }}

При вызове методов также можно передавать значение по умолчанию и назначать значение по умолчанию возвращаемому результату:


{{ var.method(foo|default('foo'))|default('foo') }}

Фильтр escape

Фильтр escape экранирует строку для вывода (использует php функцию htmlspecialchars() для html). Он поддерживает различные настройки в зависимости от контекста шаблона. По умолчанию экранируется HTML:


{{ user.name|escape }}

Для удобства работы с фильтром у него есть псевдоним:


{{ user.name|e }}

Фильтр escape поддерживает следующие методы экранирования:

  • html - экранирует строку для контекста HTML (по умолчанию);
  • js - экранирует строку для контекста JavaScript;
  • css - экранирует строку для контекста CSS;
  • url - экранирует строку для URI;
  • html_attr - экранирует строку для контекста атрибута HTML.

Таким образом экранируется JavaScript:


{{ user.username|escape('js') }}
{{ user.username|e('js') }}

В Drupal 8 имеется свой собственный фильтр drupal_escape.

Фильтр first

Фильтр first возвращает первый элемент массива или первый символ строки:


{{ [1, 2, 3, 4]|first }}
{# Результат: 1 #}

{{ { a: 1, b: 2, c: 3, d: 4 }|first }}
{# Результат: 1 #}

{{ '1234'|first }}
{# Результат 1 #}

Применяется также и к объектам, являющимся экземпляром класса, имплементирующего интерфейс Traversable.

Фильтр format

Фильтр format форматирует заданную строку, заменяя метки (метки пишутся в нотации php функции sprintf()):


{{ "I like %s and %s."|format(foo, "bar") }}
{# Результат: 'I like foo and bar' #}

Фильтр join

Фильтр join объединяет элементы массива в строку:


{{ [1, 2, 3]|join }}
{# Результат: 123 #}

Разделитель между элементами по-умолчанию является пустой строкой, но вы можете определить его, задав в аргументе:


{{ [1, 2, 3]|join('|') }}
{# Результат: 1|2|3 #}

В Drupal 8 рекомендуется использовать более безопасный фильтр safe_join.

Фильтр json_encode

Фильтр json_encode возвращает представление JSON строки:


{% set items = ['a', 'b', 'c', 'd', 'e', 'f', 'g'] %}
{{ items|json_encode() }}
{# Результат: строка json '["a","b","c","d","e","f","g"]' #}

Фильтр keys

Фильтр keys возвращает ключи массива. Это полезно, когда вы хотите перебрать ключи массива:


{% for key in array|keys %}
    ...
{% endfor %}

Фильтр last

Фильтр last возвращает последний элемент массива или последний символ строки:


{{ [1, 2, 3, 4]|last }}
{# Результат: 4 #}

{{ { a: 1, b: 2, c: 3, d: 4 }|last }}
{# Результат: 4 #}

{{ '1234'|last }}
{# Результат: 4 #}

Применяется также и к объектам, являющиеся экземпляром класса, имплементирующего интерфейс Traversable.

Фильтр length

Фильтр length возвращает количество элементов массива или длину строки:


{% if users|length > 10 %}
    ...
{% endif %}

Фильтр lower

Фильтр lower преобразует значение строки в нижний регистр:


{{ 'WELCOME'|lower }}
{# Результат: 'welcome' #}

Фильтр merge

Фильтр merge сливает два массива вместе:


{% set values = [1, 2] %}
{% set values = values|merge(['apple', 'orange']) %}
{# Массив values содержит  [1, 2, 'apple', 'orange'] #}

Фильтр nl2br

Фильтр nl2br вставляет тег br перед каждым переводом строки:


{{ "I like Twig.\nYou will like it too."|nl2br }}
{# Результат:
    I like Twig.<br />
    You will like it too.
#}

Фильтр number_format

Фильтр number_format позволяет форматировать числа (использует php функцию number_format()):


{{ 200.35|number_format }}
{# Результат: 200 #}

Вы можете изменять количество знаков после запятой, десятичную точку и разделитель тысяч, используя дополнительные аргументы. Если аргументы не переданы, то Twig будет использовать параметры форматирования по умолчанию: 0 знаков после запятой; . в качестве десятичной точки; , Как разделитель тысяч.


{{ 9800.333|number_format(2, '.', ',') }}
{# Результат: 9,800.33 #}

Фильтр raw

Фильтр raw отмечает значение переменной как "безопасное", что означает, что в блоке экранирования autoescape эта переменная будет выведена как не экранируемая:


{% autoescape %}
    {{ var|raw }} {# var не экранируется #}
{% endautoescape %}

Фильтр replace

Фильтр replace форматирует входную строку, заменяя метки:


{{ "I like %this% and %that%."|replace({'%this%': foo, '%that%': "bar"}) }}
{# Результат: 'I like foo and bar' #}

Фильтр reverse

Фильтр reverse возвращает массив с элементами в обратном порядке или переворачивает строку задом наперед:


{% for user in users|reverse %}
    ...
{% endfor %}

{{ '1234'|reverse }}
{# Результат: 4321 #}

Для массивов числовые ключи не сохраняются. Если передать в аргумент true, то ключи будут сохранены. Не числовые ключи не подвержены этой опции и всегда сохраняются:


{% for key, value in {1: "a", 2: "b", 3: "c"}|reverse %}
    {{ key }}: {{ value }}
{% endfor %}
{# Результат: 0: c    1: b    2: a #}

{% for key, value in {1: "a", 2: "b", 3: "c"}|reverse(true) %}
    {{ key }}: {{ value }}
{%- endfor %}
{# Результат: 3: c    2: b    1: a #}

Фильтр round

Фильтр round округляет числа с указанной точностью. Фильтр имеет два необязательных аргумента, первый из которых определяет точность (по умолчанию 0), а второй - метод округления (по умолчанию common):

  • common - округление в большую или меньшую сторону в зависимости от дробной части (округляет значение, отсекая дробную часть). Если дробная часть равна 1,5 измениться на 2 и -1,5 на -2;
  • ceil - округляет в большую сторону;
  • floor - округляет в меньшую сторону.

{{ 42.55|round }}
{# Результат: 43 #}

{{ 42.55|round(1, 'floor') }}
{# Результат: 42.5 #}

Фильтр slice

Выбирает срез массива или возвращает подстроку (использует PHP функцию array_slice() для массивов и substr() для строк). Принимает 2 аргумента: start - начальный индекс массива или позиция строки (начинается с 0, возможны отрицательные значения) и length - количество элементов массива или символов строки.


{{ '12345'|slice(1, 2) }}
{# Результат: 23 #}

{% for i in [1, 2, 3, 4, 5]|slice(1, 2) %}
    {# В цикле будет массив [2, 3] #}
{% endfor %}
{# Можно использовать упрощенный синтаксис #}
{% for i in [1, 2, 3, 4, 5][1:2] %}
    {# ... #}
{% endfor %}
{# Первый аргумент можно не указывать - по-умолчанию будет start 0  #}
{{ '12345'[:2] }} 
{# Результат: '12' #}

{# Второй аргумент length также можно пропустить - будет выбирать до конца массива/строки #}
{{ '12345'[2:] }} 
{# Результат: '345' #}

Фильтр sort

Фильтр sort сортирует массив в алфавитном порядке c сохранением ключей (использует PHP функцию asort()):


{% for user in users|sort %}
    ...
{% endfor %}

Фильтр split

Фильтр split разбивает строку по заданному разделителю и возвращает массив строк:


{% set array = 'one,two,three'|split(',') %}
{# Результат: array содержит массив ['one', 'two', 'three'] #}

Фильтр striptags

Фильтр striptags удаляет html теги и заменяет множественные пробелы на 1 пробел (использует PHP функцию strip_tags()), а теги, переданные в аргумент не вырезает:


{% set some_html = '<p>Paragraph.</p><!-- Comment --> <a href="#fragment">Anchor</a>'; %}
{{ some_html|striptags('<a>') }}
{# Результат: 'Paragraph. <a href="#fragment">Anchor</a>' #}

Фильтр title

Фильтр title возвращает всю строку в нижнем регистре, первый символ в каждом слове будет заглавным:


{{ 'my first car'|title }}
{# Результат: 'My First Car' #}

Фильтр trim

Фильтр trim удаляет пробелы (или любые другие символы, переданные в аргументе) из начала и конца строки:


{{ '  I like Twig.  '|trim }}
{# Результат: 'I like Twig.' #}

{{ '  I like Twig.'|trim('.') }}
{# Результат: '  I like Twig' #}

Фильтр upper

Фильтр upper возвращяет строку в верхнем регистре:


{{ 'welcome'|upper }}
{# Результат: 'WELCOME' #}

Фильтр url_encode

Фильтр url_encode кодирует полученную строку как URL сегмент или массив запросов в строку:


{{ "path-seg*ment"|url_encode }}
{# Результат: 'path-seg%2Ament' #}

{{ "string with spaces"|url_encode }}
{# Результат: 'string%20with%20spaces' #}

{{ {'param': 'value', 'foo': 'bar'}|url_encode }}
{# Результат: 'param=value&foo=bar' #}

Drupal специфичные фильтры

Drupal специфичные фильтры объявлены в TwigExtension::getFilters:

Фильтр t

Фильтр t обрабатывает строку с помощью drupal функции t() и возвращает перевод строки:


<a href="{{ url('<front>') }}" title="{{ 'Home'|t }}">{{ 'Home'|t }}</a>
{# Результат: <a href="http://example.com/" title="Главная">Главная</a>  #}

В строке можно использовать «заменители» для вставки переменных, значение которых нужно передать в аргумент фильтра в виде ассоциативного массива (подробнее в документации FormattableMarkup::placeholderFormat):


{{ 'Welcome, @username'|t({ '@username': user.name }) }}
{# Результат: 'Добро пожаловать, User' #}

Фильтр t

Фильтр trans является абсолютным аналогом фильтра t:


<a href="{{ url('<front>') }}" title="{{ 'Home'|trans }}">{{ 'Home'|trans }}</a>
{# Результат: <a href="http://example.com/" title="Главная">Главная</a>  #}

Фильтр placeholder

Фильтр placeholder используется внутри тега trans. Перед выводом переменная экранируется и оборачивается тегом em с классом placeholder. Переменная в строке перевода помечается %:


<div>
  {% trans %}
    Disabled: {{ string|placeholder }}
  {# В перевод попадет строка в виде: 'Disabled: %string' #}
  {# Результат вывода: '<em class="placeholder">Disabled: String</em>'  #}
  {% endtrans %}
  {% trans %}
    Disabled: {{ string }}
  {# В перевод попадет строка в виде: 'Disabled: @string' #}
  {# Результат вывода: 'Disabled: String'  #}
  {% endtrans %}
</div>

Фильтр drupal_escape

Переопределяет twig фильтр escape. Возвращает экранированный и уже отрендеренный вывод переменной.

Фильтр safe_join

Фильтр аналогичен Twig фильтру join, за тем лишь исключением, что все элементы массива перед объединением в строку экранируются:


{% set array = ['<a href="#"></a>', 'foo'] %}
{{ array|safe_join }}
{# Результат: '&lt;a href=&quot;#&quot;&gt;&lt;/a&gt;foo' #}

Фильтр without

Создает копию рендерного массива и удаляет дочерние элементы массива, которые передаются в аргументы фильтра. При этом оригинальный массив будет доступен со всеми дочерними элементами для дальнейшего вывода в шаблоне:


<div class="layout-region layout-region-node-main">
  {#  Форма будет выведена без form.advanced и form.actions #}
  {{ form|without('advanced', 'actions') }}
</div>
{#  Затем выводим отдельно form.advanced и form.actions #}
<div class="layout-region layout-region-node-secondary">
  {{ form.advanced }}
</div>
<div class="layout-region layout-region-node-footer">
  {{ form.actions }}
</div>

В Drupal 7 тот же самый пример выглядел бы так:


<?php
hide($form['advanced']);
hide($form['actions']);
?>
<div class="layout-region layout-region-node-main">
  <?php print drupal_render_children($form); ?>
</div>
<div class="layout-region layout-region-node-secondary">
  <?php print render($form['advanced']); ?>
</div>
<div class="layout-region layout-region-node-footer">
  <?php print render($form['actions']); ?>
</div>

Фильтр clean_class

Фильтр clean_class подготавливает строку для использования ее в качестве валидного имени класса (использует Html::getClass):


{%
  set classes = [
    'taxonomy-term',
    'vocabulary-' ~ term.bundle|clean_class,
  ]
%}

Фильтр clean_id

Фильтр clean_id подготавливает строку для использования ее в качестве валидного html атрибута id (использует Html::getId):


{% set heading_id = attributes.id ~ '-menu'|clean_id %}

Фильтр render

Фильтр render применим к переменным, содержащим рендерные массивы и преобразует массив в уже отрендеренный вывод. Тем не менее применять его в шаблонах к рендерным массивам не нужно, так как все переменные при выводе в шаблоне будут отрендерены.


{{ content.field_tags|render }}
{# Аналогично #}
{{ content.field_tags }}

Фильтр format_date

Фильтр format_date форматирует дату. Первым аргументом принимает формат, который может быть одним из предустановленных: 'short', 'medium', 'long', 'html_datetime', 'html_date', 'html_time', 'html_yearless_date', 'html_week', 'html_month', 'html_year' либо же 'custom', который позволяет передать во второй аргумент нужный php date формат. Третьим аргументом можно передать часовой пояс, четвертым - код языка для перевода (по умолчанию NULL):


{{ node.getChangedTime()|format_date('html_date')}}
{# Результат: '2015-11-11' #}



Официальная документация по Twig фильтрам http://twig.sensiolabs.org/doc/filters/index.html