diff --git a/reference/configuration/framework.rst b/reference/configuration/framework.rst index 93c4f31345b..e7910bf547c 100644 --- a/reference/configuration/framework.rst +++ b/reference/configuration/framework.rst @@ -20,23 +20,29 @@ routing and more. Configuration ------------- -* `secret`_ -* `http_method_override`_ -* `trusted_proxies`_ -* `ide`_ -* `test`_ -* `default_locale`_ -* `trusted_hosts`_ -* :ref:`form ` - * :ref:`enabled ` +* `annotations`_ + * :ref:`cache ` + * `file_cache_dir`_ + * `debug`_ +* `assets`_ + * `base_path`_ + * `base_urls`_ + * `packages`_ + * `version`_ + * `version_format`_ * `csrf_protection`_ * :ref:`enabled ` * `field_name`_ (deprecated as of 2.4) +* `default_locale`_ * `esi`_ * :ref:`enabled ` + * :ref:`form ` + * :ref:`enabled ` * `fragments`_ * :ref:`enabled ` * :ref:`path ` +* `http_method_override`_ +* `ide`_ * `profiler`_ * :ref:`enabled ` * `collect`_ @@ -50,12 +56,20 @@ Configuration * `ip`_ * :ref:`path ` * `service`_ +* `property_access`_ + * `magic_call`_ + * `throw_exception_on_invalid_index`_ * `router`_ * `resource`_ * `type`_ * `http_port`_ * `https_port`_ * `strict_requirements`_ +* `secret`_ +* `serializer`_ + * :ref:`enabled ` + * :ref:`cache ` + * :ref:`enable_annotations ` * `session`_ * `storage_id`_ * `handler_id`_ @@ -69,12 +83,6 @@ Configuration * `gc_probability`_ * `gc_maxlifetime`_ * `save_path`_ -* `assets`_ - * `base_path`_ - * `base_urls`_ - * `packages`_ - * `version`_ - * `version_format`_ * `templating`_ * `hinclude_default_template`_ * :ref:`form ` @@ -82,13 +90,13 @@ Configuration * :ref:`cache ` * `engines`_ * `loaders`_ +* `test`_ * `translator`_ * :ref:`enabled ` * `fallbacks`_ * `logging`_ -* `property_access`_ - * `magic_call`_ - * `throw_exception_on_invalid_index`_ +* `trusted_hosts`_ +* `trusted_proxies`_ * `validation`_ * :ref:`enabled ` * :ref:`cache ` @@ -96,91 +104,103 @@ Configuration * `translation_domain`_ * `strict_email`_ * `api`_ -* `annotations`_ - * :ref:`cache ` - * `file_cache_dir`_ - * `debug`_ -* `serializer`_ - * :ref:`enabled ` - * :ref:`cache ` - * :ref:`enable_annotations ` -secret -~~~~~~ +annotations +~~~~~~~~~~~ -**type**: ``string`` **required** +.. _reference-annotations-cache: -This is a string that should be unique to your application and it's commonly -used to add more entropy to security related operations. Its value should -be a series of characters, numbers and symbols chosen randomly and the -recommended length is around 32 characters. +cache +..... -In practice, Symfony uses this value for generating the -:doc:`CSRF tokens `, for encrypting the cookies used -in the :doc:`remember me functionality ` and for -creating signed URIs when using :ref:`ESI (Edge Side Includes) `. +**type**: ``string`` **default**: ``'file'`` -This option becomes the service container parameter named ``kernel.secret``, -which you can use whenever the application needs an immutable random string -to add more entropy. +This option can be one of the following values: -As with any other security-related parameter, it is a good practice to change -this value from time to time. However, keep in mind that changing this value -will invalidate all signed URIs and Remember Me cookies. That's why, after -changing this value, you should regenerate the application cache and log -out all the application users. +file + Use the filesystem to cache annotations +none + Disable the caching of annotations +a service id + A service id referencing a `Doctrine Cache`_ implementation -.. _configuration-framework-http_method_override: +file_cache_dir +.............. -http_method_override -~~~~~~~~~~~~~~~~~~~~ +**type**: ``string`` **default**: ``'%kernel.cache_dir%/annotations'`` -.. versionadded:: 2.3 - The ``http_method_override`` option was introduced in Symfony 2.3. +The directory to store cache files for annotations, in case +``annotations.cache`` is set to ``'file'``. -**type**: ``boolean`` **default**: ``true`` +debug +..... -This determines whether the ``_method`` request parameter is used as the -intended HTTP method on POST requests. If enabled, the -:method:`Request::enableHttpMethodParameterOverride ` -method gets called automatically. It becomes the service container parameter -named ``kernel.http_method_override``. +**type**: ``boolean`` **default**: ``%kernel.debug%`` -.. seealso:: +Whether to enable debug mode for caching. If enabled, the cache will +automatically update when the original file is changed (both with code and +annotation changes). For performance reasons, it is recommended to disable +debug mode in production, which will happen automatically if you use the +default value. - For more information, see :doc:`/form/action_method`. +assets +~~~~~~ -.. caution:: +.. _reference-assets-base-path: - If you're using the :ref:`AppCache Reverse Proxy ` - with this option, the kernel will ignore the ``_method`` parameter, - which could lead to errors. +base_path +......... - To fix this, invoke the ``enableHttpMethodParameterOverride()`` method - before creating the ``Request`` object:: +**type**: ``string`` - // web/app.php +This option allows you to define a base path to be used for assets: - // ... - $kernel = new AppCache($kernel); +.. configuration-block:: - Request::enableHttpMethodParameterOverride(); // <-- add this line - $request = Request::createFromGlobals(); - // ... + .. code-block:: yaml -.. _reference-framework-trusted-proxies: + # app/config/config.yml + framework: + # ... + assets: + base_path: '/images' -trusted_proxies -~~~~~~~~~~~~~~~ + .. code-block:: xml -**type**: ``array`` + + + -Configures the IP addresses that should be trusted as proxies. For more -details, see :doc:`/request/load_balancer_reverse_proxy`. + + + + -.. versionadded:: 2.3 - CIDR notation support was introduced in Symfony 2.3, so you can whitelist - whole subnets (e.g. ``10.0.0.0/8``, ``fc00::/7``). + .. code-block:: php + + // app/config/config.php + $container->loadFromExtension('framework', array( + // ... + 'assets' => array( + 'base_path' => '/images', + ), + )); + +.. _reference-templating-base-urls: +.. _reference-assets-base-urls: + +base_urls +......... + +**type**: ``array`` + +This option allows you to define base URLs to be used for assets. +If multiple base URLs are provided, Symfony will select one from the +collection each time it generates an asset's path: .. configuration-block:: @@ -188,7 +208,10 @@ details, see :doc:`/request/load_balancer_reverse_proxy`. # app/config/config.yml framework: - trusted_proxies: [192.0.0.1, 10.0.0.0/8] + # ... + assets: + base_urls: + - 'http://cdn.example.com/' .. code-block:: xml @@ -200,39 +223,25 @@ details, see :doc:`/request/load_balancer_reverse_proxy`. 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"> - + + + .. code-block:: php // app/config/config.php $container->loadFromExtension('framework', array( - 'trusted_proxies' => array('192.0.0.1', '10.0.0.0/8'), + // ... + 'assets' => array( + 'base_urls' => array('http://cdn.example.com/'), + ), )); -ide -~~~ - -**type**: ``string`` **default**: ``null`` - -If you're using an IDE like TextMate or Mac Vim, then Symfony can turn all -of the file paths in an exception message into a link, which will open that -file in your IDE. - -Symfony contains preconfigured URLs for some popular IDEs, you can set them -using the following keys: - -* ``textmate`` -* ``macvim`` -* ``emacs`` -* ``sublime`` - -.. versionadded:: 2.3.14 - The ``emacs`` and ``sublime`` editors were introduced in Symfony 2.3.14. +packages +........ -You can also specify a custom URL string. If you do this, all percentage -signs (``%``) must be doubled to escape that character. For example, if -you use PHPstorm on the Mac OS platform, you will do something like: +You can group assets into packages, to specify different base URLs for them: .. configuration-block:: @@ -240,7 +249,11 @@ you use PHPstorm on the Mac OS platform, you will do something like: # app/config/config.yml framework: - ide: 'phpstorm://open?file=%%f&line=%%l' + # ... + assets: + packages: + avatars: + base_urls: 'http://static_cdn.example.com/avatars' .. code-block:: xml @@ -252,83 +265,75 @@ you use PHPstorm on the Mac OS platform, you will do something like: 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"> - + + + + + .. code-block:: php // app/config/config.php $container->loadFromExtension('framework', array( - 'ide' => 'phpstorm://open?file=%%f&line=%%l', + // ... + 'assets' => array( + 'packages' => array( + 'avatars' => array( + 'base_urls' => 'http://static_cdn.example.com/avatars', + ), + ), + ), )); -.. tip:: +Now you can use the ``avatars`` package in your templates: - If you're on a Windows PC, you can install the `PhpStormProtocol`_ to - be able to use this. +.. configuration-block:: php -Of course, since every developer uses a different IDE, it's better to set -this on a system level. This can be done by setting the ``xdebug.file_link_format`` -in the ``php.ini`` configuration to the URL string. + .. code-block:: html+twig -If you don't use Xdebug, another way is to set this URL string in the -``SYMFONY__TEMPLATING__HELPER__CODE__FILE_LINK_FORMAT`` environment variable. -If any of these configurations values are set, the ``ide`` option will be ignored. + -.. _reference-framework-test: + .. code-block:: html+php -test -~~~~ + -**type**: ``boolean`` +Each package can configure the following options: -If this configuration setting is present (and not ``false``), then the services -related to testing your application (e.g. ``test.client``) are loaded. This -setting should be present in your ``test`` environment (usually via -``app/config/config_test.yml``). - -.. seealso:: - - For more information, see :doc:`/testing`. +* :ref:`base_path ` +* :ref:`base_urls ` +* :ref:`version ` +* :ref:`version_format ` -default_locale -~~~~~~~~~~~~~~ +.. _reference-framework-assets-version: +.. _ref-framework-assets-version: -**type**: ``string`` **default**: ``en`` +version +....... -The default locale is used if no ``_locale`` routing parameter has been -set. It is available with the -:method:`Request::getDefaultLocale ` -method. +**type**: ``string`` -.. seealso:: +This option is used to *bust* the cache on assets by globally adding a query +parameter to all rendered asset paths (e.g. ``/images/logo.png?v2``). This +applies only to assets rendered via the Twig ``asset()`` function (or PHP +equivalent) as well as assets rendered with Assetic. - You can read more information about the default locale in - :ref:`translation-default-locale`. +For example, suppose you have the following: -trusted_hosts -~~~~~~~~~~~~~ +.. configuration-block:: -**type**: ``array`` | ``string`` **default**: ``array()`` + .. code-block:: html+twig -A lot of different attacks have been discovered relying on inconsistencies -in handling the ``Host`` header by various software (web servers, reverse -proxies, web frameworks, etc.). Basically, every time the framework is -generating an absolute URL (when sending an email to reset a password for -instance), the host might have been manipulated by an attacker. + Symfony! -.. seealso:: + .. code-block:: php - You can read "`HTTP Host header attacks`_" for more information about - these kinds of attacks. + Symfony! -The Symfony :method:`Request::getHost() ` -method might be vulnerable to some of these attacks because it depends on -the configuration of your web server. One simple solution to avoid these -attacks is to whitelist the hosts that your Symfony application can respond -to. That's the purpose of this ``trusted_hosts`` option. If the incoming -request's hostname doesn't match one in this list, the application won't -respond and the user will receive a 500 response. +By default, this will render a path to your image such as ``/images/logo.png``. +Now, activate the ``version`` option: .. configuration-block:: @@ -336,7 +341,9 @@ respond and the user will receive a 500 response. # app/config/config.yml framework: - trusted_hosts: ['example.com', 'example.org'] + # ... + assets: + version: 'v2' .. code-block:: xml @@ -349,61 +356,72 @@ respond and the user will receive a 500 response. http://symfony.com/schema/dic/symfony http://symfony.com/schema/dic/symfony/symfony-1.0.xsd"> - example.com - example.org - - + + .. code-block:: php // app/config/config.php $container->loadFromExtension('framework', array( - 'trusted_hosts' => array('example.com', 'example.org'), + // ... + 'assets' => array( + 'version' => 'v2', + ), )); -Hosts can also be configured using regular expressions (e.g. ``.*\.?example.com$``), -which make it easier to respond to any subdomain. - -In addition, you can also set the trusted hosts in the front controller -using the ``Request::setTrustedHosts()`` method:: - - // web/app.php - Request::setTrustedHosts(array('.*\.?example.com$', '.*\.?example.org$')); - -The default value for this option is an empty array, meaning that the application -can respond to any given host. +Now, the same asset will be rendered as ``/images/logo.png?v2`` If you use +this feature, you **must** manually increment the ``version`` value +before each deployment so that the query parameters change. -.. seealso:: +You can also control how the query string works via the `version_format`_ +option. - Read more about this in the `Security Advisory Blog post`_. +.. tip:: -.. _reference-framework-form: + As with all settings, you can use a parameter as value for the + ``version``. This makes it easier to increment the cache on each + deployment. -form -~~~~ +.. _reference-templating-version-format: +.. _reference-assets-version-format: -.. _reference-form-enabled: +version_format +.............. -enabled -....... +**type**: ``string`` **default**: ``%%s?%%s`` -**type**: ``boolean`` **default**: ``false`` +This specifies a :phpfunction:`sprintf` pattern that will be used with the +`version`_ option to construct an asset's path. By default, the pattern +adds the asset's version as a query string. For example, if +``version_format`` is set to ``%%s?version=%%s`` and ``version`` +is set to ``5``, the asset's path would be ``/images/logo.png?version=5``. -Whether to enable the form services or not in the service container. If -you don't use forms, setting this to ``false`` may increase your application's -performance because less services will be loaded into the container. +.. note:: -This option will automatically be set to ``true`` when one of the child -settings is configured. + All percentage signs (``%``) in the format string must be doubled to + escape the character. Without escaping, values might inadvertently be + interpreted as :ref:`service-container-parameters`. -.. note:: +.. tip:: - This will automatically enable the `validation`_. + Some CDN's do not support cache-busting via query strings, so injecting + the version into the actual file path is necessary. Thankfully, + ``version_format`` is not limited to producing versioned query + strings. -.. seealso:: + The pattern receives the asset's original path and version as its first + and second parameters, respectively. Since the asset's path is one + parameter, you cannot modify it in-place (e.g. ``/images/logo-v5.png``); + however, you can prefix the asset's path using a pattern of + ``version-%%2$s/%%1$s``, which would result in the path + ``version-5/images/logo.png``. - For more details, see :doc:`/forms`. + URL rewrite rules could then be used to disregard the version prefix + before serving the asset. Alternatively, you could copy assets to the + appropriate version path as part of your deployment process and forgot + any URL rewriting. The latter option is useful if you would like older + asset versions to remain accessible at their original URL. csrf_protection ~~~~~~~~~~~~~~~ @@ -439,6 +457,21 @@ field_name The name of the hidden field used to render the :doc:`CSRF token `. +default_locale +~~~~~~~~~~~~~~ + +**type**: ``string`` **default**: ``en`` + +The default locale is used if no ``_locale`` routing parameter has been +set. It is available with the +:method:`Request::getDefaultLocale ` +method. + +.. seealso:: + + You can read more information about the default locale in + :ref:`translation-default-locale`. + esi ~~~ @@ -487,6 +520,33 @@ You can also set ``esi`` to ``true`` to enable it: 'esi' => true, )); +.. _reference-framework-form: + +form +~~~~ + +.. _reference-form-enabled: + +enabled +....... + +**type**: ``boolean`` **default**: ``false`` + +Whether to enable the form services or not in the service container. If +you don't use forms, setting this to ``false`` may increase your application's +performance because less services will be loaded into the container. + +This option will automatically be set to ``true`` when one of the child +settings is configured. + +.. note:: + + This will automatically enable the `validation`_. + +.. seealso:: + + For more details, see :doc:`/forms`. + fragments ~~~~~~~~~ @@ -518,60 +578,297 @@ path The path prefix for fragments. The fragment listener will only be executed when the request starts with this path. -profiler -~~~~~~~~ +.. _configuration-framework-http_method_override: -.. _reference-profiler-enabled: +http_method_override +~~~~~~~~~~~~~~~~~~~~ -enabled -....... +.. versionadded:: 2.3 + The ``http_method_override`` option was introduced in Symfony 2.3. -**type**: ``boolean`` **default**: ``false`` +**type**: ``boolean`` **default**: ``true`` -The profiler can be enabled by setting this option to ``true``. When you -are using the Symfony Standard Edition, the profiler is enabled in the ``dev`` -and ``test`` environments. +This determines whether the ``_method`` request parameter is used as the +intended HTTP method on POST requests. If enabled, the +:method:`Request::enableHttpMethodParameterOverride ` +method gets called automatically. It becomes the service container parameter +named ``kernel.http_method_override``. -.. note:: +.. seealso:: - The profiler works independently from the Web Developer Toolbar, see - the :doc:`WebProfilerBundle configuration ` - on how to disable/enable the toolbar. + For more information, see :doc:`/form/action_method`. -collect -....... +.. caution:: -.. versionadded:: 2.3 - The ``collect`` option was introduced in Symfony 2.3. Previously, when - ``profiler.enabled`` was ``false``, the profiler *was* actually enabled, - but the collectors were disabled. Now, the profiler and the collectors - can be controlled independently. + If you're using the :ref:`AppCache Reverse Proxy ` + with this option, the kernel will ignore the ``_method`` parameter, + which could lead to errors. -**type**: ``boolean`` **default**: ``true`` + To fix this, invoke the ``enableHttpMethodParameterOverride()`` method + before creating the ``Request`` object:: -This option configures the way the profiler behaves when it is enabled. -If set to ``true``, the profiler collects data for all requests (unless -you configure otherwise, like a custom `matcher`_). If you want to only -collect information on-demand, you can set the ``collect`` flag to ``false`` -and activate the data collectors manually:: + // web/app.php - $profiler->enable(); + // ... + $kernel = new AppCache($kernel); -only_exceptions -............... + Request::enableHttpMethodParameterOverride(); // <-- add this line + $request = Request::createFromGlobals(); + // ... -**type**: ``boolean`` **default**: ``false`` +ide +~~~ -When this is set to ``true``, the profiler will only be enabled when an -exception is thrown during the handling of the request. +**type**: ``string`` **default**: ``null`` -only_master_requests -.................... +If you're using an IDE like TextMate or Mac Vim, then Symfony can turn all +of the file paths in an exception message into a link, which will open that +file in your IDE. -**type**: ``boolean`` **default**: ``false`` +Symfony contains preconfigured URLs for some popular IDEs, you can set them +using the following keys: -When this is set to ``true``, the profiler will only be enabled on the master -requests (and not on the subrequests). +* ``textmate`` +* ``macvim`` +* ``emacs`` +* ``sublime`` + +.. versionadded:: 2.3.14 + The ``emacs`` and ``sublime`` editors were introduced in Symfony 2.3.14. + +You can also specify a custom URL string. If you do this, all percentage +signs (``%``) must be doubled to escape that character. For example, if +you use PHPstorm on the Mac OS platform, you will do something like: + +.. configuration-block:: + + .. code-block:: yaml + + # app/config/config.yml + framework: + ide: 'phpstorm://open?file=%%f&line=%%l' + + .. code-block:: xml + + + + + + + + + .. code-block:: php + + // app/config/config.php + $container->loadFromExtension('framework', array( + 'ide' => 'phpstorm://open?file=%%f&line=%%l', + )); + +.. tip:: + + If you're on a Windows PC, you can install the `PhpStormProtocol`_ to + be able to use this. + +Of course, since every developer uses a different IDE, it's better to set +this on a system level. This can be done by setting the ``xdebug.file_link_format`` +in the ``php.ini`` configuration to the URL string. + +If you don't use Xdebug, another way is to set this URL string in the +``SYMFONY__TEMPLATING__HELPER__CODE__FILE_LINK_FORMAT`` environment variable. +If any of these configurations values are set, the ``ide`` option will be ignored. + +property_access +~~~~~~~~~~~~~~~ + +magic_call +.......... + +**type**: ``boolean`` **default**: ``false`` + +When enabled, the ``property_accessor`` service uses PHP's +:ref:`magic __call() method ` when +its ``getValue()`` method is called. + +throw_exception_on_invalid_index +................................ + +**type**: ``boolean`` **default**: ``false`` + +When enabled, the ``property_accessor`` service throws an exception when you +try to access an invalid index of an array. + +.. _reference-framework-trusted-proxies: + +trusted_proxies +~~~~~~~~~~~~~~~ + +**type**: ``array`` + +Configures the IP addresses that should be trusted as proxies. For more +details, see :doc:`/request/load_balancer_reverse_proxy`. + +.. versionadded:: 2.3 + CIDR notation support was introduced in Symfony 2.3, so you can whitelist + whole subnets (e.g. ``10.0.0.0/8``, ``fc00::/7``). + +.. configuration-block:: + + .. code-block:: yaml + + # app/config/config.yml + framework: + trusted_proxies: [192.0.0.1, 10.0.0.0/8] + + .. code-block:: xml + + + + + + + + + .. code-block:: php + + // app/config/config.php + $container->loadFromExtension('framework', array( + 'trusted_proxies' => array('192.0.0.1', '10.0.0.0/8'), + )); + +trusted_hosts +~~~~~~~~~~~~~ + +**type**: ``array`` | ``string`` **default**: ``array()`` + +A lot of different attacks have been discovered relying on inconsistencies +in handling the ``Host`` header by various software (web servers, reverse +proxies, web frameworks, etc.). Basically, every time the framework is +generating an absolute URL (when sending an email to reset a password for +instance), the host might have been manipulated by an attacker. + +.. seealso:: + + You can read "`HTTP Host header attacks`_" for more information about + these kinds of attacks. + +The Symfony :method:`Request::getHost() ` +method might be vulnerable to some of these attacks because it depends on +the configuration of your web server. One simple solution to avoid these +attacks is to whitelist the hosts that your Symfony application can respond +to. That's the purpose of this ``trusted_hosts`` option. If the incoming +request's hostname doesn't match one in this list, the application won't +respond and the user will receive a 500 response. + +.. configuration-block:: + + .. code-block:: yaml + + # app/config/config.yml + framework: + trusted_hosts: ['example.com', 'example.org'] + + .. code-block:: xml + + + + + + + example.com + example.org + + + + + .. code-block:: php + + // app/config/config.php + $container->loadFromExtension('framework', array( + 'trusted_hosts' => array('example.com', 'example.org'), + )); + +Hosts can also be configured using regular expressions (e.g. ``.*\.?example.com$``), +which make it easier to respond to any subdomain. + +In addition, you can also set the trusted hosts in the front controller +using the ``Request::setTrustedHosts()`` method:: + + // web/app.php + Request::setTrustedHosts(array('.*\.?example.com$', '.*\.?example.org$')); + +The default value for this option is an empty array, meaning that the application +can respond to any given host. + +.. seealso:: + + Read more about this in the `Security Advisory Blog post`_. + +profiler +~~~~~~~~ + +.. _reference-profiler-enabled: + +enabled +....... + +**type**: ``boolean`` **default**: ``false`` + +The profiler can be enabled by setting this option to ``true``. When you +are using the Symfony Standard Edition, the profiler is enabled in the ``dev`` +and ``test`` environments. + +.. note:: + + The profiler works independently from the Web Developer Toolbar, see + the :doc:`WebProfilerBundle configuration ` + on how to disable/enable the toolbar. + +collect +....... + +.. versionadded:: 2.3 + The ``collect`` option was introduced in Symfony 2.3. Previously, when + ``profiler.enabled`` was ``false``, the profiler *was* actually enabled, + but the collectors were disabled. Now, the profiler and the collectors + can be controlled independently. + +**type**: ``boolean`` **default**: ``true`` + +This option configures the way the profiler behaves when it is enabled. +If set to ``true``, the profiler collects data for all requests (unless +you configure otherwise, like a custom `matcher`_). If you want to only +collect information on-demand, you can set the ``collect`` flag to ``false`` +and activate the data collectors manually:: + + $profiler->enable(); + +only_exceptions +............... + +**type**: ``boolean`` **default**: ``false`` + +When this is set to ``true``, the profiler will only be enabled when an +exception is thrown during the handling of the request. + +only_master_requests +.................... + +**type**: ``boolean`` **default**: ``false`` + +When this is set to ``true``, the profiler will only be enabled on the master +requests (and not on the subrequests). dsn ... @@ -698,349 +995,190 @@ The value can be one of: ``true`` is recommended in the development environment, while ``false`` or ``null`` might be preferred in production. -session -~~~~~~~ +secret +~~~~~~ -storage_id -.......... +**type**: ``string`` **required** -**type**: ``string`` **default**: ``'session.storage.native'`` +This is a string that should be unique to your application and it's commonly +used to add more entropy to security related operations. Its value should +be a series of characters, numbers and symbols chosen randomly and the +recommended length is around 32 characters. -The service id used for session storage. The ``session.storage`` service -alias will be set to this service id. This class has to implement -:class:`Symfony\\Component\\HttpFoundation\\Session\\Storage\\SessionStorageInterface`. +In practice, Symfony uses this value for generating the +:doc:`CSRF tokens `, for encrypting the cookies used +in the :doc:`remember me functionality ` and for +creating signed URIs when using :ref:`ESI (Edge Side Includes) `. -handler_id -.......... - -**type**: ``string`` **default**: ``'session.handler.native_file'`` - -The service id used for session storage. The ``session.handler`` service -alias will be set to this service id. - -You can also set it to ``null``, to default to the handler of your PHP -installation. - -.. seealso:: - - You can see an example of the usage of this in - :doc:`/doctrine/pdo_session_storage`. - -name -.... - -**type**: ``string`` **default**: ``null`` - -This specifies the name of the session cookie. By default it will use the -cookie name which is defined in the ``php.ini`` with the ``session.name`` -directive. - -cookie_lifetime -............... - -**type**: ``integer`` **default**: ``null`` - -This determines the lifetime of the session - in seconds. The default value -- ``null`` - means that the ``session.cookie_lifetime`` value from ``php.ini`` -will be used. Setting this value to ``0`` means the cookie is valid for -the length of the browser session. - -cookie_path -........... - -**type**: ``string`` **default**: ``/`` - -This determines the path to set in the session cookie. By default it will -use ``/``. - -cookie_domain -............. - -**type**: ``string`` **default**: ``''`` +This option becomes the service container parameter named ``kernel.secret``, +which you can use whenever the application needs an immutable random string +to add more entropy. -This determines the domain to set in the session cookie. By default it's -blank, meaning the host name of the server which generated the cookie according -to the cookie specification. +As with any other security-related parameter, it is a good practice to change +this value from time to time. However, keep in mind that changing this value +will invalidate all signed URIs and Remember Me cookies. That's why, after +changing this value, you should regenerate the application cache and log +out all the application users. -cookie_secure -............. +.. _configuration-framework-serializer: -**type**: ``boolean`` **default**: ``false`` +serializer +~~~~~~~~~~ -This determines whether cookies should only be sent over secure connections. +.. _reference-serializer-enabled: -cookie_httponly -............... +enabled +....... **type**: ``boolean`` **default**: ``false`` -This determines whether cookies should only be accessible through the HTTP -protocol. This means that the cookie won't be accessible by scripting -languages, such as JavaScript. This setting can effectively help to reduce -identity theft through XSS attacks. - -gc_divisor -.......... - -**type**: ``integer`` **default**: ``100`` - -See `gc_probability`_. - -gc_probability -.............. - -**type**: ``integer`` **default**: ``1`` - -This defines the probability that the garbage collector (GC) process is -started on every session initialization. The probability is calculated by -using ``gc_probability`` / ``gc_divisor``, e.g. 1/100 means there is a 1% -chance that the GC process will start on each request. - -gc_maxlifetime -.............. - -**type**: ``integer`` **default**: ``1440`` - -This determines the number of seconds after which data will be seen as "garbage" -and potentially cleaned up. Garbage collection may occur during session -start and depends on `gc_divisor`_ and `gc_probability`_. - -save_path -......... - -**type**: ``string`` **default**: ``%kernel.cache_dir%/sessions`` - -This determines the argument to be passed to the save handler. If you choose -the default file handler, this is the path where the session files are created. -For more information, see :doc:`/session/sessions_directory`. - -You can also set this value to the ``save_path`` of your ``php.ini`` by -setting the value to ``null``: - -.. configuration-block:: - - .. code-block:: yaml - - # app/config/config.yml - framework: - session: - save_path: ~ - - .. code-block:: xml - - - - - - - - - - - .. code-block:: php - - // app/config/config.php - $container->loadFromExtension('framework', array( - 'session' => array( - 'save_path' => null, - ), - )); - -assets -~~~~~~ +Whether to enable the ``serializer`` service or not in the service container. -.. _reference-assets-base-path: +.. _reference-serializer-cache: -base_path -......... +cache +..... **type**: ``string`` -This option allows you to define a base path to be used for assets: - -.. configuration-block:: - - .. code-block:: yaml - - # app/config/config.yml - framework: - # ... - assets: - base_path: '/images' - - .. code-block:: xml +The service that is used to persist class metadata in a cache. The service +has to implement the ``Doctrine\Common\Cache\Cache`` interface. - - - +.. seealso:: - - - - + For more information, see :ref:`serializer-enabling-metadata-cache`. - .. code-block:: php +.. _reference-serializer-enable_annotations: - // app/config/config.php - $container->loadFromExtension('framework', array( - // ... - 'assets' => array( - 'base_path' => '/images', - ), - )); +enable_annotations +.................. -.. _reference-templating-base-urls: -.. _reference-assets-base-urls: +**type**: ``boolean`` **default**: ``false`` -base_urls -......... +If this option is enabled, serialization groups can be defined using annotations. -**type**: ``array`` +.. seealso:: -This option allows you to define base URLs to be used for assets. -If multiple base URLs are provided, Symfony will select one from the -collection each time it generates an asset's path: + For more information, see :ref:`serializer-using-serialization-groups-annotations`. -.. configuration-block:: +session +~~~~~~~ - .. code-block:: yaml +storage_id +.......... - # app/config/config.yml - framework: - # ... - assets: - base_urls: - - 'http://cdn.example.com/' +**type**: ``string`` **default**: ``'session.storage.native'`` - .. code-block:: xml +The service id used for session storage. The ``session.storage`` service +alias will be set to this service id. This class has to implement +:class:`Symfony\\Component\\HttpFoundation\\Session\\Storage\\SessionStorageInterface`. - - - +handler_id +.......... - - - - +**type**: ``string`` **default**: ``'session.handler.native_file'`` - .. code-block:: php +The service id used for session storage. The ``session.handler`` service +alias will be set to this service id. - // app/config/config.php - $container->loadFromExtension('framework', array( - // ... - 'assets' => array( - 'base_urls' => array('http://cdn.example.com/'), - ), - )); +You can also set it to ``null``, to default to the handler of your PHP +installation. -packages -........ +.. seealso:: -You can group assets into packages, to specify different base URLs for them: + You can see an example of the usage of this in + :doc:`/doctrine/pdo_session_storage`. -.. configuration-block:: +name +.... - .. code-block:: yaml +**type**: ``string`` **default**: ``null`` - # app/config/config.yml - framework: - # ... - assets: - packages: - avatars: - base_urls: 'http://static_cdn.example.com/avatars' +This specifies the name of the session cookie. By default it will use the +cookie name which is defined in the ``php.ini`` with the ``session.name`` +directive. - .. code-block:: xml +cookie_lifetime +............... - - - +**type**: ``integer`` **default**: ``null`` - - - - - - +This determines the lifetime of the session - in seconds. The default value +- ``null`` - means that the ``session.cookie_lifetime`` value from ``php.ini`` +will be used. Setting this value to ``0`` means the cookie is valid for +the length of the browser session. - .. code-block:: php +cookie_path +........... - // app/config/config.php - $container->loadFromExtension('framework', array( - // ... - 'assets' => array( - 'packages' => array( - 'avatars' => array( - 'base_urls' => 'http://static_cdn.example.com/avatars', - ), - ), - ), - )); +**type**: ``string`` **default**: ``/`` -Now you can use the ``avatars`` package in your templates: +This determines the path to set in the session cookie. By default it will +use ``/``. -.. configuration-block:: php +cookie_domain +............. - .. code-block:: html+twig +**type**: ``string`` **default**: ``''`` - +This determines the domain to set in the session cookie. By default it's +blank, meaning the host name of the server which generated the cookie according +to the cookie specification. - .. code-block:: html+php +cookie_secure +............. - +**type**: ``boolean`` **default**: ``false`` -Each package can configure the following options: +This determines whether cookies should only be sent over secure connections. -* :ref:`base_path ` -* :ref:`base_urls ` -* :ref:`version ` -* :ref:`version_format ` +cookie_httponly +............... -.. _reference-framework-assets-version: -.. _ref-framework-assets-version: +**type**: ``boolean`` **default**: ``false`` -version -....... +This determines whether cookies should only be accessible through the HTTP +protocol. This means that the cookie won't be accessible by scripting +languages, such as JavaScript. This setting can effectively help to reduce +identity theft through XSS attacks. -**type**: ``string`` +gc_divisor +.......... -This option is used to *bust* the cache on assets by globally adding a query -parameter to all rendered asset paths (e.g. ``/images/logo.png?v2``). This -applies only to assets rendered via the Twig ``asset()`` function (or PHP -equivalent) as well as assets rendered with Assetic. +**type**: ``integer`` **default**: ``100`` -For example, suppose you have the following: +See `gc_probability`_. -.. configuration-block:: +gc_probability +.............. - .. code-block:: html+twig +**type**: ``integer`` **default**: ``1`` - Symfony! +This defines the probability that the garbage collector (GC) process is +started on every session initialization. The probability is calculated by +using ``gc_probability`` / ``gc_divisor``, e.g. 1/100 means there is a 1% +chance that the GC process will start on each request. - .. code-block:: php +gc_maxlifetime +.............. - Symfony! +**type**: ``integer`` **default**: ``1440`` -By default, this will render a path to your image such as ``/images/logo.png``. -Now, activate the ``version`` option: +This determines the number of seconds after which data will be seen as "garbage" +and potentially cleaned up. Garbage collection may occur during session +start and depends on `gc_divisor`_ and `gc_probability`_. + +save_path +......... + +**type**: ``string`` **default**: ``%kernel.cache_dir%/sessions`` + +This determines the argument to be passed to the save handler. If you choose +the default file handler, this is the path where the session files are created. +For more information, see :doc:`/session/sessions_directory`. + +You can also set this value to the ``save_path`` of your ``php.ini`` by +setting the value to ``null``: .. configuration-block:: @@ -1048,9 +1186,8 @@ Now, activate the ``version`` option: # app/config/config.yml framework: - # ... - assets: - version: 'v2' + session: + save_path: ~ .. code-block:: xml @@ -1063,7 +1200,7 @@ Now, activate the ``version`` option: http://symfony.com/schema/dic/symfony http://symfony.com/schema/dic/symfony/symfony-1.0.xsd"> - + @@ -1071,65 +1208,11 @@ Now, activate the ``version`` option: // app/config/config.php $container->loadFromExtension('framework', array( - // ... - 'assets' => array( - 'version' => 'v2', + 'session' => array( + 'save_path' => null, ), )); -Now, the same asset will be rendered as ``/images/logo.png?v2`` If you use -this feature, you **must** manually increment the ``version`` value -before each deployment so that the query parameters change. - -You can also control how the query string works via the `version_format`_ -option. - -.. tip:: - - As with all settings, you can use a parameter as value for the - ``version``. This makes it easier to increment the cache on each - deployment. - -.. _reference-templating-version-format: -.. _reference-assets-version-format: - -version_format -.............. - -**type**: ``string`` **default**: ``%%s?%%s`` - -This specifies a :phpfunction:`sprintf` pattern that will be used with the -`version`_ option to construct an asset's path. By default, the pattern -adds the asset's version as a query string. For example, if -``version_format`` is set to ``%%s?version=%%s`` and ``version`` -is set to ``5``, the asset's path would be ``/images/logo.png?version=5``. - -.. note:: - - All percentage signs (``%``) in the format string must be doubled to - escape the character. Without escaping, values might inadvertently be - interpreted as :ref:`service-container-parameters`. - -.. tip:: - - Some CDN's do not support cache-busting via query strings, so injecting - the version into the actual file path is necessary. Thankfully, - ``version_format`` is not limited to producing versioned query - strings. - - The pattern receives the asset's original path and version as its first - and second parameters, respectively. Since the asset's path is one - parameter, you cannot modify it in-place (e.g. ``/images/logo-v5.png``); - however, you can prefix the asset's path using a pattern of - ``version-%%2$s/%%1$s``, which would result in the path - ``version-5/images/logo.png``. - - URL rewrite rules could then be used to disregard the version prefix - before serving the asset. Alternatively, you could copy assets to the - appropriate version path as part of your deployment process and forgot - any URL rewriting. The latter option is useful if you would like older - asset versions to remain accessible at their original URL. - templating ~~~~~~~~~~ @@ -1255,6 +1338,22 @@ templating loaders. Templating loaders are used to find and load templates from a resource (e.g. a filesystem or database). Templating loaders must implement :class:`Symfony\\Component\\Templating\\Loader\\LoaderInterface`. +.. _reference-framework-test: + +test +~~~~ + +**type**: ``boolean`` + +If this configuration setting is present (and not ``false``), then the services +related to testing your application (e.g. ``test.client``) are loaded. This +setting should be present in your ``test`` environment (usually via +``app/config/config_test.yml``). + +.. seealso:: + + For more information, see :doc:`/testing`. + translator ~~~~~~~~~~ @@ -1302,26 +1401,6 @@ for a given key. The logs are made to the ``translation`` channel and at the ``debug`` for level for keys where there is a translation in the fallback locale and the ``warning`` level if there is no translation to use at all. -property_access -~~~~~~~~~~~~~~~ - -magic_call -.......... - -**type**: ``boolean`` **default**: ``false`` - -When enabled, the ``property_accessor`` service uses PHP's -:ref:`magic __call() method ` when -its ``getValue()`` method is called. - -throw_exception_on_invalid_index -................................ - -**type**: ``boolean`` **default**: ``false`` - -When enabled, the ``property_accessor`` service throws an exception when you -try to access an invalid index of an array. - validation ~~~~~~~~~~ @@ -1398,85 +1477,6 @@ To capture these logs in the ``prod`` environment, configure a :doc:`channel handler ` in ``config_prod.yml`` for the ``translation`` channel and set its ``level`` to ``debug``. -annotations -~~~~~~~~~~~ - -.. _reference-annotations-cache: - -cache -..... - -**type**: ``string`` **default**: ``'file'`` - -This option can be one of the following values: - -file - Use the filesystem to cache annotations -none - Disable the caching of annotations -a service id - A service id referencing a `Doctrine Cache`_ implementation - -file_cache_dir -.............. - -**type**: ``string`` **default**: ``'%kernel.cache_dir%/annotations'`` - -The directory to store cache files for annotations, in case -``annotations.cache`` is set to ``'file'``. - -debug -..... - -**type**: ``boolean`` **default**: ``%kernel.debug%`` - -Whether to enable debug mode for caching. If enabled, the cache will -automatically update when the original file is changed (both with code and -annotation changes). For performance reasons, it is recommended to disable -debug mode in production, which will happen automatically if you use the -default value. - -.. _configuration-framework-serializer: - -serializer -~~~~~~~~~~ - -.. _reference-serializer-enabled: - -enabled -....... - -**type**: ``boolean`` **default**: ``false`` - -Whether to enable the ``serializer`` service or not in the service container. - -.. _reference-serializer-cache: - -cache -..... - -**type**: ``string`` - -The service that is used to persist class metadata in a cache. The service -has to implement the ``Doctrine\Common\Cache\Cache`` interface. - -.. seealso:: - - For more information, see :ref:`serializer-enabling-metadata-cache`. - -.. _reference-serializer-enable_annotations: - -enable_annotations -.................. - -**type**: ``boolean`` **default**: ``false`` - -If this option is enabled, serialization groups can be defined using annotations. - -.. seealso:: - - For more information, see :ref:`serializer-using-serialization-groups-annotations`. - Full Default Configuration --------------------------