Довідник конфігурації Twig (TwigBundle)

Дата оновлення перекладу 2024-05-29

Довідник конфігурації Twig (TwigBundle)

TwigBundle інтегрує бібліотеку Twig у додатки Symfony, щоб відображати шаблони . Всі ці опції конфігуруються під ключем twig у конфігурації вашого додатку.

        1
2
3
4
5
        # відображає значення конфігурації за замовчуванням, визначені Symfony
$ php bin/console config:dump-reference twig

# відображає реальні значення конфігурації, які використовуються вашим додатком
$ php bin/console debug:config twig
    

Note

При використанні XML, ви маєте використовувати простір імен http://symfony.com/schema/dic/twig, а пов'язана XSD-схема доступна тут: https://symfony.com/schema/dic/twig/twig-1.0.xsd

Конфігурація

auto_reload

тип: boolean за замовчуванням: %kernel.debug%

Якщо true, то кожний раз при відображенні шаблону, Symfony спочатку перевіряє, чи змінився початковий код після останньої компіляції. Якщо змінився, то шаблон комплюється знову автоматично.

autoescape_service

тип: string за замовчуванням: null

Починаючи з Twig 1.17, стратегія екранування, застосована за замовчуванням до шаблону, визначається під час компіляції, засновуючись на імені файлу шаблону. Це означає, наприклад, що зміст шаблону *.html.twig екранується для HTML, а зміст *.js.twig - для JavaScript.

Ця опція дозволяє визначити сервіс Symfony, який буде використано, щоб визначити екранування за замовчуванням, застосоване до шаблону.

autoescape_service_method

тип: string за замовчуванням: null

Якщо визначена опція autoescape_service, то ця опція визначає метод, який викликається для визначення екранування за замовчуванням, застосованого до шаблону.

Якщо сервіс, визначений у autoescape_service, є викличним (тобто він визначає магічний метод PHP __invoke()), ви можете опустити цю опцію.

base_template_class

тип: string за замовчуванням: Twig\Template

Шаблони Twig компілюються в PHP-класи до їх використання для відображення змісту. Ця опція визначає базовий клас, з якого розширюються всі класи шаблонів. Використання користувацького базового шаболну не схвалюється, так як це ускладнить зміст вашого додатку.

cache

тип: string | false за замовчуванням: %kernel.cache_dir%/twig

До використання шаблонів Twig для відображення деякого змісту, вони компілюються у звичайний PHP-код. Компіляція - це витратний процес, так що результат кешується у каталог, визначений цією опцією конфігурації.

Встановіть цю опцію як false, щоб відключити компіляцію шаблону Twig. Однак, це не рекомендується; навіть в середовищі dev, так як опція auto_reload гарантує, що змінени кешовані шаблони будуть скомпільовані знову.

charset

тип: string за замовчуванням: %kernel.charset%

Набір символів, який використовується файлами шаблонів. За замовчуванням, це те ж значення, що і параметр контейнера kernel.charset , який за замовчуванням у додатках Symfony встановлений як UTF-8.

date

Ці опції визначають значення за замовчуванням, які використовуються фільтром date для форматування значень дати та часу. Вони корисні для запобігання передачі одних і тих самих аргументів на кожний виклик фільтра date.

format

тип: string за замовчуванням: F j, Y H:i

Формат, який використовується фільтром date для відображення значень, коли не передано ніякого формату в якості аргументу.

internal_format

тип: string за замовчуванням: %d days

Формат, який використовуйється фільтром date для відображення екземплярів DateInterval, коли не передано ніякого формату в якості аргументу.

timezone

тип: string за замовчуванням: (значение, возвращённое date_default_timezone_get())

Часовий пояс, який використовується при форматуванні значень дат з фільтром date, і коли не передано ніякого часового поясу в якості аргументу.

debug

тип: boolean за замовчуванням: '%kernel.debug%'

Якщо true, то скомпільовані шаблони включають в себе метод __toString(), який може бути використаний для відображення їх вузлів.

Ця опція також контролює поведінку утиліт скидання Twig . Якщо ця опція має значення false, функція dump() не виводить жодного змісту.

default_path

тип: string за замовчуванням: %kernel.project_dir%/templates

Шлях до каталогу, де Symfony шукатиме шаблони додатку Twig за замовчуванням. Якщо ви зберігаєте ці шаблони більше ніж у одному каталозі, використайте також опцію paths .

file_name_pattern

тип: string або array string за замовчуванням: []

Деякі додатки зберігають свої фронт-енд ресурси у тому ж каталозі, що і шаблони Twig. Команда lint:twig фільтрує ці файли, щоб залишити тільки ті, які співпадають з патерном імен файлів *.twig.

Однак, команда cache:warmup намагається скомпілювати всі файли, включно з
не-Twig шаблонами (та ігнорує помилки компіляції). Результатом стає зайве споживання ресурів CPU та диску.

У таких випадках, використайте цю опцію, щоб визначити патерн(и) імен файлів для файлів, які є шаблонами Twig (решта файлів буде проігнорована cache:warmup). Значення цієї опції може бути регулярним виразом, глобальним або рядком:

        1
2
3
4
        # config/packages/twig.yaml
twig:
    file_name_pattern: ['*.twig', 'specific_file.html']
    # ...
    

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
        <!-- config/packages/twig.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:twig="http://symfony.com/schema/dic/twig"
    xsi:schemaLocation="http://symfony.com/schema/dic/services
        https://symfony.com/schema/dic/services/services-1.0.xsd
        http://symfony.com/schema/dic/twig https://symfony.com/schema/dic/twig/twig-1.0.xsd">

    <twig:config>
        <twig:file-name-pattern>*.twig</twig:file-name-pattern>
        <twig:file-name-pattern>specific_file.html</twig:file-name-pattern>
        <!-- ... -->
    </twig:config>
</container>
    

        1
2
3
4
5
6
7
8
9
10
11
        // config/packages/twig.php
use Symfony\Config\TwigConfig;

return static function (TwigConfig $twig): void {
    $twig->fileNamePattern([
        '*.twig',
        'specific_file.html',
    ]);

    // ...
};
    

form_themes

тип: array в string за замовчуванням: ['form_div_layout.html.twig']

Визначає одну або більше тему форми, які застосовуються до всіх форм додатку:

        1
2
3
4
        # config/packages/twig.yaml
twig:
    form_themes: ['bootstrap_4_layout.html.twig', 'form/my_theme.html.twig']
    # ...
    

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
        <!-- config/packages/twig.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:twig="http://symfony.com/schema/dic/twig"
    xsi:schemaLocation="http://symfony.com/schema/dic/services
        https://symfony.com/schema/dic/services/services-1.0.xsd
        http://symfony.com/schema/dic/twig https://symfony.com/schema/dic/twig/twig-1.0.xsd">

    <twig:config>
        <twig:form-theme>bootstrap_4_layout.html.twig</twig:form-theme>
        <twig:form-theme>form/my_theme.html.twig</twig:form-theme>
        <!-- ... -->
    </twig:config>
</container>
    

        1
2
3
4
5
6
7
8
9
10
11
        // config/packages/twig.php
use Symfony\Config\TwigConfig;

return static function (TwigConfig $twig): void {
    $twig->formThemes([
        'bootstrap_4_layout.html.twig',
        'form/my_theme.html.twig',
    ]);

    // ...
};
    

Порядок, в якому визначаються теми, важливий, так як кожна тема перевизначає усі попередні. При відображення поля форми, блок якої не визначено в темі форми, Symfony використовує попередні теми до першої.

Ці глобальні теми застосовуються до всіх форм, навіть тих, які використовують тег Twig form_theme , але ви можете віключити глобальні теми для конкретних форм .

globals

тип: array за замовчуванням: []

Визначає глобальні змінні автоматично врповаджені у всі шаблони Twig. Дізнайтеся більше про глобальні змінні Twig.

mailer

html_to_text_converter

тип: string за замовчуванням: ````

Сервіс, що реалізує HtmlToTextConverterInterface, який буде використано для автоматичного створення частини електронного листа з його HTML змісту, якщо не вказано чітко.

number_format

Ці опції визначають значення за замовчуванням, які використовуються фільтром number_format для форматування числових значень. Вони корисні для запобігання передачі одних і тих же аргументів за кожним викликом фільтра number_format.

decimals

тип: integer за замовчуванням: 0

Кількість десяткових знаків, які використовуються для форматування числових значень, коли не передано ніякого числа в якості аргументу фільтра number_format.

decimal_point

тип: string за замовчуванням: .

Символ, який використовується для розділення десяткових знаком від цілої частини числових значень, коли не передано ніякого конкретного символу в якості аргументу до фільтру number_format.

thousands_separator

тип: string за замовчуванням: ,

Символ, який використовується для відокремлення кожної групи тисяч у числових значеннях, коли не передано ніякого конкретного символу в якості аргументу фільтра number_format.

optimizations

тип: integer за замовчуванням: -1

Twig включає в себе розширення під назвою optimizer, яке підключається за замовчуванням у додатках Symfony. Це розширення аналізує шаблони для їх оптимізації при компіляції. Наприклад, якщо ваш шаблон не використовує спеціальну змінну loop всередині тегу for, то це розширення видаляє ініціалізацію невикористаної змінної.

За замовчуванням, ця опція - -1, що означає, що всі оптимзації увімкнено. Встановіть її як 0, щоб відключити всі оптимізації. Ви навіть можете увімкнути або відключити ці оптимізації вибірково, як пояснюється у документації Twig про розширення оптимізатора.

paths

тип: array за замовчуванням: null

Визначає каталоги, де Symfony шукатиме шаблони Twig на додаток до каталогу, визначеному в опції default_path :

        1
2
3
4
5
6
        # config/packages/twig.yaml
twig:
    # ...
    paths:
        'email/default/templates': ~
        'backend/templates': 'admin'
    

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
        <!-- config/packages/twig.xml -->
<container xmlns="http://symfony.com/schema/dic/services"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:twig="http://symfony.com/schema/dic/twig"
    xsi:schemaLocation="http://symfony.com/schema/dic/services
        https://symfony.com/schema/dic/services/services-1.0.xsd
        http://symfony.com/schema/dic/twig https://symfony.com/schema/dic/twig/twig-1.0.xsd">

    <twig:config>
        <!-- ... -->
        <twig:path>email/default/templates</twig:path>
        <twig:path namespace="admin">backend/templates</twig:path>
    </twig:config>
</container>
    

        1
2
3
4
5
6
7
8
9
        // config/packages/twig.php
use Symfony\Config\TwigConfig;

return static function (TwigConfig $twig): void {
    // ...

    $twig->path('email/default/templates', null);
    $twig->path('backend/templates', 'admin');
};
    

Прочитайте більше про каталоги та простори імен шаблонів .

strict_variables

тип: boolean за замовчуванням: %kernel.debug%

Якщо встановлена як true, Symfony відображає виключення кожний раз, коли не існує змінної, атрибуту або методу Twig. Якщо встановлена як false, то ці помилки ігноруються, а неіснуючі значення замінюються на null.