Конфигурация FrameworkBundle ("framework")

FrameworkBundle содержит большую часть "базовой" функциональности фреймворка и может быть сконфигурирован в конфигурации вашего приложения под ключом framework. При использовании XML, вы должны использовать пространство имён http://symfony.com/schema/dic/symfony.

Это включает в себя настройки, относящиеся к сессиям, перевод, формы, валидацию, маршрутизацию и другое.

Tip

XSD-схема доступна здесь: http://symfony.com/schema/dic/symfony/symfony-1.0.xsd.

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

secret

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

Это строка, которая должна быть уникальна в вашем приложении, и часто используется, что добавить больше энтропии в операции, связанные с безопасностью. Её значение жолжно быть набором знаков, цифр и символов, выбранных хаотично, а рекомендуемая длина составляет примерно 32 знака.

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

Эта опция становится параметром сервис-контейнера под названием kernel.secret, который вы можете использовать тогда, когда приложению нужна случайная постоянная строка для добавления большей энтропии.

Как и с любым другим параметром, относящимся к безопасности, хорошей практикой считается изменение этого значения время от времени. Однако, помните, что изменение этого значение инвалидирует все подписанные URI и cookies "Запомнить меня". Поэтому, после изменения этого значения, вам нужно повторно сгенерировать кеш приложения и вывести из системы всех пользователей приложения.

http_method_override

тип: boolean по умолчанию: true

Определяет, использунтся ли параметр запроса _method так, как требуется HTTP-методом в запросах POST. Если опция включена, то метод Request::enableHttpMethodParameterOverride вызывается автоматически. Он становится параметром сервис-контейнера под именем kernel.http_method_override.

Чтобы узнать больше, см. How to Change the Action and Method of a Form.

Caution

Если вы используете Обратный прокси AppCache с этой опцией, то ядро будет игнорировать параметр _method, что может привести к ошибкам.

Чтобы исправить это, вызовите метод enableHttpMethodParameterOverride() до создания объекта Request:

1
2
3
4
5
6
7
8
// web/app.php

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

Request::enableHttpMethodParameterOverride(); // <-- add this line
$request = Request::createFromGlobals();
// ...

trusted_proxies

Опция trusted_proxies была удалена в Symfony 3.3. См. /request/load_balancer_reverse_proxy.

ide

тип: string по умолчанию: null

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

Note

Опция phpstorm поддерживается PhpStorm в MacOS, Windows требует PhpStormProtocol, а Linux требует phpstorm-url-handler.

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

  • YAML
    1
    2
    3
    # app/config/config.yml
    framework:
        ide: 'myide://open?url=file://%%f&line=%%l'
    
  • XML
     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    <!-- app/config/config.xml -->
    <?xml version="1.0" encoding="UTF-8" ?>
    <container xmlns="http://symfony.com/schema/dic/services"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xmlns:framework="http://symfony.com/schema/dic/symfony"
        xsi:schemaLocation="http://symfony.com/schema/dic/services
            http://symfony.com/schema/dic/services/services-1.0.xsd
            http://symfony.com/schema/dic/symfony http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
    
        <framework:config ide="myide://open?url=file://%%f&line=%%l" />
    </container>
    
  • PHP
    1
    2
    3
    4
    // app/config/config.php
    $container->loadFromExtension('framework', array(
        'ide' => 'myide://open?url=file://%%f&line=%%l',
    ));
    

Так как каждый разработчик использует разные IDE, то рекомендованый способ включения этой функции - сконфигурировать её на системном уровне. Это можно сделать установив опцию xdebug.file_link_format в вашем файле конфигурации php.ini. Формат для использования такой же, как и для опции framework.ide, но без необходимости экранирования символов процента (%), удваивая их.

Note

Если определён как framework.ide, так и xdebug.file_link_format, то Symfony использует значение опции framework.ide.

Tip

Установка ini опции xdebug.file_link_format работает даже если расширение Xdebug не включено.

Tip

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

1
2
3
4
// /path/to/guest/.../файл будет открыт
// как /path/to/host/.../файл на хосте
// и /foo/.../file as /bar/.../также файл
'myide://%f:%l&/path/to/guest/>/path/to/host/&/foo/>/bar/&...'

New in version 3.2: Маршруты от гостя к хосту были представлены к Symfony 3.2.

test

тип: boolean

Если представлена эта настройка конфигурации (а не false), то загружаются сервисы, относящиеся к тестированию вашего приложеия (например, test.client). Эта настройка должна присутствовать в вашем окружении test (обычно через app/config/config_test.yml).

Чтобы узнать больше, см. Testing.

default_locale

тип: string по умолчанию: en

Локаль по умолчаию используется, если не был установлен параметр маршрутизации _locale. Он доступен с методом Request::getDefaultLocale.

Вы можете узнать больше информации о локали по умолчанию в Установка локали по умолчанию.

trusted_hosts

тип: array | string по умолчанию: array()

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

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

Метод Symfony Request::getHost() может быть уязвим к некоторым из таких атак, так как он зависит от конфигурации вашего веб-сервера. Простым решением для избежания этих атак является белый список хостов, на которые будето отвечать ваше приложение Symfony. В этом заключается цель опции trusted_hosts. Если имя хоста входящего запроса не совпадает с одним из хостов в списке, то приложение не будет отвечать, а пользователь получить ответ 400.

  • YAML
    1
    2
    3
    # app/config/config.yml
    framework:
        trusted_hosts:  ['example.com', 'example.org']
    
  • XML
     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    14
    15
    <!-- app/config/config.xml -->
    <?xml version="1.0" encoding="UTF-8" ?>
    <container xmlns="http://symfony.com/schema/dic/services"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xmlns:framework="http://symfony.com/schema/dic/symfony"
        xsi:schemaLocation="http://symfony.com/schema/dic/services
            http://symfony.com/schema/dic/services/services-1.0.xsd
            http://symfony.com/schema/dic/symfony http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
    
        <framework:config>
            <framework:trusted-host>example.com</framework:trusted-host>
            <framework:trusted-host>example.org</framework:trusted-host>
            <!-- ... -->
        </framework:config>
    </container>
    
  • PHP
    1
    2
    3
    4
    // app/config/config.php
    $container->loadFromExtension('framework', array(
        'trusted_hosts' => array('example.com', 'example.org'),
    ));
    

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

Кроме того, вы также можете установить доверенные хосты во фронт-контроллере, используя метод Request::setTrustedHosts():

1
2
// web/app.php
Request::setTrustedHosts(array('^(.+\.)?example.com$', '^(.+\.)?example.org$'));

Значение по умолчанию для этой опции - это пустой массив, что означает, что приложение может отвечать на любой заданный хост.

Прочтите больше об этом в записи блога Советов безопасности.

form

enabled

тип: boolean по умолчанию: false

Включать сервисы формы в сервис-контейнере или нет. Если вы не используете формы, установка этой опции, как false может улучшить производительность вашего приложения, так как в контейнер будет загружаться меньше сервисов.

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

Note

Это автоматически включит `валидацию`_.

Чтобы узнать больше, см. Forms.

csrf_protection

Чтобы узнать больше информации о CSRF-защите в формах, см. /form/csrf_protection.

enabled

тип: boolean по умолчанию: true если включена поддержка форм, false - если нет

Эта опция может быть использована, чтобы отключить CSRF-защиту во всех формах. Но вы также можете отключить CSRF-защиту в индивидуальных формах.

Если вы используете формы, но хотите избежать запуска вашей сессии (например, используя формы на сайте только с API), то csrf_protection должна быть установлена, как false.

esi

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

enabled

тип: boolean по умолчанию: false

Включать ли поддержку ESI в фреймворке.

Вы также можете установить esi, как true, чтобы включить её:

  • YAML
    1
    2
    3
    # app/config/config.yml
    framework:
        esi: true
    
  • XML
     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    <!-- app/config/config.xml -->
    <?xml version="1.0" encoding="UTF-8" ?>
    <container xmlns="http://symfony.com/schema/dic/services"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xmlns:framework="http://symfony.com/schema/dic/symfony"
        xsi:schemaLocation="http://symfony.com/schema/dic/services
            http://symfony.com/schema/dic/services/services-1.0.xsd
            http://symfony.com/schema/dic/symfony http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
    
        <framework:config>
            <framework:esi />
        </framework:config>
    </container>
    
  • PHP
    1
    2
    3
    4
    // app/config/config.php
    $container->loadFromExtension('framework', array(
        'esi' => true,
    ));
    

fragments

Узнайте больше о фрагментах в статье об HTTP-кеше.

enabled

тип: boolean по умолчанию: false

Включать ли слушатель фрагментов, или нет. Слушатель фрагментов используется, чтобы отображать ESI-фрагменты независимо от остальной страницы.

Эта установка автоматически имеет значение true, когда конфигурируется одна из дочерних установок.

path

тип: string по умолчанию: '/_fragment'

Префикс пути для фрагментов. Слушатель фрагментов будет выполнен только когда запрос начинается с этого пути.

profiler

enabled

тип: boolean по умолчанию: false

Профилировщик может быть включен путём установки этой опции, как true. Когда вы используете стандартную версию Symfony, профилировщик включается в окружениях dev и test.

Note

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

collect

тип: boolean по умолчанию: true

Эта опция конфигурирует то, как ведёт себя профилироващик, когда он включен. Если установлена, как true, то профилировщик собирает данные для всех запросов (разве что вы не сконфигурируете по-другому, например, пользовательский matcher). Если вы хотите собирать информацию только по запросу, то вы можете установить отметку collect, как false, и активировать сборщики данных вручную:

1
$profiler->enable();

only_exceptions

тип: boolean по умолчанию: false

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

only_master_requests

тип: boolean по умолчанию: false

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

dsn

тип: string по умолчанию: 'file:%kernel.cache_dir%/profiler'

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

См. Switching the Profiler Storage, чтобы узнать больше о хранилище профилировщика.

matcher

Опции сопоставителя конфигурируются, чтобы динамически включать профилировщик. Например, основываясь на ip или путь.

См. How to Use Matchers to Enable the Profiler Conditionally, чтобы узнать больше об использовании сопоставителей для включения и отключения профилировщика.
ip

тип: string

Если установлена, то профилироващик будет включен только когда совпадает текущий IP адрес.

path

тип: string

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

service

тип: string

Эта установко содержит id сервиса пользовательского сопоставителя.

router

resource

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

Путь главного источника маршрутизации (например, YAML-файл), содержащий маршруты и импорт, который должен загружать маршрутизатор.

type

тип: string

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

http_port

тип: integer по умолчанию: 80

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

https_port

тип: integer по умолчанию: 443

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

strict_requirements

тип: mixed по умолчанию: true

Определяет поведение генератора маршрутизации. При генерировании маршрута, который имеет особенные требования, генератор может вести себя по-другому, если использованные параметры не соответствуют этим требованиям.

Значение может быть следующим:

true
Выдать исключение, если требования не выполнены;
false
Отключить исключения, если требования не выполнены и вернуть вместо этого null;
null
Отключить проверку требований (т.е. сопоставлять маршрут даже если требования не выполнены).

true рекомендуется в окружении разработки, а false или null - лучше в производстве.

session

storage_id

тип: string по умолчанию: 'session.storage.native'

Id сервиса, используемый для хранения сессии. Дополнительное имя сервиса session.storage будет установлено в этом id сервиса. Класс должен реализовать SessionStorageInterface.

handler_id

тип: string по умолчанию: 'session.handler.native_file'

Id сервиса, используемый для хранения сессии. Дополнительное имя сервиса session.storage будет установлено в этом id сервиса.

Вы также можете установить null, чтобы по умолчанию использовался обработчик вашей PHP-установки.

Вы можете увидеть пример использования этого в How to Use PdoSessionHandler to Store Sessions in the Database.

name

тип: string по умолчанию: null

Указывается имя cookie сессии. По умолчанию будет использоваться имя cookie, определённое в php.ini с директивой session.name.

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.

save_path

тип: string по умолчанию: %kernel.cache_dir%/sessions

Определяет аргумент, передаваемый обработчику сохранения. Если вы выберете обработчик файлов по умолчанию, то это путь, по которому создаются файлы сессии. Чтобы узнать больше, см Configuring the Directory where Session Files are Saved.

Вы также можете установить это значение, как save_path вашего php.ini, установив значение, как null:

  • YAML
    1
    2
    3
    4
    # app/config/config.yml
    framework:
        session:
            save_path: ~
    
  • XML
     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    <!-- app/config/config.xml -->
    <?xml version="1.0" encoding="UTF-8" ?>
    <container xmlns="http://symfony.com/schema/dic/services"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xmlns:framework="http://symfony.com/schema/dic/symfony"
        xsi:schemaLocation="http://symfony.com/schema/dic/services
            http://symfony.com/schema/dic/services/services-1.0.xsd
            http://symfony.com/schema/dic/symfony http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
    
        <framework:config>
            <framework:session save-path="null" />
        </framework:config>
    </container>
    
  • PHP
    1
    2
    3
    4
    5
    6
    // app/config/config.php
    $container->loadFromExtension('framework', array(
        'session' => array(
            'save_path' => null,
        ),
    ));
    

assets

base_path

тип: string

Эта опция позволяет вам определять базовый путь для использования с ресурсами:

  • YAML
    1
    2
    3
    4
    5
    # app/config/config.yml
    framework:
        # ...
        assets:
            base_path: '/images'
    
  • XML
     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    <!-- app/config/config.xml -->
    <?xml version="1.0" encoding="UTF-8" ?>
    <container xmlns="http://symfony.com/schema/dic/services"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xmlns:framework="http://symfony.com/schema/dic/symfony"
        xsi:schemaLocation="http://symfony.com/schema/dic/services
            http://symfony.com/schema/dic/services/services-1.0.xsd
            http://symfony.com/schema/dic/symfony http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
    
        <framework:config>
            <framework:assets base-path="/images" />
        </framework:config>
    </container>
    
  • PHP
    1
    2
    3
    4
    5
    6
    7
    // app/config/config.php
    $container->loadFromExtension('framework', array(
        // ...
        'assets' => array(
            'base_path' => '/images',
        ),
    ));
    

base_urls

тип: array

Эта опция позволяет вам определять базовые URL для использования с ресурсами. Если предоставлено несколько базовых URL, Symfony будет выбирать из коллекции один каждый раз, когда будет генерировать путь ресурса:

  • YAML
    1
    2
    3
    4
    5
    6
    # app/config/config.yml
    framework:
        # ...
        assets:
            base_urls:
                - 'http://cdn.example.com/'
    
  • XML
     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    <!-- app/config/config.xml -->
    <?xml version="1.0" encoding="UTF-8" ?>
    <container xmlns="http://symfony.com/schema/dic/services"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xmlns:framework="http://symfony.com/schema/dic/symfony"
        xsi:schemaLocation="http://symfony.com/schema/dic/services
            http://symfony.com/schema/dic/services/services-1.0.xsd
            http://symfony.com/schema/dic/symfony http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
    
        <framework:config>
            <framework:assets base-url="http://cdn.example.com/" />
        </framework:config>
    </container>
    
  • PHP
    1
    2
    3
    4
    5
    6
    7
    // app/config/config.php
    $container->loadFromExtension('framework', array(
        // ...
        'assets' => array(
            'base_urls' => array('http://cdn.example.com/'),
        ),
    ));
    

packages

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

  • YAML
    1
    2
    3
    4
    5
    6
    7
    # app/config/config.yml
    framework:
        # ...
        assets:
            packages:
                avatars:
                    base_urls: 'http://static_cdn.example.com/avatars'
    
  • XML
     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    14
    15
    16
    17
    <!-- app/config/config.xml -->
    <?xml version="1.0" encoding="UTF-8" ?>
    <container xmlns="http://symfony.com/schema/dic/services"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xmlns:framework="http://symfony.com/schema/dic/symfony"
        xsi:schemaLocation="http://symfony.com/schema/dic/services
            http://symfony.com/schema/dic/services/services-1.0.xsd
            http://symfony.com/schema/dic/symfony http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
    
        <framework:config>
            <framework:assets>
                <framework:package
                    name="avatars"
                    base-url="http://static_cdn.example.com/avatars" />
            </framework:assets>
        </framework:config>
    </container>
    
  • PHP
     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    // app/config/config.php
    $container->loadFromExtension('framework', array(
        // ...
        'assets' => array(
            'packages' => array(
                'avatars' => array(
                    'base_urls' => 'http://static_cdn.example.com/avatars',
                ),
            ),
        ),
    ));
    

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

  • Twig
    1
    <img src="{{ asset('...', 'avatars') }}">
    
  • PHP
    1
    <img src="<?php echo $view['assets']->getUrl('...', 'avatars') ?>">
    

Каждый пакет может сконфигурировать следующие опции:

version

тип: string

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

Например, представьте, что у вас есть следующее:

  • Twig
    1
    <img src="{{ asset('images/logo.png') }}" alt="Symfony!" />
    
  • PHP
    1
    <img src="<?php echo $view['assets']->getUrl('images/logo.png') ?>" alt="Symfony!" />
    

По умолчанию, это отобразит путь к вашему изображению так: /images/logo.png. Теперь, активируйте опцию version:

  • YAML
    1
    2
    3
    4
    5
    # app/config/config.yml
    framework:
        # ...
        assets:
            version: 'v2'
    
  • XML
     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    <!-- app/config/config.xml -->
    <?xml version="1.0" encoding="UTF-8" ?>
    <container xmlns="http://symfony.com/schema/dic/services"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xmlns:framework="http://symfony.com/schema/dic/symfony"
        xsi:schemaLocation="http://symfony.com/schema/dic/services
            http://symfony.com/schema/dic/services/services-1.0.xsd
            http://symfony.com/schema/dic/symfony http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
    
        <framework:config>
            <framework:assets version="v2" />
        </framework:config>
    </container>
    
  • PHP
    1
    2
    3
    4
    5
    6
    7
    // app/config/config.php
    $container->loadFromExtension('framework', array(
        // ...
        'assets' => array(
            'version' => 'v2',
        ),
    ));
    

Теперь, тот же ресерс будет отображаться, как /images/logo.png?v2. Если вы используете эту функцию, вы должны вручную увеличить значение version до каждого развёртывания, чтобы параметры запросов изменялись.

Вы также можете контролировать то, как работает строка запросов, через опцию version_format.

Note

Этот параметр не может быть установлен одновременно с version_strategy.

Tip

Как и со всеми настройками, вы можете использовать параметр в качестве значения для version. Это облегчает увеличение кеша при каждом развёртывании.

version_format

тип: string по умолчанию: %%s?%%s

Определяет схему sprintf, которая будет использована опцией version, чтобы построить путь ресурса. По умолчанию, схема добавляется к версии ресурса в качестве строки запроса Например, если version_format установлен, как %%s?version=%%s, а version - как 5, то путь ресурса будет /images/logo.png?version=5.

Note

Все знаки процента (%) в формате строки должны быть удвоены, чтобы экранировать знак. Без экранирования, значения могут быть по неострожности восприняты, как Service Parameters.

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 сервиса стратегии версий ресурсов применяется к ресурсам. Эта опция может быть установлена глоабльно для всех ресурсов, и индивидуально для каждого пакета ресурсов:

  • YAML
     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    14
    15
     # app/config/config.yml
    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'
    
  • XML
     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    <!-- app/config/config.xml -->
    <?xml version="1.0" encoding="UTF-8" ?>
    <container xmlns="http://symfony.com/schema/dic/services"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xmlns:framework="http://symfony.com/schema/dic/symfony"
        xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd
            http://symfony.com/schema/dic/symfony http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
    
        <framework:config>
            <framework:assets version-strategy="app.asset.my_versioning_strategy">
                <!-- этот пакет удаляет всё версионирование (его ресурсы не будут версионированы) -->
                <framework:package
                    name="foo_package"
                    version="null" />
                <!-- этот пакет использует свою собственную стратегию (стратегия по умолчанию игнорируется) -->
                <framework:package
                    name="bar_package"
                    version-strategy="app.asset.another_version_strategy" />
                <!-- этот пакет наследует стратегию по умолчанию -->
                <framework:package
                    name="baz_package"
                    base_path="/images" />
            </framework:assets>
        </framework:config>
    </container>
    
  • PHP
     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    // app/config/config.php
    $container->loadFromExtension('framework', array(
        'assets' => array(
            'version_strategy' => 'app.asset.my_versioning_strategy',
            'packages' => array(
                'foo_package' => array(
                    // этот пакет удаляет всё версионирование (его ресурсы не будут версионированы)
                    'version' => null,
                ),
                'bar_package' => array(
                    // этот пакет использует свою собственную стратегию (стратегия по умолчанию игнорируется)
                    'version_strategy' => 'app.asset.another_version_strategy',
                ),
                'baz_package' => array(
                    // этот пакет наследует стратегию по умолчанию
                    'base_path' => '/images',
                ),
            ),
        ),
    ));
    

Note

Этот параметр не может быть установлен однновременно с version.

templating

hinclude_default_template

тип: string по умолчанию: null

Устаналивает содержимое, отображаемое во время загрузки фрагмента, или когда отключен JavaScript. Это может быть либо именем шаблона, либо самим содержимым.

См. How to Embed Asynchronous Content with hinclude.js, чтобы узнать больше о hinclude.

form

resources

тип: string[] по умолчанию: ['FrameworkBundle:Form']

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

Представив, что у вас есть глобальные пользовательские темы в src/WebsiteBundle/Resources/views/Form, вы можете сконфигурировать это так:

  • YAML
    1
    2
    3
    4
    5
    6
    # app/config/config.yml
    framework:
        templating:
            form:
                resources:
                    - 'WebsiteBundle:Form'
    
  • XML
     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    <!-- app/config/config.xml -->
    <?xml version="1.0" encoding="UTF-8" ?>
    <container xmlns="http://symfony.com/schema/dic/services"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xmlns:framework="http://symfony.com/schema/dic/symfony"
        xsi:schemaLocation="http://symfony.com/schema/dic/services
            http://symfony.com/schema/dic/services/services-1.0.xsd
            http://symfony.com/schema/dic/symfony http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
    
        <framework:config>
    
            <framework:templating>
    
                <framework:form>
    
                    <framework:resource>WebsiteBundle:Form</framework:resource>
    
                </framework:form>
    
            </framework:templating>
    
        </framework:config>
    </container>
    
  • PHP
     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    // app/config/config.php
    $container->loadFromExtension('framework', array(
        'templating' => array(
            'form' => array(
                'resources' => array(
                    'WebsiteBundle:Form'
                ),
            ),
        ),
    ));
    

Note

Шаблоны формы по умолчанию из FrameworkBundle:Form всегда будут включены в источники форм.

См. Глобальные темы, чтобы узнать больше.

cache

тип: string

Путь к каталогу кеша для шаблонов. Когда это не установлено, кеширование отключено.

Note

При использовании шаблонизатора Twig, кеширование уже обрабатывается TwigBundle и не должно быть включено для FrameworkBundle.

engines

тип: string[] / string обязательно

Какой движок шаблонизатора использовать. Это может быть либо строкой (когда конфигурируется только один движок), либо массивом движков.

Требуется хотя бы один движок.

loaders

тип: string[]

Массив (или строка при конфигурировании только одного загрузчика) is сервисов для загрузчиков шаблонизатора. Загрузчики шаблонизатора используются для того, чтобы находить и загружать шаблоны из источника (например, файловой системы или БД). Загрузчики шаблонизатора должны реализовывать LoaderInterface.

translator

enabled

тип: boolean по умолчанию: false

Включать сервис translator в сервис-контейнере, или нет.

fallbacks

тип: string|array по умолчанию: array('en')

Эта опция используется, когда ключ перевода для текущей локали не был найден.

Чтобы узнать больше, см. Translations.

logging

по умолчанию: true когда включен режим отладки, false - когда нет.

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

paths

тип: array по умолчанию: []

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

property_access

magic_call

тип: boolean по умолчанию: false

Когда включена, сервис property_accessor использует PHP метод magic __call()? когда вызываетс его метод getValue().

throw_exception_on_invalid_index

тип: boolean по умолчанию: false

Когда включена, сервис property_accessor вызывает исключение, когда вы пробуете получить доступ к невалидному индексу массива.

validation

enabled

тип: boolean по умолчанию: true если включена поддержка форм, false - если нет

Включать поддержку валидации, или нет.

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

cache

тип: string

Сервис, используемый для сохранения метаданных класса в кеше. Сервис должен реализовывать CacheInterface.

Установите эту опцию, как validator.mapping.cache.doctrine.apc, чтобы использовать APC-кеш предоставленный из проекта Doctrine.

enable_annotations

тип: boolean по умолчанию: false

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

translation_domain

тип: string по умолчанию: validators

Домен переводов, используемый при переводе сообщений ошибо ограничений валидации.

strict_email

тип: Boolean по умолчанию: false

Если эта опция включена, валидатором ограничений Email будет использована библиотека egulias/email-validator. В обратном случае, валидатор использует простое регулярное выражение для валидации адресов электронной почты.

mapping

paths

тип: array по умолчанию: []

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

annotations

cache

тип: string по умолчанию: 'file'

Эта опция может быть одним из следующих значений:

file
Использовать файловую систему для кеширования аннотаций
none
Отключить кеширование аннотаций
a service id
id сервиса, ссылающийся на реализацию Кеша Doctrine

file_cache_dir

тип: string по умолчанию: '%kernel.cache_dir%/annotations'

Каталог для хранения файлов кеша для аннотаций, в случае, если annotations.cache установлен, как 'file'.

debug

тип: boolean по умолчанию: %kernel.debug%

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

serializer

enabled

тип: boolean по умолчанию: false

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

cache

тип: string

Сервис, который используется для сохранени метаданных класса в кеше. Сервис должен реализовывать интерфейс Doctrine\Common\Cache\Cache.

Чтобы узнать больше, см. Активация кеша метаданных.

enable_annotations

тип: boolean по умолчанию: false

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

name_converter

тип: string

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

circular_reference_handler

тип string

Id сервиса, который используется как обработчик циклической зависимоти сериализатора по умолчанию. Сервис должен реализовывать волшебный метод __invoke($object).

Чтобы узнать больше, см. Работа с циклическими ссылками.

php_errors

log

New in version 3.2: Опция log была представлена в Symfony 3.2.

тип: boolean по умолчанию: false

Использовать логгер приложения вместо PHP-логгера для логирования PHP-ошибок.

throw

New in version 3.2: Опция throw была представлена Symfony 3.2.

тип: boolean по умолчанию: %kernel.debug%

Вызывает PHP-ошибки, как экземпляры \ErrorException. Параметр debug.error_handler.throw_at контролирует порог.

cache

app

тип: string по умолчанию: cache.adapter.filesystem

Адаптер кеша, используемый сервисом cache.app. FrameworkBundle поставляется с несколькими адаптерами: apcu, doctrine, system, filesystem, psr6 и redis.

Tip

Вначале это может быть тяжело понять, так что, чтобы избежать путаницы, помните, что все пулы проводят одинаковые действия, но на разных носителях, учитывая адаптер, на котором они основываются. Внутренне, пул оборачивает определение адаптера.

system

тип: string по умолчанию: cache.adapter.system

Адаптер кеша, ипользуемый сервисом cache.system.

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.

pools

тип: array

Список пулов кеша, который должен быть создан расширением фреймворка.

Чтобы узнать болше о том, как работают пулы, см. пулы кеша.
name

тип: prototype

Имя пула, который вы хотите создать.

Note

Ваше имя пула должно отличаться от cache.app или cache.system.

adapter

тип: string по умолчанию: cache.app

Имя адаптера для использования. Вы также можете использовать вашу собственную реализацию.

Note

Ваш сервис ДОЛЖЕН реализовывать интерфейс CacheItemPoolInterface

public

тип: boolean по умолчанию: false

Должен ваш сервис быть публичным, или нет.

default_lifetime

тип: integer

Жизненный цикл ваших объектов кеша в секундах по умолчанию.

provider

тип: string

Имя сервиса для использования в качестве провайдера, когда это требуется указанному адаптеру.

clearer

тип: string

Очиститель кеша, используемый для очистки вашего PSR-6 кеша.

Чтобы узнать больше, см. Psr6CacheClearer.

prefix_seed

New in version 3.2: Опция prefix_seed была представлена в Symfony 3.2.

тип: string по умолчанию: null

Если определено, то это значеиие используется в качестве части "пространства имён", сгенерированного для ключей объектов кеша. Частая практика - использовать уникальное имя приложения (например, symfony.com), так как это предотвращает конфликты именования при развёртывании нескольких приложений по одному пути (на разных серверах), которые используют один бэк-энд кеша.

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

Полная конфигурация по умолчанию

  • YAML
      1
      2
      3
      4
      5
      6
      7
      8
      9
     10
     11
     12
     13
     14
     15
     16
     17
     18
     19
     20
     21
     22
     23
     24
     25
     26
     27
     28
     29
     30
     31
     32
     33
     34
     35
     36
     37
     38
     39
     40
     41
     42
     43
     44
     45
     46
     47
     48
     49
     50
     51
     52
     53
     54
     55
     56
     57
     58
     59
     60
     61
     62
     63
     64
     65
     66
     67
     68
     69
     70
     71
     72
     73
     74
     75
     76
     77
     78
     79
     80
     81
     82
     83
     84
     85
     86
     87
     88
     89
     90
     91
     92
     93
     94
     95
     96
     97
     98
     99
    100
    101
    102
    103
    104
    105
    106
    107
    108
    109
    110
    111
    112
    113
    114
    115
    116
    117
    118
    119
    120
    121
    122
    123
    124
    125
    126
    127
    128
    129
    130
    131
    132
    133
    134
    135
    136
    137
    138
    139
    140
    141
    142
    143
    144
    145
    146
    147
    148
    149
    150
    151
    152
    153
    framework:
        secret:               ~
        http_method_override: true
        trusted_proxies:      []
        ide:                  ~
        test:                 ~
        default_locale:       en
    
        csrf_protection:
            enabled:              false
    
        # конфигурация формы
        form:
            enabled:              false
            csrf_protection:
                enabled:          true
                field_name:       ~
    
        # конфигурация esi
        esi:
            enabled:              false
    
        # конфигурация фрагментов
        fragments:
            enabled:              false
            path:                 /_fragment
    
        # конфигурация профилировщика
        profiler:
            enabled:              false
            collect:              true
            only_exceptions:      false
            only_master_requests: false
            dsn:                  file:%kernel.cache_dir%/profiler
            matcher:
                ip:                   ~
    
                # использовать формат urldecoded
                path:                 ~ # Example: ^/path to resource/
                service:              ~
    
        # конфигурация маршрутизатора
        router:
            resource:             ~ # Required
            type:                 ~
            http_port:            80
            https_port:           443
    
            # * установить, как "true", чтобы вызвать исключение, если параметр не
            #   соответствует требованиям
            # * установить, как "false", чтобы отключить исключения, когда параметр не
            #   соответствует требованиям (и вернуть вместо этого "null")
            # * установить, как "null", чтобы отключить проверку параметров на требования
            #
            # 'true' - предпочитваемая конфигурация в режиме разработки, а
            # 'false' или 'null' - могут быть лучше в производстве
            strict_requirements:  true
    
        # конфигурация сессии
        session:
            storage_id:           session.storage.native
            handler_id:           session.handler.native_file
            name:                 ~
            cookie_lifetime:      ~
            cookie_path:          ~
            cookie_domain:        ~
            cookie_secure:        ~
            cookie_httponly:      ~
            gc_divisor:           ~
            gc_probability:       ~
            gc_maxlifetime:       ~
            save_path:            '%kernel.cache_dir%/sessions'
    
        # конфигурация сериализатора
        serializer:
           enabled:                   false
           cache:                      ~
           name_converter:             ~
           circular_reference_handler: ~
    
        # конфигурация ресурсов
        assets:
            base_path:          ~
            base_urls:          []
            version:            ~
            version_format:     '%%s?%%s'
            packages:
    
                # Прототип
                name:
                    base_path:            ~
                    base_urls:            []
                    version:              ~
                    version_format:       '%%s?%%s'
    
        # конфигурация шаблонизатора
        templating:
            hinclude_default_template:  ~
            form:
                resources:
    
                    # По умолчанию:
                    - FrameworkBundle:Form
            cache:                ~
            engines:              # Required
    
                # Пример:
                - twig
            loaders:              []
    
        # конфигурация переводчика
        translator:
            enabled:              false
            fallbacks:            [en]
            logging:              "%kernel.debug%"
            paths:                []
    
        # конфигурация валидации
        validation:
            enabled:              false
            cache:                ~
            enable_annotations:   false
            translation_domain:   validators
            mapping:
                paths:            []
    
        # конфигурация аннотации
        annotations:
            cache:                file
            file_cache_dir:       '%kernel.cache_dir%/annotations'
            debug:                '%kernel.debug%'
    
        # конфигурация обработки PHP-ошибок
        php_errors:
            log:                  false
            throw:                '%kernel.debug%'
    
        # конфигурация кеша
        cache:
            app: cache.app
            system: cache.system
            directory: '%kernel.cache_dir%/pools'
            default_doctrine_provider: ~
            default_psr6_provider: ~
            default_redis_provider: 'redis://localhost'
            pools:
                # Прототип
                name:
                    adapter: cache.app
                    public: false
                    default_lifetime: ~
                    provider: ~
                    clearer: ~
    

Эта документация является переводом официальной документации Symfony и предоставляется по свободной лицензии CC BY-SA 3.0.