Расширения Twig, определенные Symfony

Дата обновления перевода 2025-09-03

Расширения Twig, определенные Symfony

Twig - это щаблонизатор используемый по умолчанию в приложениях Symfony. Существуют десятки фильтров и функций по умолчанию определенных Twig, но Symfony также определяет некоторые фильтры, функции и теги, для интеграции различных компонентов Symfony с шаблонами Twig. Эта статья разъясняет их все.

Tip

Если этих расширений, предоставленных Symfony, вам недостаточно, вы можете создать пользовательское расширение Twig, чтобы определить еще больше фильтров и функций.

Функции

render

        1
        {{ render(uri, options = []) }}
    

uri: тип: string | ControllerReference
options (необязательно): тип: array по умолчанию: []

Делает запрос к заданному внутреннему URI или контроллеру и возвращает результат. Стратегия отображения может быть указана в ключе опций strategy. Часто используется для встраивания контроллеров в шаблоны .

render_esi

        1
        {{ render_esi(uri, options = []) }}
    

uri: type: string | ControllerReference
options (необязательно): type: array default: []

Похожа на функцию render и определяет те же аргументы. Однако, она генерирует тег ESI когда включена поддержка ESI, или откатывается до поведения render в других случаях.

Tip

Функция render_esi() - это пример шорткат функций render. Она автоматически устанваливает стратегию, основываясь на том, что задано в имени функции, например, render_hinclude() будет использовать стратегию hinclude.js. Это работает для всех функций render_*().

fragment_uri

        1
        {{ fragment_uri(controller, absolute = false, strict = true, sign = true) }}
    

controller: type: ControllerReference
absolute (опционально): type: boolean default: false
strict (опционально): type: boolean default: true
sign (опционально): type: boolean default: true

Генерирует URI фрагмента .

controller

        1
        {{ controller(controller, attributes = [], query = []) }}
    

controller: тип: string
attributes (необябазтельно): тип: array по умолчанию: []
query (необязательно): тип: array по умолчанию: []

Возвращает экземпляр ControllerReference для использования с функциями вроде render() и render_esi() .

asset

        1
        {{ asset(path, packageName = null) }}
    

path: тип: string
packageName (необязательно): тип: string | null по умолчанию: null

        1
2
3
4
5
6
7
        # config/packages/framework.yaml
framework:
    # ...
    assets:
        packages:
            foo_package:
                base_path: /avatars
    

        1
2
3
        {# изображение находится тут - "public/avatars/avatar.png" #}
{{ asset(path = 'avatar.png', packageName = 'foo_package') }}
{# вывод: /avatars/avatar.png #}
    

Возвращает публчный путь заданного пути ресурса (который может быть файлом CSS, JavaScript, путем изображения и т.д.). Эта функция берет во внимание, где установлено приложение (например, в случае, если доступ к проекту происходит через субкаталог хоста) и базовый путь необязательного пакета ресурсов.

Symfony предоставляет различные реализации отключения кеша через опции конфигурации , +, и .

asset_version

        1
        {{ asset_version(packageName = null) }}
    

packageName (необязательно): тип: string | null по умолчанию: null

Возвращает текущую версию пакета, больше информации в .

csrf_token

        1
        {{ csrf_token(intention) }}
    

intention: тип: string - произвольная строка, используемая для идентификации токена.

Отображает CSRF-токен. Используйте эту функцию, если вы хотите CSRF-защиту, в обычной HTML-форме не управляемой компонентом Symfony Формы.

        1
2
3
        {{ csrf_token('my_form') }}
{# вывод: a random alphanumeric string like:
   a.YOosAd0fhT7BEuUCFbROzrvgkW8kpEmBDQ_DKRMUi2o.Va8ZQKt5_2qoa7dLW-02_PLYwDBx9nnWOluUHUFCwC5Zo0VuuVfQCqtngg #}
    

is_granted

        1
        {{ is_granted(role, object = null, field = null) }}
    

role: тип: string
object (необязательно): тип: object
field (необязательно): тип: string

Возвращает true, если текущий пользователь имеет заданную роль.

Как вариант, объект может быть передан для использоваия избирателем. Больше информации можно найти в .

is_granted_for_user

7.3

Функция is_granted_for_user() была представлена в Symfony 7.3.

        1
        {{ is_granted_for_user(user, attribute, subject = null) }}
    

user: тип: object
attribute: тип: string
subject (optional): тип: object

Возвращает true, если пользователь авторизован для указанного атрибута.

Опционально можно передать объект, чтобы он использовался избирателем. Больше информации можно найти в .

logout_path

        1
        {{ logout_path(key = null) }}
    

key (необязательно): тип: string

Генерирует относительный URL выхода из системы для заданного брандмауэра. Если не предоставлен ключ, то URL генерируется для текущего брандмауэра, в системе которого находится пользователь.

        1
2
3
4
5
6
7
8
9
10
11
12
13
        # config/packages/security.yaml
security:
    # ...

    firewalls:
        main:
            # ...
            logout:
                path: '/logout'
        othername:
            # ...
            logout:
                path: '/other/logout'
    

        1
2
3
4
5
        {{ logout_path(key = 'main') }}
{# вывод: /logout #}

{{ logout_path(key = 'othername') }}
{# вывод: /other/logout #}
    

logout_url

        1
        {{ logout_url(key = null) }}
    

key (необязательно): тип: string

Приравнивается к функции logout_path, но генерирует абсолютный URL, вместо относительного.

        1
2
3
4
5
6
7
8
9
10
11
12
13
        # config/packages/security.yaml
security:
    # ...

    firewalls:
        main:
            # ...
            logout:
                path: '/logout'
        othername:
            # ...
            logout:
                path: '/other/logout'
    

        1
2
3
4
5
        {{ logout_url(key = 'main') }}
{# вывод: http://example.org/logout #}

{{ logout_url(key = 'othername') }}
{# вывод: http://example.org/other/logout #}
    

path

        1
        {{ path(name, parameters = [], relative = false) }}
    

name: тип: string
parameters (необязательно): тип: array по умолчанию: []
relative (необязательно): тип: boolean по умолчанию: false

Возвращает относительный URL (без схемы и хоста) для заданного маршрута. Если relative подключен, то он создаст путь, относительного текушего пути.

        1
2
3
4
5
6
7
        {# отметьте, что приложение определяет маршрут 'app_blog' с путем '/blog/{page}' #}

{{ path(name = 'app_blog', parameters = {page: 3}, relative = false) }}
{# вывод: /blog/3 #}

{{ path(name = 'app_blog', parameters = {page: 3}, relative = true) }}
{# вывод: blog/3 #}
    

url

        1
        {{ url(route_name, route_parameters = [], schemeRelative = false) }}
    

name: тип: string
parameters (необязательно): тип: array по умолчанию: []
schemeRelative (необязательно): тип: boolean по умолчанию: false

Возвращает абсолютный URL (со схемой и хостом) для заданного маршрута. Если schemeRelative подключен, то он создаст URL относительно схемы.

        1
2
3
4
5
6
7
        {# отметьте, что приложение определяет маршрут 'app_blog' с путем '/blog/{page}' #}

{{ url(name = 'app_blog', parameters = {page: 3}, schemeRelative = false) }}
{# вывод: http://example.org/blog/3 #}

{{ url(name = 'app_blog', parameters = {page: 3}, schemeRelative = true) }}
{# вывод: //example.org/blog/3 #}
    

absolute_url

        1
        {{ absolute_url(path) }}
    

path: тип: string

Возвращает абсолютный URL (со схемой и хостингом) из переданного относительного пути. Объедините его с функцией asset() , чтобы сгенерировать абсолютные URL для веб-ресурсов. Прочтите больше о Ссылании на ресурсы CSS, JavaScript и изображений .

relative_path

        1
        {{ relative_path(path) }}
    

path: тип: string

Возвращает относительный путь из переданного абсолютного URL. Например, представьте, что на следующей странице вашего приложения: http://example.com/products/hover-board.

        1
2
3
4
5
        {{ relative_path('http://example.com/human.txt') }}
{# ../human.txt #}

{{ relative_path('http://example.com/products/products_icon.png') }}
{# products_icon.png #}
    

expression

Создаёт Expression связанный с компонентом ExpressionLanguage.

        1
2
        {{ expression(1 + 2) }}
{# вывод: 3 #}
    

impersonation_exit_path

        1
        {{ impersonation_exit_path(exitTo = null) }}
    

exitTo (необязательно): тип: string

Генерирует URL, который вы можете посетить для выхода из имперсоназии пользователя. После выхода из имперсонации, пользователь перенаправляется по текущему URI. Если вы предпочитаете перенаправление по другому URI, определите его значение в аргументе exitTo.

Если имперсонизация пользователя не проводится, функция возвращает пустую строку.

impersonation_url

        1
        {{ impersonation_url(identifier) }}
    

identifier: тип: string

Похоже на функцию impersonation_path, но генерирует
абсолютные URL вместо относительных.

impersonation_exit_url

        1
        {{ impersonation_exit_url(exitTo = null) }}
    

exitTo (необязательно): тип: string

Похожа на функцию impersonation_exit_path, но генерирует абсолютные URL вместо относительных.

t

        1
        {{ t(message, parameters = [], domain = 'messages')|trans }}
    

message: тип: string
parameters (необязательно): тип: array default: []
domain (необязательно): тип: string default: messages

Создает объект Translatable, который может быть передан в фильтр trans .

        1
2
        # translations/blog.en.yaml
message: Hello %name%
    

        1
2
3
4
5
6
7
8
9
10
11
12
        <!-- translations/blog.en.xlf -->
<?xml version="1.0" encoding="UTF-8" ?>
<xliff version="1.2" xmlns="urn:oasis:names:tc:xliff:document:1.2">
    <file source-language="en" datatype="plaintext" original="file.ext">
        <body>
            <trans-unit id="message">
                <source>message</source>
                <target>Hello %name%</target>
            </trans-unit>
        </body>
    </file>
</xliff>
    

        1
2
3
4
        // translations/blog.en.php
return [
    'message' => "Hello %name%",
];
    

Использование фильтра будет отображено как:

        1
2
        {{ t(message = 'message', parameters = {'%name%': 'John'}, domain = 'blog')|trans }}
{# вывод: Hello John #}
    

importmap

Выводит importmap, а также некоторые другие вещи при использовании компонента Asset.

Функции, связанные с формами

Следующие функции, связанные с Формами Symfony также доступны. Они объясняются в статье о пользовательской настройке отображения форм:

form()
form_start()
form_end()
form_widget()
form_errors()
form_label()
form_help()
form_row()
form_rest()
field_name()
field_id()
field_value()
field_label()
field_help()
field_errors()
field_choices()

Фильтры

humanize

        1
        {{ text|humanize }}
    

text: тип: string

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

        1
2
3
4
5
6
        {{ 'dateOfBirth'|humanize }}    {# renders: Date of birth #}
{{ 'DateOfBirth'|humanize }}    {# renders: Date of birth #}
{{ 'date-of-birth'|humanize }}  {# renders: Date-of-birth #}
{{ 'date_of_birth'|humanize }}  {# renders: Date of birth #}
{{ 'date of birth'|humanize }}  {# renders: Date of birth #}
{{ 'Date Of Birth'|humanize }}  {# renders: Date of birth #}
    

trans

        1
        {{ message|trans(arguments = [], domain = null, locale = null) }}
    

message: тип: string
arguments (необязательно): тип: array по умолчанию: []
domain (необязательно): тип: string по умолчанию: null
locale (необязательно): тип: string по умолчанию: null

Переводит текст на текущий язык. Больше информации в Фильтрах переводов .

        1
2
        # translations/messages.en.yaml
message: Hello %name%
    

        1
2
3
4
5
6
7
8
9
10
11
12
        <!-- translations/messages.en.xlf -->
<?xml version="1.0" encoding="UTF-8" ?>
<xliff version="1.2" xmlns="urn:oasis:names:tc:xliff:document:1.2">
    <file source-language="en" datatype="plaintext" original="file.ext">
        <body>
            <trans-unit id="message">
                <source>message</source>
                <target>Hello %name%</target>
            </trans-unit>
        </body>
    </file>
</xliff>
    

        1
2
3
4
        // translations/messages.en.php
return [
    'message' => "Hello %name%",
];
    

Использование фильтра будет отображено как:

        1
2
        {{ 'message'|trans(arguments = {'%name%': 'John'}, domain = 'messages', locale = 'en') }}
{# вывод: Hello John #}
    

sanitize_html

        1
        {{ body|sanitize_html(sanitizer = "default") }}
    

body: тип: string
sanitizer (optional): тип: string по умолчанию: "default"

Дезинфицирует текст, используя компонент HTML Sanitizer. Больше информации можно найти в HTML Sanitizer .

yaml_encode

        1
        {{ input|yaml_encode(inline = 0, dumpObjects = false) }}
    

input: тип: mixed
inline (необязательно): тип: integer по умолчанию: 0
dumpObjects (необязательно): тип: boolean по умолчанию: false

Превращает ввод в синтаксис YAML.

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

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
        {% set array = {
    'a': {
        'c': 'e'
    },
    'b': {
        'd': 'f'
    }
} %}

{{ array|yaml_encode(inline = 0) }}
{# вывод:
   { a: { c: e }, b: { d: f } } #}

{{ array|yaml_encode(inline = 1) }}
{# вывод:
   a: { c: e }
   b: { d: f } #}
    

Аргумент dumpObjects включает сброс объектов PHP:

        1
2
3
4
        // ...
$object = new \stdClass();
$object->foo = 'bar';
// ...
    

        1
2
3
4
5
        {{ object|yaml_encode(dumpObjects = false) }}
{# вывод: null #}

{{ object|yaml_encode(dumpObjects = true) }}
{# вывод: !php/object 'O:8:"stdClass":1:{s:5:"foo";s:7:"bar";}' #}
    

См. , чтобы узнать больше информации.

yaml_dump

        1
        {{ value|yaml_dump(inline = 0, dumpObjects = false) }}
    

value: тип: mixed
inline (необязательно): тип: integer по умолчанию: 0
dumpObjects (необязательно): тип: boolean по умолчанию: false

Делает то же самое, что и yaml_encode(), но включает в вывод тип.

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

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
        {% set array = {
    'a': {
        'c': 'e'
    },
    'b': {
        'd': 'f'
    }
} %}

{{ array|yaml_dump(inline = 0) }}
{# вывод:
   %array% { a: { c: e }, b: { d: f } } #}

{{ array|yaml_dump(inline = 1) }}
{# вывод:
   %array% a: { c: e }
   b: { d: f } #}
    

Аргумент dumpObjects включает сброс объектов PHP:

        1
2
3
4
        // ...
$object = new \stdClass();
$object->foo = 'bar';
// ...
    

        1
2
3
4
5
        {{ object|yaml_dump(dumpObjects = false) }}
{# вывод: %object% null #}

{{ object|yaml_dump(dumpObjects = true) }}
{# вывод: %object% !php/object 'O:8:"stdClass":1:{s:3:"foo";s:3:"bar";}' #}
    

abbr_class

        1
        {{ class|abbr_class }}
    

class: тип: string

Генерирует элемент <abbr> с коротким именем PHP-класса (FQCN будет отображён в оперативной подсказке, когда пользователь наведёт курсор на элемент).

        1
        {{ 'App\\Entity\\Product'|abbr_class }}
    

Приложение выше будет отображено как:

        1
        <abbr title="App\Entity\Product">Product</abbr>
    

abbr_method

        1
        {{ method|abbr_method }}
    

method: тип: string

Генерирует элемент <abbr>, используя синтаксис FQCN::method(). Если method - Closure, то Closureбудет использован вместо этого,а если method не имеет имени класс, то он отображается в виде функции (method()).

        1
        {{ 'App\\Controller\\ProductController::list'|abbr_method }}
    

Пример выше будет отображен как:

        1
        <abbr title="App\Controller\ProductController">ProductController</abbr>::list()
    

format_args

        1
        {{ args|format_args }}
    

args: тип: array

Генерирует строку с аргументами и их типами (в рамках элементов <em>).

format_args_as_text

        1
        {{ args|format_args_as_text }}
    

args: тип: array

Приравнивается к фильтру format_args, но без использования HTML-тегов.

file_excerpt

        1
        {{ file|file_excerpt(line, srcContext = 3) }}
    

file: тип: string
line: тип: integer

srcContext (необязательно)

Генерирует выборку файла кода вокруг заданного числа line. Аргумент srcContext определяет итоговое количество строчек для отображения вокруг заданного числа строчки (используйте -1,чтобы отобразить весь файл).

Рассмотрите следующее как содержание file.txt:

        1
2
3
4
5
6
7
8
9
10
11
12
13
        {{ '/path/to/file.txt'|file_excerpt(line = 4, srcContext = 1) }}
{# вывод: #}
<ol start="3">
    <li><a class="anchor" id="line3"></a><code>c</code></li>
    <li class="selected"><a class="anchor" id="line4"></a><code>d</code></li>
    <li><a class="anchor" id="line5"></a><code>e</code></li>
</ol>

{{ '/path/to/file.txt'|file_excerpt(line = 1, srcContext = 0) }}
{# вывод: #}
<ol start="1">
    <li class="selected"><a class="anchor" id="line1"></a><code>a</code></li>
</ol>
    

format_file

        1
        {{ file|format_file(line, text = null) }}
    

file: тип: string
line: тип: integer
text (необязательно): тип: string по умолчанию: null

Генерирует путь файла внутри элемента <a>. Если пусть находится внутри корневого каталога ядра, то путь корневого каталога ядра заменяется на kernel.root_dir (отображая полный путь в оперативной подсказке при наведении курсора).

        1
2
3
4
5
6
7
8
9
10
11
        {{ '/path/to/file.txt'|format_file(line = 1, text = "my_text") }}
{# вывод: #}
<a href="/path/to/file.txt#L1"
    title="Click to open this file" class="file_link">my_text at line 1
</a>

{{ "/path/to/file.txt"|format_file(line = 3) }}
{# вывод: #}
<a href="/path/to/file.txt&amp;line=3"
    title="Click to open this file" class="file_link">/path/to/file.txt at line 3
</a>
    

Tip

Если вы установите опцию framework.ide , сгенерированные ссылки изменятся, чтобы открывать файл в этом IDE/редакторе. Например, при использовании PhpStorm, ссылка <a href="/path/to/file.txt&line=3" станет <a href="phpstorm://open?file=/path/to/file.txt&line=3".

format_file_from_text

        1
        {{ text|format_file_from_text }}
    

text: тип: string

Использует format_file, чтобы улусшить вывод ошибок PHP по умолчанию.

file_link

        1
        {{ file|file_link(line) }}
    

file: тип: string
line: тип: integer

Генерирует ссылку на предоставленный файл и на номер строки, используя предварительно сконфигурированную схему.

        1
2
        {{ 'path/to/file/file.txt'|file_link(line = 3) }}
{# вывод: file://path/to/file/file.txt#L3 #}
    

file_relative

        1
        {{ file|file_relative }}
    

file: тип: string

Преобразует заданный абсолютный путь файла в новый путь файла относительный к корневому каталогу проекта:

        1
2
        {{ '/var/www/blog/templates/admin/index.html.twig'|file_relative }}
{# если dir корня проекта - '/var/www/blog/', возвращает 'templates/admin/index.html.twig' #}
    

Если заданный путь файла находится вне каталога проекта, будет возвращено значение null.

serialize

        1
        {{ object|serialize(format = 'json', context = []) }}
    

object: тип: mixed
format (необязательно): тип: string
context (необязательно): тип: array

Принимает любые данные, которые можно сериализовать с помощью компонента Сериализатор и возвращает сериализованную строку в указанном format.

Например:

        1
2
3
4
        $object = new \stdClass();
$object->foo = 'bar';
$object->content = [];
$object->createdAt = new \DateTime('2024-11-30');
    

        1
2
3
4
5
        {{ object|serialize(format = 'json', context = {
    'datetime_format': 'D, Y-m-d',
    'empty_array_as_object': true,
}) }}
{# вывод: {"foo":"bar","content":{},"createdAt":"Sat, 2024-11-30"} #}
    

emojify

7.1

Фильтр emojify был представлен в Symfony 7.1.

        1
        {{ text|emojify(catalog = null) }}
    

text

тип: string

catalog (необязательно)

тип: string | null

Набор эмодзи, используемый для создания текстового представления (слак, github, gitlab и т.д.)

Он преобразует текстовое представление эмодзи (например, :wave:) в реальный эмодзи (👋):

        1
2
3
        {{ ':+1:'|emojify }}                 {# отображает: 👍 #}
{{ ':+1:'|emojify('github') }}       {# отображает: 👍 #}
{{ ':thumbsup:'|emojify('gitlab') }} {# отображает: 👍 #}
    

Устанавливает источники так, чтобы переопределять тему формы для заданного экземпляра просмотра формы. Вы можете использовать _self в качестве источников, чтобы установить его в качестве текущего источника. Больше информации в Как настроить отображение формы.

trans

        1
        {% trans with vars from domain into locale %}{% endtrans %}
    

vars (необязательно): тип: array по умолчанию: []
domain (необязательно): тип: string по умолчанию: string
locale (необязательно): тип: string по умолчанию: string

Отображает перевод содержимого. Больше информации в .

trans_default_domain

        1
        {% trans_default_domain domain %}
    

domain: тип: string

Устанавливает домен по умолчанию в текущем щаблоне.

stopwatch

        1
        {% stopwatch 'name' %}...{% endstopwatch %}
    

Засечёт время прогона кода внутри себя и отобразит это во временной шкале WebProfilerBundle.

Тесты

Доступны следующие тесты, связанные с Формами Symfony. Они разъясняются в статье о пользовательской настройке отображения форм:

selectedchoice()
rootform()

Глобальные переменные

app

Переменная app доступна везде и предоставляет вам доступ ко многим часто необходимым объектам и значениям. Яляется экземпляром GlobalVariables.