Довідник конфігурації фреймворку (FrameworkBundle)

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

Довідник конфігурації фреймворку (FrameworkBundle)

FrameworkBundle визначає конфігурацію головного фреймворку, від сесій та перекладів, до форми, валідації, маршрутизації та ін. Всі ці опції конфігурауються під ключем framework у вашій конфігурації додатку.

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

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

Note

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

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

secret

тип: string обовʼязково

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

На практиці, Symfony використовує це значення для шифрування кукі, використовуваних у функціональності "запамʼятати мене" та для сворення підписаних URI при використанні ESI (Включень крайніх сторін) . Тому вам потрібно відноситися до цього значення наче воно є чутливою інформацією безпеки, і ніколи не робити його публічним.

Ця опція стає параметром сервіс-контейнера під назвою kernel.secret, який ви можете використовувати тоді, коли додатку потрібний довільний постійний рядок для додавання великої ентропії.

Як і з будь-яким іншим параметром, що відноситься до безпеки, гарною практикою вважається зміна цього значення час від часу. Однак, памʼятайте, що зміна цього значення інвалідує всі підписані URI та кукі "Запамʼятати мене". Тому, після зміни цього значення, вам потрібно повторно згенерувати кеш додатку та вивести з системи всіх користувачів додатку.

handle_all_throwables

тип: boolean за замовчуванням: false

Якщо встановлено як true, ядро Symfony спіймає виключення \Throwable, викликані додатком, і перетворить їх на HTTP-відповіді.

Починаючи з Symfony 7.0, значення цієї опції зазамовчуванням буде true.

http_cache

enabled

тип: boolean за замовчуванням: false

debug

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

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

trace_level

тип: string possible values: 'none', 'short' або 'full'

Для "short" стислий слід головного запиту буде додано в якості HTTP-заголовку. 'full' додасть сліди для всіх запитів (включно з підзапитами ESI). (за замовчуванням: 'full' якщо у режмі отладки; 'none' в інших випадках)

trace_header

тип: string

Імʼя заголовку для використання зі слідами. (за замовчуванням: X-Symfony-Cache)

default_ttl

тип: integer

Кількість секунд, протягом якої запис кешу має вважатися свіжим, коли у відповіді не було надано чіткої інформації про свіжість. Чіткі заголовки кеш-контролю або закінчення дії перевизначать це значення. (за замовчуванням: 0)

private_headers

тип: array

Набір заголовків запиту, які викликають "приватну" поведінку кеш-контролю у відповідях, які чітко не встановлюють, чи є відповідь публічною або приватною, через директиву кеш-контролю (за замовчуванням: Авторизація та Кукі)

skip_response_headers

тип: array за замовчуванням: Set-Cookie

Набір заголовків відповіді, які ніколи не будуть кешовані, навіть якщо відповідь може бути кешованою і є публічною.

allow_reload

тип: string

Вказує, чи може клієнт форсувати перезавантаження кешу, додавши директиву кеш-контролю "no-cache" у запиті. Встановіть як true для відповідності RFC 2616. (за замовчуванням: false)

allow_revalidate

тип: string

Вказує, чи може клієнт форсувати ревалідацію кешу, додавши директиву кеш-контролю "max-age=0" у запиті. Встановіть як true для відповідності RFC 2616.
(за замовчуванням: false)

stale_while_revalidate

тип: integer

Вказує кількість секунд за замовчуванням (зернистість - секунда, так як точність Відповіді TTL - секунда) під час якої кеш може негайно повернути застарілу відповідь, поки він фоново проводитиме її ревалідацію (за замовчуванням: 2). Це налаштування перевизначається HTTP-розширенням кеш-контролю stale-while-revalidate (див. RFC 5861).

stale_if_error

тип: integer

Вказує значення секунд за замовчуванням (зернистість - секунда) під час якої кеш може видавати застарілу відповідь, коли сталася помилка (за замовчуванням: 60). Це налаштування перевизначається HTTP-розширенням кеш-контролю the stale-if-error HTTP (див. RFC 5861).

http_method_override

тип: boolean за замовчуванням: (see explanation below)

Визначає, чи використовується параметр запиту _method так, як вимагається HTTP-методом у запитах POST. Якщо опція включена, то метод Request::enableHttpMethodParameterOverride викликається автоматично. Він стає параметром сервіс-контейнера під іменем kernel.http_method_override.

See also

Зміна дії та HTTP-методу форм Symfony.

Caution

Якщо ви використовуєте Зворотний проксі HttpCache з цією опцією, то ядро ігноруватиме параметр _method, що може призвести до помилок.

Щоб виправити це, викличте метод enableHttpMethodParameterOverride() до створення обʼєкта Request:

1
2
3
4
5
6
7
8
// public/index.php

// ...
$kernel = new CacheKernel($kernel);

Request::enableHttpMethodParameterOverride(); // <-- додайте цей рядок
$request = Request::createFromGlobals();
// ...

trust_x_sendfile_type_header

тип: boolean за замовчуванням: false

X-Sendfile - це спеціальний HTTP-заголовок, який повідомляє веб-серверам, що треба замінити зміст відповіді файлом, який визначено у цьому заголовку. Це покращує продуктивністьь, так як файли тепер видаються не вашим додатком, а напряму веб-сервером.

Ця опція конфігурації визначає, чи довіряти заголовку x-sendfile для BinaryFileResponse. Якщо включена, Symfony автоматично викликає метод BinaryFileResponse::trustXSendfileTypeHeader. Він стає параметром сервіс-контейнера за іменем kernel.trust_x_sendfile_type_header.

trusted_headers

Опція trusted_headers необхідна для конфігурації того, якій клієнтській інформації варто довіряти (наприклад, їх хостингу) при запуску Symfony з балансувальником навантаження або зворотним проксі. Див. Як сконфігурувати Symfony, щоб вона працювала за розподільником навантаження або зворотним проксі.

trusted_proxies

Опція trusted_proxies необхідна, щоб отримувати точну інформацію про клієнта (наприклад, його IP-адресу) при запуску Symfony з балансувальником навантаження або зворотним проксі. Див. Як сконфігурувати Symfony, щоб вона працювала за розподільником навантаження або зворотним проксі.

ide

тип: string за замовчуванням: %env(default::SYMFONY_IDE)%

Symfony перетворює шляхи у скиданнях змінних та повідомленнях виключень на посилання, які відкривають ці файли прямо у вашому браузеру. Якщо ви хочете відкрити ці файли у вашому улюбленому інтерфейсі IDE або текстовому редакторі, встановіть цю опцію у будь-яке з наступних значень: phpstorm, sublime, textmate, macvim, emacs і atom.

Note

Опція phpstorm підтримуєтьься PhpStorm в MacOS, Windows вимагає PhpStormProtocol, а Linux вимагає phpstorm-url-handler.

Якщо ви використовуєте інший редактор, то очікуване значення конфігурації - це шаблон URL, що містить заповнювач %f там де очікується шлях файлу, і заповнювач %l для номеру рядку (символи відсотку (%) повинні бути екрановані шляхом їх впровадження, щоб утримати Symfony від їх використання в якості параметрів контейнера).

1
2
3
# config/packages/framework.yaml
framework:
    ide: 'myide://open?url=file://%%f&line=%%l'

Так як кожний розробник використовує різні IDE, рекомендованим способом підключення цього є конфігурація на рівні системи. Спочатку, ви можете визначити цю опцію у змінній середовища SYMFONY_IDE, яку Symfony читає автоматично, якщо не встановлена конфігурація framework.ide.

Інший варіант - встановити опцію xdebug.file_link_format у вашому файлі конфігурації php.ini. Потрібно використовувати такий же формат, як і для опції framework.ide, але без необхідності екранувати знаки відсотку (%),
шляхом їх дублювання:

1
2
3
4
5
// приклад для PhpStorm
xdebug.file_link_format="phpstorm://open?file=%f&line=%l"

// приклад для Sublime
xdebug.file_link_format="subl://open?url=file://%f&line=%l"

Note

Якщо визначені і framework.ide, і xdebug.file_link_format, Symfony використовує значення опції xdebug.file_link_format.

Tip

Установка опції ini xdebug.file_link_format працює навіть якщо
розширення Xdebug не підключене.

Tip

При запуску вашого додатку у контейнері або на віртуальній машині, ви можете сказати Symfony, щоб вона відображувала файли від гостя до хостингу шляхом зміни їх префіксів. Це має бути вказано наприкінці шаблону URL, з використанням & і > в якості розділювачів від-гостя-до-хостингу:

1
2
3
4
5
6
7
// /path/to/guest/.../file will be opened
// as /path/to/host/.../file on the host
// and /var/www/app/ as /projects/my_project/ also
'myide://%%f:%%l&/path/to/guest/>/path/to/host/&/var/www/app/>/projects/my_project/&...'

// example for PhpStorm
'phpstorm://open?file=%%f&line=%%l&/var/www/app/>/projects/my_project/'

test

тип: boolean

Якщо представлене це налаштування конфігурації (а не false), то завантажуються сервіси, що відносяться до тестування вашого додатку (наприклад, test.client). Це налаштування повинно бути присутнів у вашоме середовищі test (зазвичай через config/packages/test/framework.yaml).

See also

Щоб дізнатися більше, див. Тестування.

default_locale

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

Локаль за замовчуванням використовується, якщо не було встановлено параметр маршрутиазції _locale. Він доступний з методом Request::getDefaultLocale.

See also

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

enabled_locales

тип: array за замовчуванням: [] (порожній масив = включити всі локалі)

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

1
2
3
# config/packages/translation.yaml
framework:
    enabled_locales: ['en', 'es']

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

set_content_language_from_locale

тип: boolean за замовчуванням: false

Якщо ця опція встановлена як true, відповідь матиме HTTP-заголовок Content-Language, встановлений з локаллю Request.

set_locale_from_accept_language

тип: boolean за замовчуванням: false

Якщо ця опція встановлена як true, локаль Request буде автоматично встановлена у значення HTTP-заголовку Accept-Language.

Коли передається атрибут запиту _locale, заголовок Accept-Language ігнорується.

disallow_search_engine_index

тип: boolean за замовчуванням: true, якщо увімкнено режим налагодження, false - якщо ні.

Якшо true, Symfony додає HTTP-тег X-Robots-Tag: noindex до всіх відповідей (окрім випадків, коли ваш власний додаток додає цей заголовок, і тоді він не буде змінений). Цей HTTP-заголовок X-Robots-Tag повідомляє пошукови системам не індексувати ваш веб-сайт. Ця опція - міра безпеки на випадок, якщо ви опублікуєте свій сайт у режимі налагодження.

trusted_hosts

тип: array | string за замовчуванням: array()

Було виявлено, що багато різних атак покладаються на протиріччя обробки заголовку Host різним ПО (веб-серверами, зворотними проксі, веб-фреймворками і т.д.). Фактично, кожний раз, коли фреймворк генерує абсолютний URL (при відправленні електронного листа для скидання пароля, наприклад) хост може бути змінений хакером.

See also

Ви можете прочитати Атаки на HTTP-заголовки хосту, щоб дізнатися більше про такий вид атак.

Метод Symfony Request::getHost() може бути вразливим до деяких з таких атак, так як він залежиьт від конфігурації вашого веб-сервера. Простим вирішенням для уникнення таких атак є білий список хотів, на які відповідатиме ваш додаток Symfony. У цьому полягає ціль опції trusted_hosts. Якщо імʼя хосту вхідного запиту не співпадає з жодним зі списку, то додаток не відповідатиме, а користувач отрирмає відповідь 400.

1
2
3
# config/packages/framework.yaml
framework:
    trusted_hosts:  ['^example\.com$', '^example\.org$']

Хости також можуть бути сконфігуровані з використанням регулярних виразів (наприклад, ^(.+\.)?example.com$), що полегшує відповідь на будь-який піддомен.

Крім того, ви також можете встановити довірені хости у фронт-контролері, використовуючи метод Request::setTrustedHosts():

1
2
// public/index.php
Request::setTrustedHosts(['^(.+\.)?example\.com$', '^(.+\.)?example\.org$']);

Значення за замовчуванням для цієї опції - це порожній масив, що означає, що додаток може відповідати на будь-який заданий хост.

See also

Прочитайте більше про це у записі блогу Порад з безпеки.

form

enabled

тип: boolean за замовчуванням: true або false, в залежності від вашого налаштування

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

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

Note

Це автоматично включить валідацію.

See also

Щоб дізнатися більше, див. Форми.

field_name

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

Це імʼя поля, яке вам треба надати полю CSRF-токена ваших форм.

csrf_protection

See also

Щоб дізнатися більше інформації про CSRF-захист, див. Як реалізувати CSRF-захист.

enabled

тип: boolean за замовчуванням: true або false, в залежності від вашого налаштування

Ця опція може бути використана щоб відключити CSRF-захист у всіх формах. Але ви також можете відключити CSRF-захист в індивідуальних формах `.

1
2
3
4
# config/packages/framework.yaml
framework:
    # ...
    csrf_protection: true

Якщо ви використовуєте форми, але хочете уникнути запуску вашої сесії (наприклад, використовуючи форми на сайті лише з API), то csrf_protection повинна бути встановлена як false.

error_controller

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

Цей контролер викликається, коли будь-де у вашому додатку зʼявляється виключення. Контролер за замовчуванням (ErrorController), відображає конкретні шаблони за різних умов помилок (див. Як налаштувати сторінки помилок).

esi

See also

Ви можете прочитати більше про Включення крайніх сторін (ESI) в .

enabled

тип: boolean за замовчуванням: false

Чи включати підтримку ESI у фреймворку.

Ви також можете встановити esi як true, щоб включити її:

1
2
3
# config/packages/framework.yaml
framework:
    esi: true

fragments

See also

Дізнайтеся більше про фрагменти у статті про HTTP-кеш .

enabled

тип: boolean за замовчуванням: false

Чи включати слухач фрагментів. Слухач фрагментів використовується, щоб відображати ESI-фрагменти незалежно від решти сторінки.

Ця установка автоматично має значення true, коли конфігурується одна з дочірних установок.

hinclude_default_template

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

Встановлює зміст, відображуваний під час завантаження фрагменту, або коли відключено JavaScript. Може бути або іменем шаблону, або самим змістом.

See also

Див. Як вбудувати асинхронний зміст за допомогою hinclude.js, щоб дізнатися більше про hinclude.

path

тип: string за замовчуванням: /_fragment'

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

http_client

Коли встановлений компонент HttpClient, HTTP-клієнт доступний як сервіс під назвою http_client або з використанням псевдоніму автомонтування HttpClientInterface.

Цей сервіс може бути сконфігурований з використанням framework.http_client.default_options:

1
2
3
4
5
6
7
8
# config/packages/framework.yaml
framework:
    # ...
    http_client:
        max_host_connections: 10
        default_options:
            headers: { 'X-Powered-By': 'ACME App' }
            max_redirects: 7

Може бути визначено багато попередньо сконфігурованих сервісів HTTP-клієнта, кожний зі своїм іменем сервісу, визначеним у вигляді ключа під scoped_clients. Видимі клієнти наслідують опції за замовчуванням, визначені для сервісу http_client. Ви можете перевизначити ці опції та визначити декілька інших:

1
2
3
4
5
6
7
8
# config/packages/framework.yaml
framework:
    # ...
    http_client:
        scoped_clients:
            my_api.client:
                auth_bearer: secret_bearer_token
                # ...

Опції, визначені для валідних клієнтів, застосовуються лише до URL, що відповідають або їх base_uri, або опції scope, якщо вона визначена. URL, що не співпадають, завжди використовують опції за замовчуванням.

Кожний видимий клієнт також визначає відповідний іменований псевдонім автомонтування. Якщо ви, наприклад, використовуєте Symfony\Contracts\HttpClient\HttpClientInterface $myApiClient в якості типу та імені аргументу, автомонтування впровадить сервіс my_api.client у ваші автоматично змонтовані класи.

Підключивши необовʼязкову конфігурацію retry_failed, сервіс HTTP-клієнта автоматично буде повторно пробувати неуспішні HTTP-запити.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
# config/packages/framework.yaml
framework:
    # ...
    http_client:
        # ...
        default_options:
            retry_failed:
                # retry_strategy: app.custom_strategy
                http_codes:
                    0: ['GET', 'HEAD']   # повторно спробувати помилки мережі, якщо метод запиту GET або HEAD
                    429: true            # повторно спробувати всі відповіді зі статус-кодом 429
                    500: ['GET', 'HEAD']
                max_retries: 2
                delay: 1000
                multiplier: 3
                max_delay: 5000
                jitter: 0.3

        scoped_clients:
            my_api.client:
                # ...
                retry_failed:
                    max_retries: 4

auth_basic

тип: string

Імʼя користувача та пароль, використовувані для створення HTTP-заголовку Authorization, використовуваного в аутентифікації базового HTTP. Значення цієї опції має дотримуватись формату username:password.

auth_bearer

тип: string

Токен, використовуваний для створення HTTP-заголовку Authorization,
використовуваного в аутентифікації HTTP Bearer (також називається аутентифікацією токенів).

auth_ntlm

тип: string

Імʼя користувача та пароль, використовувані для створення HTTP-заголовку Authorization, використовуваного у протоколі аутентифікації Microsoft NTLM. Значення цієї опції має дотримуватись формату username:password. Цей механізм аутентифікації вимагає використання транспорту, заснованого на cURL.

base_uri

тип: string

URI, який зливається у відносні URI, дотримуючись правил, пояснених у стандарті RFC 3986.
Це корисно, коли всі зроблені вами запити мають спільний префікс (наприклад, https://api.github.com/), і ви можете уникнути його додавання до кожного запиту.

Ось деякі розповсюджені приклади того, як на практиці працює злиття base_uri:

bindto

тип: string

Імʼя інтерфейсу мережі, IP-адреса, імʼя хостингу або UNIX-сокет для використання в якості вихідного інтерфейсу мережі.

buffer

тип: boolean | Closure

Буферизація відповіді означає, що ви можете отримувати доступ до його змісту багато разів, не виконуючи запит знову. Буферизація підключається за замовчуванням, коли тип змісту відповіді - text/*, application/json або application/xml.

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

cafile

тип: string

Шлях файлу центру сертифікації, який містить один або більше сертифікатів, використовуваних для верифікації сертифікатів інших серверів.

capath

тип: string

Шлях до каталогу, що містить один або більше файлів центру сертифікації.

ciphers

тип: string

Список імен шифрів, дозволених для зʼєднань TLS. Вони можуть бути розділені двокрапками, комами або пробілами (наприклад, 'RC4-SHA:TLS13-AES-128-GCM-SHA256').

crypto_method

тип: integer

Мінімальна версія TLS, що приймається. Значення має бути однією з констант STREAM_CRYPTO_METHOD_TLSv*_CLIENT, визначених PHP.

delay

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

Початкова затримка у мілісекундах, використовувана для обчислення часу очікування між повторими спробами.

enabled

тип: boolean за замовчуванням: false

Чи підключати підтримку повторних спроб неуспішного HTTP-запиту. Ця установка автоматично має значення "true", якщо сконфігуроване одне з дочірніх налаштувань.

extra

тип: array

Довільні додаткові дані для передачі HTTP-клієнту для подальшого використання. Це може бути особливо корисним при декоруванні існуючого клієнта .

headers

тип: array

Асоційований масив HTTP-заголовків, доданий перед тим як зробити запит. Це значення повинно використовувати формат ['header-name' => 'value0, value1, ...'].

http_codes

тип: array за замовчуванням: DEFAULT_RETRY_STATUS_CODES()

Список HTTP статус-кодів, що викликають повторну спробу запиту.

http_version

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

HTTP-версія для використання, зазвичай '1.1' або '2.0'. Залиште як null, щоб дозволити Symfony обрати найкращу версію автоматично.

jitter

тип: float за замовчуванням: 0.1 (має бути між 0.0 і 1.0)

Ця опція додає деяку рандомність до затримки. Корисно для уникнення відправлення багатьох запитів до серверу в один і той же час. Рандомність обчислюється як затримка * джитер. Наприклад: якщо затримка - 1000ms, а джитер - 0.2, реальна затримка буде числом між 800 і 1200 (1000 +/- 20%).

local_cert

тип: string

Шлях файлу, який містить сертифікат в PEM форматі, використовуваний HTTP- клієнтом, Часто комбінується з опціями local_pk і passphrase.

local_pk

тип: string

Шлях файлу, який містить приватний ключ в PEM форматі сертифікату, визначеного в опції local_cert.

max_delay

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

Максимальна кількість у мілісекундах для очікування між повторними спробами. Використайте 0, щоб не обмежувати тривалість.

max_duration

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

Максимальний час виконання в секундах, який можуть використовувати запит та відповідь. Значення, яке менше ніж або дорівнює 0, означає, що час необмежений.

max_host_connections

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

Визначає максимальну кількість одночасно відкритих зʼєднань з одним хостингом (розглядаючи "хостинг" як еквівалент пари "імʼя хостингу + номер порту"). Це обмеження також застосовується для зʼєднань проксі, де проксі розглядається як хостинг, для якого застосовується дане обмеження.

max_redirects

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

Максимальна кількість перенаправлень, за якими слідувати. Використайте 0, щоб не слідувати жодному перенаправленню.

max_retries

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

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

multiplier

тип: float за замовчуванням: 2

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

no_proxy

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

Список хостингів, розділений комами, які не вимагають досягнення проксі, навіть якщо він сконфігурований; Використайте заповнювач '*', щоб співпадали всі хостинги, та порожній рядок, щоб не співпадав жодний (відключає проксі).

passphrase

тип: string

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

peer_fingerprint

тип: array

При розгляді TLS зʼєднання, сервер відправляє сертифікат, що вказує на його ідентичність. Публічний ключ вилучається з цього сертифікату, і якщо він точно не співпаде з жодним з наданих у цій опції публічних ключів, зʼєднання переривається до відправлення або отримання будь-яких даних.

Значення цієї опції - асоційований масив algorithm => hash (наприклад, ['pin-sha256' => '...']).

proxy

тип: string | null

HTTP-проксі для використання у запитах. Залиште як null, щоб визначати проксі автоматично, засновуючись на конфігурації вашої системи.

query

тип: array

Асоційований масив значень рядку запиту, доданих до URL перед виконанням запиту. Це значення повинно використовувати формат ['parameter-name' => parameter-value, ...].

rate_limiter

тип: string

ID сервісу обмежувача швидкості, який використовується для обмеження кількості HTTP-запитів протягом певного періоду. Сервіс повинен реалізовувати інтерфейс LimiterInterface.

7.1

Опція rate_limiter була представлена в Symfony 7.1.

resolve

тип: array

Список імен хостингів та їх IP-адрес для попереднього наповнення DNS-кешу, що використовується HTTP-клієнтом для того, щоб уникнути пошуку цих хостингів у DNS. Ця опція корисна для покращення безпеки, коли IP перевіряються перед тим як URL передається клієнту, і робить ваші тести простішими.

Значення цієї опції є асоційованим масивом domain => IP address (наприклад, ['symfony.com' => '46.137.106.254', ...]).

retry_strategy

тип: string

Сервіс використовується, щоб вирішити, чи варто робити повторну спробу запиту, та обчислити час очікування між спробами. За замовчуванням використовує екземпляр GenericRetryStrategy, сконфігурований з опціями http_codes, delay, max_delay, multiplier і jitter. Цей клас має реалізовувати RetryStrategyInterface.

scope

тип: string

Лише для видимих клієнтів: регулярний вираз, якому має відповідати URL перед його застосуванням до всіх інших опцій за замовчуванням. За замовчуванням, область виводиться з base_uri.

timeout

тип: float за замовчуванням: залежить від вашої конфігурації PHP

Час в секундах для очікування відповіді. Якщо відповідь буде без стану довше, викликається TransportException. Значення за замовчуванням таке ж, як і значення опції конфігурації PHP default_socket_timeout.

verify_host

тип: boolean за замовчуванням: true

Якщо true, сертифікат, відправлений іншими серверами, верифікується, щоб гарантувати, що їх спільне імʼя співпадає з хостингом, включеним в URL. Зазвичай комбінується з verify_peer, щоб також верифікувати аутентичність сертифікату.

verify_peer

тип: boolean за замовчуванням: true

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

html_sanitizer

Опція html_sanitizer (та її доньки) використовуються для конфігурації користувацьких дезінфекторів HTML. Прочитайте більше про опції у документації HTML Sanitizer .

profiler

enabled

тип: boolean за замовчуванням: false

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

Note

Профілювальник працює незалежно від панелі інструментів веб-розробки, див. конфігурацію WebProfilerBundle, щоб дізнатия, як включати та відключати панель інструментів.

collect

тип: boolean за замовчуванням: true

Ця опція конфігурує те, як поводить себе профілювальник, коли він включений. Якщо встановлена як true, то профілювальник збирає дані для всіх запитів. Якщо ви хочете збирати інформацію лише за одним запитом, то ви можете встановити відмітку collect як false, та активувати збиральники даних вручну:

1
$profiler->enable();

collect_parameter

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

Це вказує імʼя параметру запиту, параметр тіла або атрибут запиту, використані для включення або відключення збору даних профілювальником для кожного запиту. Скомбінуйте її з опцією collect, щоб включати/відключати профілювальник за вимогою:

  • Якщо опція collect встановлена як true, але цей параметр існує у запиті та має будь-яке значення, окрім true, yes, on або 1, дані запиту не будуть збиратися;
  • Якщо опція collect встановлена як false, але цей параметр існує у запиті та має значення true, yes, on або 1, дані запиту будуть збиратися.

only_exceptions

тип: boolean за замовчуванням: false

Коли вона встановлена як true, профілювальник буде включений лише тоді, коли викликається виключення під час обробки запиту.

only_main_requests

тип: boolean за замовчуванням: false

Коли встановлена як true, профілювальник буде включений лище у головних запитах (а не у підзапитах).

dsn

тип: string за замовчуванням: file:%kernel.cache_dir%/profiler'

DSN, де зберігати інформацію профілювання.

collect_serializer_data

тип: boolean за замовчуванням: false

Встановіть цю опцію як true, щоб включити колектор даних серіалізатора та його панель профілювальника. Коли ця опція встановлена як true, всі нормалізатори та шифрувальники декоровані відслідковуваними реалізаціями, які збирають інформацію профілювання про них.

rate_limiter

name

тип: prototype

Імʼя слухача частоти, якого ви хочете створити.

lock_factory

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

Сервіс, використовуваний для створення блокування. Сервіс має бути екземпляром класу LockFactory.

policy

тип: string обовʼязково

Імʼя алгоритму обмежувача частоти, який потрібно використовувати. Наприклад, fixed_window, sliding_window і no_limit. Див. Політика обмежувачів частоти , щоб дізнатися більше.

request

formats

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

Це налаштування використовується для асоціації додаткових форматів запитів (наприклад, html) до одного або більше mime-типів (наприклад, text/html), яка дозволить вам використовувати формат і mime-типи для виклику Request::getFormat($mimeType) або Request::getMimeType($format).

На практиці це важливо, так як Symfony використовує її, щоб автоматично встановлювати заголовок Content-Type у Response (якщо ви не вказуєте його чітко). Якщо ви передасте масив mime-типів, перший буде використано для заголовку.

Щоб сконфігурувати формат jsonp:

1
2
3
4
5
# config/packages/framework.yaml
framework:
    request:
        formats:
            jsonp: 'application/javascript'

router

resource

тип: string обовʼязково

Шлях головного джерела маршрутизації (наприклад, YAML-файл), що містить маршрути та імпорт, який повинен завантажувати маршрутизатор.

type

тип: string

Тип джерела, що натякає завантажувачам про формат. Не потрібно, якщо ви використовуєте маршрутизатори за замовчуванням з очікуваними розширеннями файлів (.xml, .yml або .yaml, .php)

default_uri

тип: string

URI за замовчуванням, використовуваний для генерування URL в контексті поза HTTP (див. Генерування URL в командах ).

http_port

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

Порт для нормальних http-запитів (використовується при співставленні схеми).

https_port

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

Порт для https-запитів (використовується при співставленні схеми).

strict_requirements

тип: mixed за замовчуванням: true

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

Значення може бути наступним:

true
Видати виключення, якщо вимоги не виконані;
false
Відключити виключення, якщо вимоги не виконані, та повернрути замість цього '';
null
Відключити перевірку вимог (тобто, співставляти маршрут навіть якщо вимоги не виконані).

true рекомендовано у середовищі розробки, false або null - краще у виробництві.

utf8

тип: boolean за замовчуванням: false

Коли ця опція встановлена як true, регулярні вирази, використовувані у вимогах параметрів маршруту , будуть запущені з використанням модифікатора utf-8. Це, наприклад, співпадатиме з будь-яким символом UTF-8 при використанні ., замість співвідношення лише з одним байтом.

Якщо набір символів вашого додатку - UTF-8 (як визначено у методі getCharset() вашого ядра), рекомендовано встановити true. Це призведе до того, що не-UTF8 URL будуть генерувати помилки 404.

cache_dir

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

Каталог, де буде кешована інформація маршрутизації. Може бути встановлено як ~ (null), щоб відключити кешування маршрутів.

7.1

Встановлення опції cache_dir є застарілим, починаючи з Symfony 7.1. Маршрути тепер завжди кешуються у каталозі %kernel.build_dir%.

secrets

enabled

тип: boolean за замовчуванням: true

Чи вмикати керування секретами.

decryption_env_var

тип: string за замовчуванням: base64:default::SYMFONY_DECRYPTION_SECRET

Ім'я змінної середовиша, яке містить секрет розшифрування сховища. За замовчуванням, це значення буде декодовано з base64.

local_dotenv_file

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

Шлях до локального файлу .env. Цей файл має містити ключ розшифрування сховища, заданий опцією decryption_env_var.

vault_directory

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

Каталог для зберігання сховища секретів. За замовчуванням, шлях включає в себе значення параметра kernel.runtime_environment .а

session

storage_factory_id

тип: string за замовчуванням: session.storage.factory.native'

ID сервісу, використовуваного для створення SessionStorageInterface, який зберігає сесію. Цей сервіс доступний у додатку Symfony через псевдонім сервісу session.storage.factory. Клас має реалізовувати SessionStorageFactoryInterface. Щоб побачити список всіх доступних сховищ, виконайте:

1
$ php bin/console debug:container session.storage.factory.

handler_id

тип: string за замовчуванням: session.handler.native_file'

Id сервісу, використовуваний для зберігання сесії. Значення за замовчуванням, 'session.handler.native_file', дозволить Symfony управляти сесіями самостійно, використовуючи файли для зберігання метаданих сесій. Встановіть як null, щоб використовувати нативний механізм PHP-сесії. Ви також можете зберігати сесії у базі даних.

Існує можливість зберігати сесії у базі даних , а також налаштувати обробник сесії за допомогою DSN:

1
2
3
4
5
6
7
8
# config/packages/framework.yaml
framework:
    session:
        # декілька можливих прикладів
        handler_id: 'redis://localhost'
        handler_id: '%env(REDIS_URL)%'
        handler_id: '%env(DATABASE_URL)%'
        handler_id: 'file://%kernel.project_dir%/var/sessions'

Note

Ось підтримувані протоколи DSN:

  • file
  • redis
  • rediss (Redis над TLS)
  • memcached (вимагає symfony/cache)
  • pdo_oci (вимагає doctrine/dbal)
  • mssql
  • mysql
  • mysql2
  • pgsql
  • postgres
  • postgresql
  • sqlsrv
  • sqlite
  • sqlite3

name

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

Вказується імʼя кукі сесії. За замовчуванням буде використовуватися імʼя кукі, визначене в php.ini з директивою session.name.

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

Визначає життєвий цикл сесії в секундах. Значення за замовчуванням, null, означає, що буде використано значення session.cookie_lifetime з php.ini. Установка цього значення як 0, означає, що кукі валідний протягом тривалості сесії браузера.

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

Визначає шлях для установки в кукі сесії. За замовчуванням буде використовуватися /.

cache_limiter

тип: string або int за замовчуванням: (порожній рядок)

Якщо встановлено як 0, Symfony не буде встановлювати конкретний заголовок, повʼязаний з кешем, і покладатиметься на метод контролю кешу, сконфігурований в опції PHP.ini session.cache-limiter.

На відміну від інших опцій сесії, cache_limiter встановлена як звичайний параметр контейнера :

1
2
3
4
# config/services.yaml
parameters:
    session.storage.options:
        cache_limiter: 0

Майте на увазі, що якщо ви сконфігуруєте його, вам доведеться встановити інші опції, пов'язані з сесією, як параметри.

тип: string за замовчуванням: (порожній рядок) ''

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

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

Контролює, як відправляються кукі, коли HTTP-запит відбувся не з того ж домену, з яким асоційовані кукі. Установка цієї опції рекомендована для послаблення атак безпеки CSRF.

За замовчуванням, браузери відправляють всі кукі, повʼязані з доменом HTTP-запиту. Це може бути проблемою, наприклад, коли ви відвідуєте форум, і якийсь зловмисний коментар містить посилання на кшталт https://some-bank.com/?send_money_to=attacker&amount=1000. Якщо ви раніше виконали вхід у систему вашого сайту, браузер відправить всі ці кукі під час HTTP-запиту.

Можливі значення цієї опції:

  • null, використовуйте для відключення цього захисту. Така ж поведінка, як і в старіших версіях Symfony.
  • 'none' (або константа Symfony\Component\HttpFoundation\Cookie::SAMESITE_NONE), використовуйте для дозволу відправки кукі, якщо HTTP-запит виходить з іншого домену (раніше це було поведінкою за замовчуванням для null, але у новіших браузерах застосовуватиметься 'lax' , коли заголовок ще не було встановлено).
  • 'strict' (або константа Cookie::SAMESITE_STRICT), використовуйте, щоб ніколи не відправляти ніяких кукі, якщо HTTP-запить не виходить з того ж домену.
  • 'lax' (або константа Cookie::SAMESITE_LAX), використовуйте, щоб дозволити відправку кукі, коли запит виходить з іншого домену, але лише коли користувач свідомо зрробив запит (натиснувши на посилання або відправивши форму з методом GET).

тип: boolean або auto за замовчуванням: auto

Визначає, чи повинні кукі відправлятися лише за захищеними звʼязками. На додаток до true і false, є спеціальне значення 'auto', яке означає true для HTTPS-запитів і false - для HTTP-запитів.

тип: boolean за замовчуванням: true

Визначає, чи мають кукі бути доступними лише через HTTP-протокол. Це означає, що кукі не будуть доступні скриптовим мовам, на кшталт JavaScript. Ця установка може ефективно допомогти знизити випадки крадіжок особистості через XSS-атаки.

gc_divisor

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

Див. gc_probability.

gc_probability

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

Визначає вірогідніст того, що процес збирання сміття (ЗС) буде розпочато при ініціалізації кожної сесії. Вірогідність обчислюється з використанням gc_probability / gc_divisor, наприклад, 1/100 означає, що є 1% шансу, що ЗС проводитиметься у кожному запиті.

gc_maxlifetime

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

Визначає кількість секунд, після якої дані розглядатимуться як "сміття" і потенційно будуть прибрані. ЗС може відбутися під час початку сесії та залежить від gc_divisor і gc_probability.

sid_length

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

Визначає довжину ID рядку сесії, яка може бути цілим числом між 22 та 256 (включно), де 32 - рекомендоване значення. Довші ID cесії складніше вгадувати.

Ця опція повʼязана з PHP-опцією session.sid_length.

sid_bits_per_character

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

Визначає кількість бітів у зашифрованому ID символі сесії. Можливі значення - 4 (0-9, a-f), 5 (0-9, a-v), і 6 (0-9, a-z, A-Z, "-", ","). Більша кількість бітів призводить до міцнішого ID сесії. 5 є рекомендованим значенням для більшості середовищ.

Ця опція повʼязана з PHP-опцією session.sid_bits_per_character.

save_path

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

Визначає аргумент, що передається обробнику зберігання. Якщо ви оберете обробник файлів за замовчуванням, то це шлях, за яким створюються файли сесії. Щоб дізнатися більше, див. Конфигурация каталога, где сохраняются файлы сессии.

Ви також можете встановити це значення як save_path вашого php.ini, встановивши значення як null:

1
2
3
4
# config/packages/framework.yaml
framework:
    session:
        save_path: ~

metadata_update_threshold

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

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

enabled

тип: boolean за замовчуванням: true

Чи включати підтримку сесії у фреймворку.

1
2
3
4
# config/packages/framework.yaml
framework:
    session:
        enabled: true

use_cookies

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

Вказує, чи зберігається ID сесії на клієнтській стороні з використанням кукі, чи ні. За замовчуванням використовує значення, визначене в php.ini з директивою session.use_cookies.

ssi

enabled

тип: boolean за замовчуванням: false

Чи вмикати підтримку SSI у вашому додатку.

assets

base_path

тип: string

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

1
2
3
4
5
# config/packages/framework.yaml
framework:
    # ...
    assets:
        base_path: '/images'

base_urls

тип: array

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

1
2
3
4
5
6
# config/packages/framework.yaml
framework:
    # ...
    assets:
        base_urls:
            - 'http://cdn.example.com/'

packages

Ви можете групувати ресурси в пакети, щоб вказати для них різні базові URL:

1
2
3
4
5
6
7
# config/packages/framework.yaml
framework:
    # ...
    assets:
        packages:
            avatars:
                base_urls: 'http://static_cdn.example.com/avatars'

Тепер ви можете використати пакет avatars у ваших шаблонах:

1
<img src="{{ asset('...', 'avatars') }}">

Кожний пакет може сконфігурувати наступні опції:

  • base_path
  • base_urls
  • version_strategy
  • version
  • version_format
  • json_manifest_path
  • strict_mode

version

тип: string

Ця опція використовується для анулювання кешу у ресурсах, глобально додавши параметр запиту до всіх відображених шляхів ресурсів (наприклад, /images/logo.png?v2). Це застосовується лише до ресурсів, відображених через функцію Twig asset() (або PHP еквівалентом).

Наприклад, уявіть, що у вас є наступне:

1
<img src="{{ asset('images/logo.png') }}" alt="Symfony!"/>

За замовчуванням, це відобразить шлях до вашого зображення так: /images/logo.png. Тепер, активуйте опцію version:

1
2
3
4
5
# config/packages/framework.yaml
framework:
    # ...
    assets:
        version: 'v2'

Тепер той же ресурс відображатиметься як /images/logo.png?v2. Якщо ви використовуєте цю функцію, ви повинні вручну збільшити значення version до кожного розгортування, щоб параметри запитів змінювалися.

Ви також можете контролювати те, як працює рядок запитів, через опцію version_format.

Note

Цей параметр не може бути встановлений одночасно з version_strategy або json_manifest_path.

Tip

Як і з усіма налаштуваннями, ви можете використовувати параметр в якості значення для version. Це полегшує збільшення кешу при кожному розгортуванні.

version_format

тип: string за замовчуванням: %%s?%%s

Визначає схему sprintf, яка буде використана опцією version, щоб побудувати шлях ресурсу. За замовчуванням схема додається до версії ресурсу в якості рядку запиту. Наприклад, якщо version_format встановлено як %%s?version=%%s, а version - як 5, то шлях ресурсу буде /images/logo.png?version=5.

Note

Всі знаки відсотку (%) у форматі рядку мають бути подвоєні, щоб екранувати знак. Без екранування, значення можуть бути помилково сприйняті як .

Tip

Деякі мережі доставки контенту (CDN) не підтримують ануляцію кешу через рядки запиту, так що необхідно впровадження версії у сам шлях файлу. На щастя, version_format не обмежений виробленням версіонованих рядків запиту.

Схема отримує оригінальний шлях ресурсу та версію в якості першого і другого параметрів, відповідно. Так як шлях ресурсу - це один параметр, ви не можете змінити його на місці (наприклад, /images/logo-v5.png); однак, ви можете додати префікс до шляху ресурсу, використовуючи схему version-%%2$s/%%1$s, яка призведе до шляху у вигляді version-5/images/logo.png.

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

version_strategy

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

Id сервісу стратегії версій ресурсів застосовується до ресурсів. Ця опція може бути встановлена глобально для всіх ресурсів, та індивідуально для кожного пакету ресурсів:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
# config/packages/framework.yaml
framework:
     assets:
         # ця стратегія затосовується до кожного ресурсу (включно з пакетами)
         version_strategy: 'app.asset.my_versioning_strategy'
         packages:
             foo_package:
                 # цей пакет видаляє все версіонування (його ресурси не будуть версіоновані)
                 version: ~
             bar_package:
                 # цей пакет використовує свою власну стратегію (стратегія за замовчуванням ігнорується)
                 version_strategy: 'app.asset.another_version_strategy'
             baz_package:
                 # цей пакет наслідує стратегію за замовчуванням
                 base_path: '/images'

Note

Цей параметр не може бути встановлений одночасно з version або json_manifest_path.

json_manifest_path

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

Шлях файлу до файлу manifest.json, що містить асоціативний масив імен ресурсів та їх відповідні скомпільовані імена. Розповсюджена техніка скидання кешу, використовуючи файл "manifest", працює шляхом виписування ресурсів з префіксом "hash" в їх іменах файлів (наприклад, main.ae433f1cb.css) під час процесу фронтенд компіляції.

Tip

Symfony Webpack Encore підтримує виведення хешованих ресурсів . Більш того, це можна інкорпорувати у багато інших робочих процесів, включно з Webpack та Gulp, використовуючи webpack-manifest-plugin і gulp-rev, відповідно.

Ця опція може бути встановлена глобально для всіх ресурсів та індивідуально для кожного пакету ресурсів:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
# config/packages/framework.yaml
framework:
    assets:
        # цей маніфест застосовується до кожного ресурсу (включно з пакетами)
        json_manifest_path: "%kernel.project_dir%/public/build/manifest.json"
        # ви також можете використати абсолютні URL, і Symfony завантажить їх автоматично
        # json_manifest_path: 'https://cdn.example.com/manifest.json'
        packages:
            foo_package:
                # цей пакет використовує власний маніфест (файл за замовчуванням ігнорується)
                json_manifest_path: "%kernel.project_dir%/public/build/a_different_manifest.json"
            bar_package:
                # цей пакет використовує глобальний манфіест (файл за замовчуванням використовується)
                base_path: '/images'

Note

Цей параметр не може бути встановлений одночасно з version або version_strategy. Крім того, ця опція не може бути обнулена в масштабах пакету, якщо вказано глобальний файл маніфесту.

Tip

Якщо ви запитаєте ресурс, який не знайдено у файлі manifest.json, буде повернено початковий незмінений шлях ресурсу. Ви можете встановити strict_mode як true, щоб отримати виключення, коли ресурс не знайдено.

Note

Якщо URL встановлена, JSON-маніфест завантажується за кожним запитом, використовуючи http_client.

strict_mode

тип: boolean за замовчуванням: false

Коли включений, жорсткий режим стверджує, що всі запитані ресурси знаходяться у файлі маніфесту. Ця оція корисна для виявлення друкарських помилок або відсутніх ресурсів, рекомендоване значення - %kernel.debug%.

translator

cache_dir

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

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

enabled

тип: boolean за замовчуванням: true або false, в залежності від вашої установки

Чи підключати сервіс translator у сервіс-контейнері.

fallbacks

тип: string|array за замовчуванням: значення default_locale

Ця опція використовується, коли ключ перекладу для поточної локалі не було знайдено.

See also

Щоб дізнатися більше, див. Переклади.

logging

за замовчуванням: true коли ввімкнено режим налагодження, false - коли ні.

Коли true, то запис логів робиться кожний раз, коли перекладач не може знайти переклад для заданого ключа. Логи робляться у каналі translation і на рівні debug для ключів, коли у резервній локалі є переклад, та на рівні warning, якщо немає перекладу для використання.

formatter

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

ID сервісу, використовуваного для форматування повідомлень перекладу. Клас сервісу має реалізовувати MessageFormatterInterface.

paths

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

Ця опція дозволяє визначити масив шляхів, де компонент шукатиме файли перекладу. Чим пізніше буде додано шлях, ти більшу пріоритетність він матиме (переклади з пізніших шляхів перезаписуватимуть ті, що були раніше). Переклади з default_path мають більший пріоритет, ніж переклади з усіх цих шляхів.

default_path

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

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

providers

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

Ця опція включає та конфігурує постачальників перекладів , щоб пушити та пулити ваші переклади з/у стороні сервіси перекладу.

property_access

magic_call

тип: boolean за замовчуванням: false

Коли включена, сервіс property_accessor використовує PHP метод magic __call() , коли викликається його метод getValue().

magic_get

тип: boolean за замовчуванням: true

Коли включена, сервіс property_accessor використовує PHP метод magic __get() , коли викликається його метод getValue().

magic_set

тип: boolean за замовчуванням: true

Коли включена, сервіс property_accessor використовує PHP метод magic __set() , коли викликається його метод setValue().

throw_exception_on_invalid_index

тип: boolean за замовчуванням: false

Коли включена, сервіс property_accessor викликає виключення, коли ви пробуєте отримати доступ до невалідного індексу масиву.

throw_exception_on_invalid_property_path

тип: boolean за замовчуванням: true

Коли включена, сервіс property_accessor викликає виключення, якщо ви намагаєтесь отримати доступ до невалідного шляху властивості обʼєкта.

property_info

enabled

тип: boolean за замовчуванням: true або false, в залежності від вашої установки

validation

auto_mapping

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

Визначає сутності Doctrine, які будуть проаналізовані для додавання до них обмеження автоматичної валідації :

1
2
3
4
5
6
7
framework:
    validation:
        auto_mapping:
            # порожній масив означає, що всі сутності, які належать до цього
            # простору імен, додаватимуть автоматичну валідацію
            'App\Entity\': []
            'Foo\': ['Foo\Some\Entity', 'Foo\Another\Entity']

enabled

тип: boolean за замовчуванням: true або false, в залежності від вашої установки

enabled

тип: boolean за замовчуванням: true або false, в залежності від вашої установки

Підключати підтримку валідації, чи ні.

Ця опція буде автоматично встановлена як true, якщо сконфігуровано одне з дочірніх налаштувань.

enable_attributes

тип: boolean за замовчуванням: true

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

translation_domain

тип: string | false за замовчуванням: validators

Домен перекладів, використовуваний при перекладі повідомлень помилок обмежень валідації. Використайте false, щоб відключити переклади.

not_compromised_password

Обмеження NotCompromisedPassword робить HTTP-запити до публічного API, щоб перевірити, чи був заданий пароль скомпроментований при витоку даних.

enabled

тип: boolean за замовчуванням: true

Якщо ви встановите цю опцію як false, жоден HTTP-запит не буде зроблений, а заданий пароль вважатиметься валідним. Це корисно, коли ви не хочете або не можете робити HTTP-запити, наприклад, у середовищах dev і test, або на серверах безперервної інтеграції.

endpoint

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

За замовчуванням, обмеження NotCompromisedPassword використовує публічний API, наданий haveibeenpwned.com. Ця опція дозволяє визначати іншу, але сумісну, кінцеву точку API, щоб проводити перевірки паролів. Корисно, наприклад, коли додаток Symfony запущений в інтранеті, без публічного доступу до інтернету.

static_method

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

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

password_strength

Обмеження PasswordStrength верифікує відповідність ентропії наданого рядка мінімальному значенню ентропії.

email_validation_mode

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

Встановлює значення за замовчуванням для опції "mode" для валідатора Email .

mapping

paths

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

Ця опція дозволяє визначати масив шляхів з файлами або каталогами, де компонент шукатиме додаткові файли валідації.

1
2
3
4
5
6
# config/packages/framework.yaml
framework:
    validation:
        mapping:
            paths:
                - "%kernel.project_dir%/config/validation/"

annotations

cache

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

Ця опція може бути одним з наступних значень:

php_array
Використовувати PHP-масив, щоб кешувати анотації в памʼяті
file
Використовувати файлову систему для кешування анотацій
none
Відключити кешування анотацій
service id
id сервісу, що посилається на реалізацію Кешу Doctrine

file_cache_dir

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

Каталог для зберігання файлів кешу для анотацій, у випадку, якщо annotations.cache встановлено як 'file'.

debug

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

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

serializer

enabled

тип: boolean за замовчуванням: true або false, в залежності від вашої установки

Включати сервіс serializer у сервіс-контейнері, чи ні.

enable_annotations

тип: boolean за замовчуванням: true

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

See also

Щоб дізнатися більше, див. .

name_converter

тип: string

Конвертер імен для використання. Конвертер імен CamelCaseToSnakeCaseNameConverter може бути включений, використовуючи значення serializer.name_converter.camel_case_to_snake_case.

See also

Щоб дізнатися більше, див. .

circular_reference_handler

тип string

Id сервісу, який використовується як обробник циклічної залежності серіалізатора за замовчуванням. Сервіс має реалізовувати магічний метод __invoke($object).

See also

Щоб дізнатися більше, див. .

mapping

paths

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

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

default_context

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

Мапа з опціями контексту за замовчуванням, яка буде використана з кожним викликом serialize та deserialize. Це може бути використано, наприклад, щоб встановити поведінку шифрування json, шляхом встановлення json_encode_options для json_encode flags bitmask.

Ви можете дослідити будівники контексту serializer , щоб виявити доступні налаштування.

php_errors

log

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

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

Ця опція також приймає відображення PHP-помилок, щоб вести логи рівнів:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
# config/packages/framework.yaml
framework:
    php_errors:
        log:
            '!php/const \E_DEPRECATED': !php/const Psr\Log\LogLevel::ERROR
            '!php/const \E_USER_DEPRECATED': !php/const Psr\Log\LogLevel::ERROR
            '!php/const \E_NOTICE': !php/const Psr\Log\LogLevel::ERROR
            '!php/const \E_USER_NOTICE': !php/const Psr\Log\LogLevel::ERROR
            '!php/const \E_STRICT': !php/const Psr\Log\LogLevel::ERROR
            '!php/const \E_WARNING': !php/const Psr\Log\LogLevel::ERROR
            '!php/const \E_USER_WARNING': !php/const Psr\Log\LogLevel::ERROR
            '!php/const \E_COMPILE_WARNING': !php/const Psr\Log\LogLevel::ERROR
            '!php/const \E_CORE_WARNING': !php/const Psr\Log\LogLevel::ERROR
            '!php/const \E_USER_ERROR': !php/const Psr\Log\LogLevel::CRITICAL
            '!php/const \E_RECOVERABLE_ERROR': !php/const Psr\Log\LogLevel::CRITICAL
            '!php/const \E_COMPILE_ERROR': !php/const Psr\Log\LogLevel::CRITICAL
            '!php/const \E_PARSE': !php/const Psr\Log\LogLevel::CRITICAL
            '!php/const \E_ERROR': !php/const Psr\Log\LogLevel::CRITICAL
            '!php/const \E_CORE_ERROR': !php/const Psr\Log\LogLevel::CRITICAL

throw

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

Викликає PHP-помилки, як екземпляри \ErrorException. Параметр debug.error_handler.throw_at контролює поріг.

cache

app

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

Адаптер кешу, використовуваний сервісом cache.app. FrameworkBundle постачається з декількома адаптерами: cache.adapter.apcu, cache.adapter.system, cache.adapter.filesystem, cache.adapter.psr6, cache.adapter.redis, cache.adapter.memcached, cache.adapter.pdo та cache.adapter.doctrine_dbal.

Також існує спеціальний адаптер під назвою cache.adapter.array, який зберігає зміст памʼяті, використовуючи PHP-масив та використовується для відключення кешування (в основному у середовищі dev).

Tip

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

system

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

Адаптер кешу, використовуваний сервісом cache.system. Він підтримує ті ж адаптери, що доступні для сервісу cache.app.

directory

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

Шлях до каталогу кешу, використовуваний сервісами, що наслідують з адаптера cache.adapter.filesystem (включно зс cache.app).

default_doctrine_provider

тип: string

Імʼя сервісу для використання в якості вашого постачальника Doctrine за замовчуванням. Постачальник доступний в якості сервісу cache.doctrine.

default_psr6_provider

тип: string

Імʼя сервісу для використання в якості вашого постачальника PSR-6 за замовчуванням. Він доступний в якості сервісу cache.psr6.

default_redis_provider

тип: string за замовчуванням: redis://localhost

DSN для використання постачальником Redis. Постачальник доступний в якості сервісу cache.redis.

default_memcached_provider

тип: string за замовчуванням: memcached://localhost

DSN для використання провайдером Memcached. Провайдер доступний в якості сервісу cache.memcached.

default_pdo_provider

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

ID сервісу зʼєднання бази даних, який може бути екземпляром або PDO, або Doctrine DBAL. Постачальник доступний в якості сервісу cache.default_pdo_provider.

pools

тип: array

Список пулів кешу, який має бути створений розширенням фреймворку.

See also

Щоб дізнатися більше про те, як працюють пули, див. пули кешу .

Щоб сконфігурувати пул кешу Redis з циклом життя в 1 годину, зробіть наступне:

1
2
3
4
5
6
7
# config/packages/framework.yaml
framework:
    cache:
        pools:
            cache.mycache:
                adapter: cache.adapter.redis
                default_lifetime: 3600
name

тип: prototype

Імʼя пулу, який ви хочете створити.

Note

Ваше імʼя пулу повинно відрізнятися від cache.app або cache.system.

adapter

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

Сервісне імʼя адаптера для використання. Ви можете вказати один з сервісів за замовчуванням, які дотримуються патерну cache.adapter.[type]. Крім того, ви можете вказати інший пул кешу в якості основного, що змусить цей пул успадкувати налаштування з основного пулу за замовчуванням.

Note

Ваш сервіс ПОВИНЕН реалізовувати інтерфейс Psr\Cache\CacheItemPoolInterface.

public

тип: boolean за замовчуванням: false

Чи повинен ваш сервіс бути публічним.

tags

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

Чи повинен ваш сервіс мати можливість обробляти теги. Також може бути id сервісу іншого пулу кешу, де зберігатимуться теги.

default_lifetime

тип: integer | string

Життєвий цикл ваших обʼєктів кешу за замовчуванням. Задайте значення цілого числа, щоб встановити життєвий цикл в секундах. Значення рядку може бути часовим інтервалом ISO 8601, на кшталт "PT5M", або PHP-виразом дати, яке приймається strtotime(), на кшталт "5 minutes".

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

provider

тип: string

Перезаписати імʼя сервісу за замовчуванням або DSN, відповідно, якщо ви не хочете використовувати те, що сконфігуровано як default_X_provider під cache. Дивіться опис налаштування постачальника за замовчуванням вище, щоб дізнатися, який тип адаптера ви використовуєте, та інформацію про те, як вказати цього постачальника.

clearer

тип: string

Очищувач кешу, використовуваний для очищення вашого PSR-6 кешу.

See also

Щоб дізнатися більше, див. Psr6CacheClearer.

prefix_seed

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

Це значення використовується в якості частини "простору імен", згенерованого для ключів обʼєкта кешу. Розповсюджена практика - використовувати унікальне імʼя додатку (наприклад, symfony.com), так як це запобігає конфліктам іменування при запуску декількох додатків за одним шляхом (на різних серверах), які використовують однаковий бекенд кешу.

Це також корисно при використанні стратегій синього/зеленого запуску і навіть частіще, коли вам потрібно абстрагуватися від справжнього каталогу розгортування (наприклад, при розігріві кешу офлайн).

Note

Опція prefix_seed використовується під час компіляції. Це означає, що будь-яка зміна цього значення після компіляції контейнера не матиме жодного ефекту.

lock

тип: string

Адаптер блокування за замовчуванням. Якщо не визначений, то значення встановлюється як semaphore, якщо доступно, в інших випадках - як flock. DSN також дозволені.

enabled

тип: boolean за замовчуванням: true

Чи включати підтримку блокування. Це налаштування автоматично встановлене як true, якщо сконфігуроване одне з дочірніх налаштувань.

resources

тип: array

Список сховищ блокувань, які повинні бути створені розширенням фреймворку.

1
2
3
# config/packages/lock.yaml
framework:
    lock: '%env(LOCK_DSN)%'

See also

Щоб дізнатися більше, див. Багатопотокова робота з блокуваннями.

name

тип: prototype

Імʼя блокування, яке ви хочете створити.

semaphore

тип: string | array

Адаптер семафору за замовчуванням. DSN сховища також дозволені.

enabled

тип: boolean за замовчуванням: true

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

resources

тип: array

Мапа сховищ семафорів, яка буде створена розширенням фреймворку, з іменем в якості ключа, а DSN - в якості значення:

1
2
3
# config/packages/semaphore.yaml
framework:
    semaphore: '%env(SEMAPHORE_DSN)%'
name

тип: prototype

Імʼя семафору, який ви хочете створити.

mailer

dsn

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

DSN, використовуваний поштовою програмою. Коли може бути використано декілька DSN, краще використайте опцію transports (див. нижче).

transports

тип: array

Список DSN , які можуть бути викоирстані поштовою програмою. Імʼя транспорту - це ключ, а DSN - значення.

message_bus

тип: string за замовчуванням: null або автобус за замовчуванням якщо встановлено компонент Messenger

Ідентифікатор сервісу автобусу повідомлень, який буде використано при використанні компонента Messenger (наприклад, messenger.default_bus).

envelope

sender

тип: string

"Відправник конверта", який використовується як значення MAIL FROM під час SMTP-сесії. Це значення перевизначає будь-якого іншого відправника, встановленого в коді.

recipients

тип: array

"Отримувач конверта", який використовується як значення RCPT TO під час SMTP-сесії. Це значення перевизначає будь-якого іншого отримувача, встановленого в коді.

1
2
3
4
5
6
# config/packages/mailer.yaml
framework:
    mailer:
        dsn: 'smtp://localhost:25'
        envelope:
            recipients: ['admin@symfony.com', 'lead@symfony.com']

headers

тип: array

Заголовки, які треба додати до електронних листів. Ключ (атрибут name в xml-форматі format) - це імʼя заголовку, а значення - значення заголовку.

See also

Щоб дізнатися більше, див. Глобальна конфігурація електронних листів

messenger

enabled

тип: boolean за замовчуванням: true

Чи вмикати Messenger.

See also

Щоб дізнатися більше, дивіться документацію компонента Messenger.

enabled

тип: boolean за замовчуванням: true або false, в залежності від вашої установки

Додає HTTP-заголовок посилання до відповіді.

workflows

тип: array

Список робочих процесів, які будуть створені розширенням фреймворку:

1
2
3
4
5
# config/packages/workflow.yaml
framework:
    workflows:
        my_workflow:
            # ...

See also

Дивіться також статтю про використання робочих процесів у додатках Symfony.

enabled

тип: boolean за замовчуванням: false

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

name

тип: prototype

Імʼя робочого процесу, який ви хочете створити.

audit_trail

тип: boolean

Якщо встановлена як true, буде включено AuditTrailListener.

initial_marking

тип: string | array

Один з places або empty. Якщо не null і підтримуваний обʼєкт ще не ініціалізовано через робочий процес, буде встановлкено це місце.

marking_store

тип: array

Кожне сховище маркування може визначати будь-яку з цих опцій:

  • property (тип: string за замовчуванням: marking)
  • service (тип: string)
  • type (тип: string дозволене значення: 'method')
metadata

тип: array

Метадані, доступні для конфігурації робочого процесу. Відмітьте, що places та transitions також можуть мати власний запис metadata.

places

тип: array

Всі доступні місця (тип: string) для конфігурації робочого процесу.

supports

тип: string | array

FQCN (повністю кваліфіковане імʼя класу) обʼєкта, підтримуваного конфігурацією робочого процесу, або масив FQCN, якщо підтримується багато обʼєктів.

support_strategy

тип: string

transitions

тип: array

Кожне сховище маркування може визначати будь-яку з цих опцій:

  • from (тип: string або array) значення з places, багато значень дозволені як для workflow, так і для state_machine;
  • guard (тип: string) вираз, сумісний з ExpressionLanguage, щоб заблокувати перехід;
  • name (тип: string) імʼя переходу;
  • to (тип: string або array) значення з places, багато значень дозволені лише для workflow.
type

тип: string можливі значення: 'workflow' або 'state_machine'

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

exceptions

тип: array

Визначає рівень логів та HTTP статус-код, застосований до виключень, які співпадають з заданим класом виключень:

1
2
3
4
5
6
# config/packages/exceptions.yaml
framework:
    exceptions:
        Symfony\Component\HttpKernel\Exception\BadRequestHttpException:
            log_level: 'debug'
            status_code: 422

Порядок, в якому ви конфігуруєте виключення, важливий, так як Symfony використовуватиме конфігурацію першого виключення, яке співпадатиме з instanceof:

1
2
3
4
5
6
7
8
9
10
# config/packages/exceptions.yaml
framework:
    exceptions:
        Exception:
            log_level: 'debug'
            status_code: 404
        # Наступна конфігурація ніколи не буде використана, так як \RuntimeException розширює \Exception
        RuntimeException:
            log_level: 'debug'
            status_code: 422

Ви можете мапувати статус-код та набір заголовків до виключення, завдяки атрибуту #[WithHttpStatus] у класі виключення:

1
2
3
4
5
6
7
8
9
10
11
namespace App\Exception;

use Symfony\Component\HttpKernel\Attribute\WithHttpStatus;

#[WithHttpStatus(422, [
   'Retry-After' => 10,
   'X-Custom-Header' => 'header-value',
])]
class CustomException extends \Exception
{
}

Також можливо мапувати рівень логів у користувацькому класі виключення, використовуючи атрибут #[WithLogLevel]:

1
2
3
4
5
6
7
8
9
namespace App\Exception;

use Psr\Log\LogLevel;
use Symfony\Component\HttpKernel\Attribute\WithLogLevel;

#[WithLogLevel(LogLevel::WARNING)]
class CustomException extends \Exception
{
}

Атрибути також можна додавати безпосередньо до інтерфейсів:

1
2
3
4
5
6
7
8
9
10
11
12
namespace App\Exception;

use Symfony\Component\HttpKernel\Attribute\WithHttpStatus;

#[WithHttpStatus(422)]
interface CustomExceptionInterface
{
}

class CustomException extends \Exception implements CustomExceptionInterface
{
}

7.1

Підтримка використання атрибутів #[WithHttpStatus] і #[WithLogLevel] в інтерфейсах була представлена в Symfony 7.1.