diff --git a/reference/configuration/framework.rst b/reference/configuration/framework.rst index f323ae096c6..184e74c8b0c 100644 --- a/reference/configuration/framework.rst +++ b/reference/configuration/framework.rst @@ -166,6 +166,48 @@ named ``kernel.http_method_override``. $request = Request::createFromGlobals(); // ... +.. _reference-framework-trusted-proxies: + +trusted_proxies +~~~~~~~~~~~~~~~ + +**type**: ``array`` + +Configures the IP addresses that should be trusted as proxies. For more +details, see :doc:`/cookbook/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'), + )); + ide ~~~ @@ -331,48 +373,6 @@ can respond to any given host. Read more about this in the `Security Advisory Blog post`_. -.. _reference-framework-trusted-proxies: - -trusted_proxies -~~~~~~~~~~~~~~~ - -**type**: ``array`` - -Configures the IP addresses that should be trusted as proxies. For more -details, see :doc:`/cookbook/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'), - )); - .. _reference-framework-form: form @@ -513,328 +513,309 @@ path The path prefix for fragments. The fragment listener will only be executed when the request starts with this path. -session -~~~~~~~ +profiler +~~~~~~~~ -handler_id -.......... +.. _reference-profiler-enabled: -**type**: ``string`` **default**: ``'session.handler.native_file'`` +enabled +....... -The service id used for session storage. The ``session.handler`` service -alias will be set to this service id. +.. versionadded:: 2.2 + The ``enabled`` option was introduced in Symfony 2.2. Prior to Symfony + 2.2, the profiler could only be disabled by omitting the ``framework.profiler`` + configuration entirely. -You can also set it to ``null``, to default to the handler of your PHP -installation. +**type**: ``boolean`` **default**: ``false`` -.. seealso:: +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. - You can see an example of the usage of this in - :doc:`/cookbook/configuration/pdo_session_storage`. +.. note:: -storage_id -.......... + The profiler works independently from the Web Developer Toolbar, see + the :doc:`WebProfilerBundle configuration ` + on how to disable/enable the toolbar. -**type**: ``string`` **default**: ``'session.storage.native'`` +collect +....... -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`. +.. 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. -name -.... +**type**: ``boolean`` **default**: ``true`` -**type**: ``string`` **default**: ``null`` +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:: -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. + $profiler->enable(); -cookie_lifetime +only_exceptions ............... -**type**: ``integer`` **default**: ``null`` +**type**: ``boolean`` **default**: ``false`` -This determines the lifetime of the session - in seconds. The default value -- ``null`` - means that the ``sesssion.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. +When this is set to ``true``, the profiler will only be enabled when an +exception is thrown during the handling of the request. -cookie_path -........... +only_master_requests +.................... -**type**: ``string`` **default**: ``/`` +**type**: ``boolean`` **default**: ``false`` -This determines the path to set in the session cookie. By default it will -use ``/``. +When this is set to ``true``, the profiler will only be enabled on the master +requests (and not on the subrequests). -cookie_domain -............. +dsn +... -**type**: ``string`` **default**: ``''`` +**type**: ``string`` **default**: ``'file:%kernel.cache_dir%/profiler'`` -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. +The DSN where to store the profiling information. -cookie_secure -............. +.. seealso:: -**type**: ``boolean`` **default**: ``false`` + See :doc:`/cookbook/profiler/storage` for more information about the + profiler storage. -This determines whether cookies should only be sent over secure connections. +username +........ -cookie_httponly -............... +**type**: ``string`` **default**: ``''`` -**type**: ``boolean`` **default**: ``false`` +When needed, the username for the profiling storage. -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. +password +........ -gc_probability -.............. +**type**: ``string`` **default**: ``''`` -**type**: ``integer`` **default**: ``1`` +When needed, the password for the profiling storage. -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. +lifetime +........ -gc_divisor -.......... +**type**: ``integer`` **default**: ``86400`` -**type**: ``integer`` **default**: ``100`` +The lifetime of the profiling storage in seconds. The data will be deleted +when the lifetime is expired. -See `gc_probability`_. +matcher +....... -gc_maxlifetime -.............. +Matcher options are configured to dynamically enable the profiler. For +instance, based on the `ip`_ or :ref:`path `. -**type**: ``integer`` **default**: ``1440`` +.. seealso:: -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`_. + See :doc:`/cookbook/profiler/matchers` for more information about using + matchers to enable/disable the profiler. -save_path -......... +ip +"" -**type**: ``string`` **default**: ``%kernel.cache.dir%/sessions`` +**type**: ``string`` -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:`/cookbook/session/sessions_directory`. +If set, the profiler will only be enabled when the current IP address matches. -You can also set this value to the ``save_path`` of your ``php.ini`` by -setting the value to ``null``: +.. _reference-profiler-matcher-path: -.. configuration-block:: +path +"""" - .. code-block:: yaml +**type**: ``string`` - # app/config/config.yml - framework: - session: - save_path: ~ +If set, the profiler will only be enabled when the current path matches. - .. code-block:: xml +service +""""""" - - - +**type**: ``string`` - - - - +This setting contains the service id of a custom matcher. - .. code-block:: php +router +~~~~~~ - // app/config/config.php - $container->loadFromExtension('framework', array( - 'session' => array( - 'save_path' => null, - ), - )); +resource +........ -.. _configuration-framework-serializer: +**type**: ``string`` **required** -serializer -~~~~~~~~~~ +The path the main routing resource (e.g. a YAML file) that contains the +routes and imports the router should load. -.. _reference-serializer-enabled: +type +.... -enabled -....... +**type**: ``string`` -**type**: ``boolean`` **default**: ``false`` +The type of the resource to hint the loaders about the format. This isn't +needed when you use the default routers with the expected file extensions +(``.xml``, ``.yml`` / ``.yaml``, ``.php``). -Whether to enable the ``serializer`` service or not in the service container. +http_port +......... -For more details, see :doc:`/cookbook/serializer`. +**type**: ``integer`` **default**: ``80`` -templating -~~~~~~~~~~ +The port for normal http requests (this is used when matching the scheme). -.. _reference-templating-base-urls: +https_port +.......... -assets_base_urls -................ +**type**: ``integer`` **default**: ``443`` -**default**: ``{ http: [], ssl: [] }`` +The port for https requests (this is used when matching the scheme). -This option allows you to define base URLs to be used for assets referenced -from ``http`` and ``ssl`` (``https``) pages. If multiple base URLs are -provided, Symfony will select one from the collection each time it generates -an asset's path: +strict_requirements +................... -.. configuration-block:: +**type**: ``mixed`` **default**: ``true`` - .. code-block:: yaml +Determines the routing generator behaviour. When generating a route that +has specific :ref:`requirements `, the generator +can behave differently in case the used parameters do not meet these requirements. - # app/config/config.yml - framework: - # ... - templating: - assets_base_urls: - http: - - "http://cdn.example.com/" - # you can also pass just a string: - # assets_base_urls: - # http: "//cdn.example.com/" +The value can be one of: - .. code-block:: xml +``true`` + Throw an exception when the requirements are not met; +``false`` + Disable exceptions when the requirements are not met and return ``null`` + instead; +``null`` + Disable checking the requirements (thus, match the route even when the + requirements don't match). - - - +``true`` is recommended in the development environment, while ``false`` +or ``null`` might be preferred in production. - - +session +~~~~~~~ - - - http://cdn.example.com/ - - - - +storage_id +.......... - .. code-block:: php +**type**: ``string`` **default**: ``'session.storage.native'`` - // app/config/config.php - $container->loadFromExtension('framework', array( - // ... - 'templating' => array( - 'assets_base_urls' => array( - 'http' => array( - 'http://cdn.example.com/', - ), - ), - // you can also pass just a string: - // 'assets_base_urls' => array( - // 'http' => '//cdn.example.com/', - // ), - ), - )); +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`. -For your convenience, you can pass a string or array of strings to -``assets_base_urls`` directly. This will automatically be organized into -the ``http`` and ``ssl`` base urls (``https://`` and `protocol-relative`_ -URLs will be added to both collections and ``http://`` only to the ``http`` -collection): +handler_id +.......... -.. configuration-block:: +**type**: ``string`` **default**: ``'session.handler.native_file'`` - .. code-block:: yaml +The service id used for session storage. The ``session.handler`` service +alias will be set to this service id. - # app/config/config.yml - framework: - # ... - templating: - assets_base_urls: - - "//cdn.example.com/" - # you can also pass just a string: - # assets_base_urls: "//cdn.example.com/" +You can also set it to ``null``, to default to the handler of your PHP +installation. - .. code-block:: xml +.. seealso:: - - - + You can see an example of the usage of this in + :doc:`/cookbook/configuration/pdo_session_storage`. - - +name +.... - - //cdn.example.com/ - - - +**type**: ``string`` **default**: ``null`` - .. code-block:: php +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. - // app/config/config.php - $container->loadFromExtension('framework', array( - // ... - 'templating' => array( - 'assets_base_urls' => array( - '//cdn.example.com/', - ), - // you can also pass just a string: - // 'assets_base_urls' => '//cdn.example.com/', - ), - )); +cookie_lifetime +............... -.. _reference-templating-cache: +**type**: ``integer`` **default**: ``null`` -cache -..... +This determines the lifetime of the session - in seconds. The default value +- ``null`` - means that the ``sesssion.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. -**type**: ``string`` +cookie_path +........... -The path to the cache directory for templates. When this is not set, caching -is disabled. +**type**: ``string`` **default**: ``/`` -.. note:: +This determines the path to set in the session cookie. By default it will +use ``/``. - When using Twig templating, the caching is already handled by the - TwigBundle and doesn't need to be enabled for the FrameworkBundle. +cookie_domain +............. -engines -....... +**type**: ``string`` **default**: ``''`` -**type**: ``string[]`` / ``string`` **required** +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. -The Templating Engine to use. This can either be a string (when only one -engine is configured) or an array of engines. +cookie_secure +............. -At least one engine is required. +**type**: ``boolean`` **default**: ``false`` -loaders -....... +This determines whether cookies should only be sent over secure connections. -**type**: ``string[]`` +cookie_httponly +............... -An array (or a string when configuring just one loader) of service ids for -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`. +**type**: ``boolean`` **default**: ``false`` -packages -........ +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. -You can group assets into packages, to specify different base URLs for them: +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:`/cookbook/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:: @@ -842,11 +823,8 @@ You can group assets into packages, to specify different base URLs for them: # app/config/config.yml framework: - # ... - templating: - packages: - avatars: - base_urls: 'http://static_cdn.example.com/avatars' + session: + save_path: ~ .. code-block:: xml @@ -859,15 +837,7 @@ You can group assets into packages, to specify different base URLs for them: http://symfony.com/schema/dic/symfony http://symfony.com/schema/dic/symfony/symfony-1.0.xsd"> - - - - - - - + @@ -875,33 +845,13 @@ You can group assets into packages, to specify different base URLs for them: // app/config/config.php $container->loadFromExtension('framework', array( - // ... - 'templating' => array( - 'packages' => array( - 'avatars' => array( - 'base_urls' => 'http://static_cdn.example.com/avatars', - ), - ), + 'session' => array( + 'save_path' => null, ), )); -Now you can use the ``avatars`` package in your templates: - -.. configuration-block:: php - - .. code-block:: html+jinja - - - - .. code-block:: html+php - - - -Each package can configure the following options: - -* :ref:`base_urls ` -* :ref:`version ` -* :ref:`version_format ` +templating +~~~~~~~~~~ .. _reference-framework-assets-version: .. _ref-framework-assets-version: @@ -1110,190 +1060,224 @@ Assume you have custom global form themes in See :ref:`book-forms-theming-global` for more information. -profiler -~~~~~~~~ - -.. _reference-profiler-enabled: - -enabled -....... - -.. versionadded:: 2.2 - The ``enabled`` option was introduced in Symfony 2.2. Prior to Symfony - 2.2, the profiler could only be disabled by omitting the ``framework.profiler`` - configuration entirely. - -**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 -....... +.. _reference-templating-base-urls: -.. 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. +assets_base_urls +................ -**type**: ``boolean`` **default**: ``true`` +**default**: ``{ http: [], ssl: [] }`` -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:: +This option allows you to define base URLs to be used for assets referenced +from ``http`` and ``ssl`` (``https``) pages. If multiple base URLs are +provided, Symfony will select one from the collection each time it generates +an asset's path: - $profiler->enable(); +.. configuration-block:: -only_exceptions -............... + .. code-block:: yaml -**type**: ``boolean`` **default**: ``false`` + # app/config/config.yml + framework: + # ... + templating: + assets_base_urls: + http: + - "http://cdn.example.com/" + # you can also pass just a string: + # assets_base_urls: + # http: "//cdn.example.com/" -When this is set to ``true``, the profiler will only be enabled when an -exception is thrown during the handling of the request. + .. code-block:: xml -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). + + + http://cdn.example.com/ + + + + -dsn -... + .. code-block:: php -**type**: ``string`` **default**: ``'file:%kernel.cache_dir%/profiler'`` + // app/config/config.php + $container->loadFromExtension('framework', array( + // ... + 'templating' => array( + 'assets_base_urls' => array( + 'http' => array( + 'http://cdn.example.com/', + ), + ), + // you can also pass just a string: + // 'assets_base_urls' => array( + // 'http' => '//cdn.example.com/', + // ), + ), + )); -The DSN where to store the profiling information. +For your convenience, you can pass a string or array of strings to +``assets_base_urls`` directly. This will automatically be organized into +the ``http`` and ``ssl`` base urls (``https://`` and `protocol-relative`_ +URLs will be added to both collections and ``http://`` only to the ``http`` +collection): -.. seealso:: +.. configuration-block:: - See :doc:`/cookbook/profiler/storage` for more information about the - profiler storage. + .. code-block:: yaml -username -........ + # app/config/config.yml + framework: + # ... + templating: + assets_base_urls: + - "//cdn.example.com/" + # you can also pass just a string: + # assets_base_urls: "//cdn.example.com/" -**type**: ``string`` **default**: ``''`` + .. code-block:: xml -When needed, the username for the profiling storage. + + + -password -........ + + -**type**: ``string`` **default**: ``''`` + + //cdn.example.com/ + + + -When needed, the password for the profiling storage. + .. code-block:: php -lifetime -........ + // app/config/config.php + $container->loadFromExtension('framework', array( + // ... + 'templating' => array( + 'assets_base_urls' => array( + '//cdn.example.com/', + ), + // you can also pass just a string: + // 'assets_base_urls' => '//cdn.example.com/', + ), + )); -**type**: ``integer`` **default**: ``86400`` +.. _reference-templating-cache: -The lifetime of the profiling storage in seconds. The data will be deleted -when the lifetime is expired. +cache +..... -matcher -....... +**type**: ``string`` -Matcher options are configured to dynamically enable the profiler. For -instance, based on the `ip`_ or :ref:`path `. +The path to the cache directory for templates. When this is not set, caching +is disabled. -.. seealso:: +.. note:: - See :doc:`/cookbook/profiler/matchers` for more information about using - matchers to enable/disable the profiler. + When using Twig templating, the caching is already handled by the + TwigBundle and doesn't need to be enabled for the FrameworkBundle. -ip -"" +engines +....... -**type**: ``string`` +**type**: ``string[]`` / ``string`` **required** -If set, the profiler will only be enabled when the current IP address matches. +The Templating Engine to use. This can either be a string (when only one +engine is configured) or an array of engines. -.. _reference-profiler-matcher-path: +At least one engine is required. -path -"""" +loaders +....... -**type**: ``string`` +**type**: ``string[]`` -If set, the profiler will only be enabled when the current path matches. +An array (or a string when configuring just one loader) of service ids for +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`. -service -""""""" +packages +........ -**type**: ``string`` +You can group assets into packages, to specify different base URLs for them: -This setting contains the service id of a custom matcher. +.. configuration-block:: -router -~~~~~~ + .. code-block:: yaml -resource -........ + # app/config/config.yml + framework: + # ... + templating: + packages: + avatars: + base_urls: 'http://static_cdn.example.com/avatars' -**type**: ``string`` **required** + .. code-block:: xml -The path the main routing resource (e.g. a YAML file) that contains the -routes and imports the router should load. + + + -type -.... + -**type**: ``string`` + -The type of the resource to hint the loaders about the format. This isn't -needed when you use the default routers with the expected file extensions -(``.xml``, ``.yml`` / ``.yaml``, ``.php``). + -http_port -......... + -**type**: ``integer`` **default**: ``80`` + + -The port for normal http requests (this is used when matching the scheme). + .. code-block:: php -https_port -.......... + // app/config/config.php + $container->loadFromExtension('framework', array( + // ... + 'templating' => array( + 'packages' => array( + 'avatars' => array( + 'base_urls' => 'http://static_cdn.example.com/avatars', + ), + ), + ), + )); -**type**: ``integer`` **default**: ``443`` +Now you can use the ``avatars`` package in your templates: -The port for https requests (this is used when matching the scheme). +.. configuration-block:: php -strict_requirements -................... + .. code-block:: html+jinja -**type**: ``mixed`` **default**: ``true`` + -Determines the routing generator behaviour. When generating a route that -has specific :ref:`requirements `, the generator -can behave differently in case the used parameters do not meet these requirements. + .. code-block:: html+php -The value can be one of: + -``true`` - Throw an exception when the requirements are not met; -``false`` - Disable exceptions when the requirements are not met and return ``null`` - instead; -``null`` - Disable checking the requirements (thus, match the route even when the - requirements don't match). +Each package can configure the following options: -``true`` is recommended in the development environment, while ``false`` -or ``null`` might be preferred in production. +* :ref:`base_urls ` +* :ref:`version ` +* :ref:`version_format ` translator ~~~~~~~~~~ @@ -1480,6 +1464,22 @@ 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. + +For more details, see :doc:`/cookbook/serializer`. + Full Default Configuration --------------------------