Розширення 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: тип: string | ControllerReference
options (не обов'язково): тип: array за замовчуванням: []

Схожа на функцію 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: тип: ControllerReference
absolute (не обов'язково): тип: boolean за замовчуванням: false
strict (не обов'язково): тип: boolean за замовчуванням: true
sign (не обов'язково): тип: boolean за замовчуванням: 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 надає різноманітні реалізації відключення кешу через опції конфігурації assets.version , assets.version_strategy та assets.json_manifest_path .

asset_version

        1
        {{ asset_version(packageName = null) }}
    

path: тип: string
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

Повертає 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) }}
{# output: http://example.org/blog/3 #}

{{ url(name = 'app_blog', parameters = {page: 3}, schemeRelative = true) }}
{# output: //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_path

        1
        {{ impersonation_path(identifier) }}
    

identifier: тип: string

Генерує URL-адресу, за якою ви можете перейти, щоб імперсонувати користувача, ідентифікованого за допомогою аргументу identifier.

impersonation_url

        1
        {{ impersonation_url(identifier) }}
    

identifier: тип: string

Це схоже на функцію impersonation_path, але генерує абсолютні URL замість відносних.

impersonation_exit_path

        1
        {{ impersonation_exit_path(exitTo = null) }}
    

exitTo (не обов'язково): тип: string

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

Якщо імперсонація користувача не проводиться, функція повертає пустий рядок.

impersonation_exit_url

        1
        {{ impersonation_exit_url(exitTo = null) }}
    

exitTo (не обов'язково): тип: string

Схожа на функцію impersonation_exit_path, але генерує абсолютні URL замість відносних.

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

message: тип: string
parameters (не обов'язково): тип: array за замовчуванням: []
domain (не обов'язково): тип: string за замовчуванням: 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

Перетворює технічне ім'я у читане людиною (тобто змінює нижні підкреслення на пробіли, або трансформує текст camelCase, на кшталт helloWorld у hello world, а потім прописує великі літери у рядку).

        1
2
3
4
5
6
        {{ 'dateOfBirth'|humanize }}    {# відображає: Date of birth #}
{{ 'DateOfBirth'|humanize }}    {# відображає: Date of birth #}
{{ 'date-of-birth'|humanize }}  {# відображає: Date-of-birth #}
{{ 'date_of_birth'|humanize }}  {# відображає: Date of birth #}
{{ 'date of birth'|humanize }}  {# відображає: Date of birth #}
{{ 'Date Of Birth'|humanize }}  {# відображає: 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 (не обов'язково): тип: 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 (optional)

тип: string | null

Набір емодзі, що використовується для генерації текстового представлення (lack,
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.