Справочник конфигурации фреймворка (FrameworkBundle)
Дата обновления перевода 2024-07-25
Справочник конфигурации фреймворка (FrameworkBundle)
FrameworkBundle определяет конфигурацию главного фреймворка, от сессий и
переводов, до форм, валидации, маршрутизации и прочего. Все эти опции
конфигурируются под ключом framework
в вашей конфигурации приложения.
1 2 3 4 5
# отображает значения конфигурации по умолчанию, определённые Symfony
$ php app/console config:dump framework
# отображает актуальные значения конфигурации, используемые вашим приложением
$ php app/console debug:config framework
Note
При использовании XML, вы должны увидеть пространство имён
http://symfony.com/schema/dic/symfony
и связанная XSD
cхема доступна тут: http://symfony.com/schema/dic/symfony/symfony-1.0.xsd
Конфигурация
secret
тип: string
обязательно
Это строка, которая должна быть уникальна в вашем приложении, и часто используется, что добавить больше энтропии в операции, связанные с безопасностью. Её значение жолжно быть набором знаков, цифр и символов, выбранных хаотично, а рекомендуемая длина составляет примерно 32 знака.
На практике, Symfony использует это значение для шифроваия cookies, используемых в функциональности "запомнить меня" и для создания подписанных URI при использовании ESI (Включений боковой стороны) . Поэтому вам нужно относиться к этому значению, словно оно является чувствительной информацией безопасности, и никогда не делать его публичным
Эта опция становится параметром сервис-контейнера под названием kernel.secret
,
который вы можете использовать тогда, когда приложению нужна случайная постоянная
строка для добавления большей энтропии.
Как и с любым другим параметром, относящимся к безопасности, хорошей практикой считается изменение этого значения время от времени. Однако, помните, что изменение этого значение инвалидирует все подписанные URI и cookies "Запомнить меня". Поэтому, после изменения этого значения, вам нужно повторно сгенерировать кеш приложения и вывести из системы всех пользователей приложения.
handle_all_throwables
тип: boolean
по умолчанию: false
Если установлена как true
, ядро Symfony поймает все исключения \Throwable
,
вызванные приложением, и превратит их в HTTP-ответы.
http_cache
enabled
тип: boolean
по умолчанию: false
debug
тип: boolean
по умолчанию: %kernel.debug%
Если true, вызваются исключения, когда что-то идёт не так. В обратном случае, кеш будет пробовать продолжать работу и предоставлять значимый ответ.
trace_level
тип: string
возможные значения: 'none'
, 'short'
или 'full'
Длч 'short', краткий след основного запроса будет добавлен как HTTP-заголовок. 'full' добавит следы всех запросов (включая подзапросы ESI) (по умолчанию: 'full', если в режиме отладки; 'none' - в других случаях).
trace_header
тип: string
Имя заголовка, который нужно использовать для следов (по умолчанию: X-Symfony-Cache).
default_ttl
тип: integer
Количество секунд, в течение которых запись кеша должна считаться свежей, если не было предоставлено ясной информации о свежести в ответе. Ясные Cache-Control или заголовки Expires переопределяют это значение (по умолчанию: 0).
private_headers
тип: array
Набор заголовоков запроса, которые вызывают "приватное" поведение контроля кеша в ответах, которые ясно не указывают, является ответ приватным или публичным, через директиву Cache-Control (по умолчанию: Authorization и Cookie).
skip_response_headers
тип: array
по умолчанию: Set-Cookie
Набор заголовков ответа, которые никогда не будут кешироваться, даже если ответ является кешируемым и пўбличным.
allow_reload
тип: string
Указывает, может ли клиент форсировать перезагрузку кеша, включив директиву
Cache-Control "no-cache" в запрос. Установите как true
для соответствия
RFC 2616 (по умолчанию: false).
allow_revalidate
тип: string
Указывает, может ли клиент форсировать повторную валидацию кеша, включив директиву
Cache-Control "max-age=0" в запрос. Установите как true
для соответствия RFC 2616
(по умолчанию: false)
stale_while_revalidate
тип: integer
Указывает количество секунд по умолчанию (гранулярность - секунда, так как точность TTL ответа - секунда), во время которого кеш может немедленно вернуть несвежий ответ во время фоновой повторной валидации (по умолчанию: 2). Эта установка переопределяется расширением HTTP Cache-Control stale-while-revalidate (см. RFC 5861).
stale_if_error
тип: integer
Указывает количество секунд по умолчанию (гранулярность - секунда), во время которого кеш может выдать несвежий ответ в случае ошибки (по умолчанию: 60). Эта установка переопределяется расширением HTTP Cache-Control the stale-if-error (см. 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(); // <-- add this line
$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, использованием
&
и >
, в качестве разделителей от-гостя-к-хостингуs:
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
Путь файла центра сертификации, который содержит один или более сертификатов, используемых для верификации сертификатов других серверов.
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
Идентификатор сервиса ограничителя скорости, используемого для ограничения количества 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
Порт для http-запросов (используется при сопоставлении схемы).
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
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
| null
по умолчанию: null
Если framework.session.save_path
не установлен, то по умолчанию значение этой опции
является null
, что означает использование обработчика сессии, сконфигурированного в
php.ini. Если опция framework.session.save_path
установлена, то Symfony сохраняет
сессии, используя родной файловый обработчик сессий.
Можно хранить сессии в базе данных , а также сконфигурировать обработчик сессий с помощью 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
Указывается имя cookie сессии. По умолчанию будет использоваться имя cookie,
определённое в php.ini
с директивой session.name
.
cookie_lifetime
тип: integer
по умолчанию: null
Определяет жизненный цикл сессии в секундах. Значение по умолчанию, null
,
означает, что будет использовано значение session.cookie_lifetime
из
php.ini
. Установка этого значения, как 0
, означает, что cookie валиден
в течение длительности сессии браузера.
cookie_path
тип: string
по умолчанию: /
Определяет путь для установки в cookie сессии. По умолчанию будет использоваться
/
.
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
cookie_domain
тип: string
по умолчанию: (пустая строка) ''
Определяет домен для установки в cookie сессии. По умолчанию пустой, что означает, что имя хоста сервера, сгенерировавшего cookie в соответствии со спецификацией cookie.
cookie_samesite
тип: 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
).
cookie_secure
тип: boolean
или auto
по умолчанию: auto
Определяет, должны ли куки отправляться только по защищённым связям. В
дополнение к true
и false
, имеется специальное значение 'auto'
,
которое означает true
для HTTPS-запросов, и false
для HTTP-запросов.
cookie_httponly
тип: boolean
по умолчанию: true
Определяет, должны ли cookie быть доступны только через HTTP-протокол. Это означает, что cookie не будут доступны скриптовым языкам, вроде JavaScript. Эта установка может эффективно помочь снизить случаи кражи личности через XSS-атаки.
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
.
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
, в зависимости от вашей установки
Включать поддержку валидации, или нет.
Эта опция будет автоматически установлена, как 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.
Вы можете изучить конструкторы контекста сериализатора , чтобы узнать о доступных настройках.
php_errors
log
тип: boolean|int
по умолчанию: %kernel.debug%
Использовать логгер приложения вместо PHP-логгера для логирования PHP-ошибок. Когда используется значение целого числа, оно также устанавливает уровень логов. Эти значения целых чисел должны быть такими же, как используются в error_reporting PHP option.
Эта опция также принимает отображнение 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
.
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
default: true
Включать поддержку блокировки или нет. Эта настйрока автоматически установлена,
как true
, если сконфигурирована одна из дочерних настроейк.
resources
тип: array
Список хранилищ блокировок, которые должны быть созданы расширением фреймворка.
1 2 3
# config/packages/lock.yaml
framework:
lock: '%env(LOCK_DSN)%'
See also
Чтобы узнать больше, см. Многопоточная работа с блокировками.
semaphore
тип: string
| array
Адаптер семафора по умолчанию. DSN хранилища также разрешены.
enabled
тип: boolean
по умолчанию: true
Включать ли поддержку семфоров. Эта установка автоматически имеет значение
true
, если не сконфигурирована хоть одна из дочерних настроек.
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-формате)
- это имя заголовка, а значение - значение заголовка.
See also
Чтобы узнать больше, см. Глобальная конфигурация электронных писем
messenger
enabled
тип: boolean
по умолчанию: true
Включать ли Messenger.
See also
Чтобы узнать больше, смотрите документацию компонента Messenger.
web_link
enabled
тип: boolean
по умолчанию: true
или false
, в зависимости от вашей установки
Добавляет к ответу HTTP-заголовок Link.
webhook
Опция webhook
(и ее дочерние опции) используется для конфигурации веб-хуков,
определенных в вашем приложении. Подробнее об опциях читайте в Документации по веб-хукам.
workflows
тип: array
Список рабочих процессов, которые должны быть созданы расширением фреймворка:
1 2 3 4 5
# config/packages/workflow.yaml
framework:
workflows:
my_workflow:
# ...
See also
Также прочтите статью об использовании рабочих процессов в приложениях Symfony.
enabled
тип: boolean
default: false
Включать поддержку рабочих процессов, или нет. Эта настройка автоматически
установлена, как true
, если сконфигурирована одна из дочерних настроек.
name
тип: prototype
Имя рабочего процесса, который вы хотите создать.
initial_marking
тип: string
| array
Либо places
, либо empty
. Если не null, и поддерживаемый объект еще не инициализирован
через рабочий процесс, будет установлено это место.
marking_store
тип: array
Каждое хранилище маркировок может определять любую из этих опций:
property
(тип:string
по умолчанию:marking
)service
(тип:string
)type
(тип:string
разрешенное значение:'method'
)
metadata
тип: array
Метаданные, доступные для конфигурации рабочего процесса. Отметьте, что
places
и transitions
также могут иметь собственную запись metadata
.
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.