From cd6ee1300992406795e77e848f15c52ea2b099ca Mon Sep 17 00:00:00 2001 From: WouterJ Date: Sun, 4 Jan 2015 01:46:37 +0100 Subject: [PATCH 1/8] Rewrote FrameworkBundle configuration reference --- book/http_cache.rst | 2 + book/templating.rst | 2 + book/translation.rst | 4 +- reference/configuration/framework.rst | 982 ++++++++++++++++++++++---- 4 files changed, 855 insertions(+), 135 deletions(-) diff --git a/book/http_cache.rst b/book/http_cache.rst index 5cae7a710e2..0b68f08929b 100644 --- a/book/http_cache.rst +++ b/book/http_cache.rst @@ -1099,6 +1099,8 @@ of the master page. With ESI, the full page cache will be valid for 600 seconds, but the news component cache will only last for 60 seconds. +.. _book-http_cache-fragments: + When using a controller reference, the ESI tag should reference the embedded action as an accessible URL so the gateway cache can fetch it independently of the rest of the page. Symfony takes care of generating a unique URL for any diff --git a/book/templating.rst b/book/templating.rst index b185e909017..2829f7ccb47 100644 --- a/book/templating.rst +++ b/book/templating.rst @@ -688,6 +688,8 @@ Controllers are fast to execute and promote good code organization and reuse. Of course, like all controllers, they should ideally be "skinny", meaning that as much code as possible lives in reusable :doc:`services `. +.. _book-templating-hinclude: + Asynchronous Content with hinclude.js ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/book/translation.rst b/book/translation.rst index 35339af79c2..45b72eadb52 100644 --- a/book/translation.rst +++ b/book/translation.rst @@ -510,7 +510,9 @@ in your application. Read :doc:`/cookbook/routing/service_container_parameters` to learn how to avoid hardcoding the ``_locale`` requirement in all your routes. -Setting a default Locale +.. _book-translation-default-locale: + +Setting a Default Locale ~~~~~~~~~~~~~~~~~~~~~~~~ What if the user's locale hasn't been determined? You can guarantee that a diff --git a/reference/configuration/framework.rst b/reference/configuration/framework.rst index 5c871545081..ca7ba13c95e 100644 --- a/reference/configuration/framework.rst +++ b/reference/configuration/framework.rst @@ -4,29 +4,61 @@ FrameworkBundle Configuration ("framework") =========================================== -This reference document is a work in progress. It should be accurate, but -all options are not yet fully covered. - The FrameworkBundle contains most of the "base" framework functionality -and can be configured under the ``framework`` key in your application configuration. +and can be configured under the ``framework`` key in your application +configuration. When using XML, you can use the +``http://symfony.com/schema/dic/symfony`` namespace. + This includes settings related to sessions, translation, forms, validation, routing and more. +.. tip:: + + The XSD schema is available at + ``http://symfony.com/schema/dic/symfony/symfony-1.0.xsd``. + Configuration ------------- * `secret`_ * `http_method_override`_ +* `trusted_proxies`_ * `ide`_ * `test`_ * `default_locale`_ -* `trusted_proxies`_ -* `form`_ - * enabled +* `trusted_hosts`_ +* :ref:`form ` + * :ref:`enabled ` * `csrf_protection`_ - * enabled - * field_name + * :ref:`enabled ` + * `field_name`_ +* `esi`_ + * :ref:`enabled ` +* `fragments`_ + * :ref:`enabled ` + * :ref:`path ` +* `profiler`_ + * :ref:`enabled ` + * `collect`_ + * `only_exceptions`_ + * `only_master_requests`_ + * `dsn`_ + * `username`_ + * `password`_ + * `lifetime`_ + * `matcher`_ + * `ip`_ + * :ref:`path ` + * `service`_ +* `router`_ + * `resource`_ + * `type`_ + * `http_port`_ + * `https_port`_ + * `strict_requirements`_ * `session`_ + * `storage_id`_ + * `handler_id`_ * `name`_ * `cookie_lifetime`_ * `cookie_path`_ @@ -37,27 +69,38 @@ Configuration * `gc_probability`_ * `gc_maxlifetime`_ * `save_path`_ -* `serializer`_ - * :ref:`enabled` * `templating`_ - * `assets_base_urls`_ * `assets_version`_ * `assets_version_format`_ -* `profiler`_ - * `collect`_ - * :ref:`enabled ` + * `hinclude_default_template`_ + * :ref:`form ` + * `resources`_ + * `assets_base_urls`_ + * http + * ssl + * :ref:`cache ` + * `engines`_ + * `loaders`_ + * `packages`_ * `translator`_ - * :ref:`enabled ` + * :ref:`enabled ` * `fallback`_ * `validation`_ - * `cache`_ + * :ref:`enabled ` + * :ref:`cache ` * `enable_annotations`_ * `translation_domain`_ +* `annotations`_ + * :ref:`cache ` + * `file_cache_dir`_ + * `debug`_ +* `serializer`_ + * :ref:`enabled ` secret ~~~~~~ -**type**: ``string`` **required** +**type**: ``string`` This is a string that should be unique to your application. In practice, it's used for generating the CSRF tokens, but it could be used in any other @@ -72,14 +115,65 @@ http_method_override .. versionadded:: 2.3 The ``http_method_override`` option was introduced in Symfony 2.3. -**type**: ``Boolean`` **default**: ``true`` +**type**: ``boolean`` **default**: ``true`` 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``. For more information, see -:doc:`/cookbook/routing/method_parameters`. +named ``kernel.http_method_override``. + +.. seealso:: + + For more information, see :doc:`/cookbook/routing/method_parameters`. + +.. _reference-framework-trusted-proxies: + +trusted_proxies +~~~~~~~~~~~~~~~ + +**type**: ``array`` + +Configures the IP addresses that should be trusted as proxies. It becomes the +service container parameter called ``kernel.trusted_proxies``. + +.. seealso:: + + 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 ~~~ @@ -143,19 +237,21 @@ is set, then the ``ide`` option will be ignored. test ~~~~ -**type**: ``Boolean`` +**type**: ``boolean`` If this configuration parameter 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``). For more information, see :doc:`/book/testing`. +``app/config/config_test.yml``). -.. _reference-framework-trusted-proxies: +.. seealso:: + + For more information, see :doc:`/book/testing`. default_locale ~~~~~~~~~~~~~~ -**type**: ``string`` **default**: ``en`` +**type**: ``string`` **default**: ``'en'`` The default locale is used if no ``_locale`` routing parameter has been set. It becomes the service container parameter named ``kernel.default_locale`` and it @@ -163,17 +259,191 @@ is also available with the :method:`Request::getDefaultLocale ` method. -trusted_proxies +.. seealso:: + + You can read more information about the default locale in + :ref:`book-translation-default-locale`. + +trusted_hosts +~~~~~~~~~~~~~ + +**type**: ``array`` | ``string`` **default**: ``array()`` + +A lot of different attacks have been discovered relying on inconsistencies +between the handling of the ``Host`` header by various software (web servers, +reverse proxies, web frameworks, etc.). Basically, everytime 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: ['acme.com', 'acme.org'] + + .. code-block:: xml + + + + + + + acme.com + acme.org + + + + + .. code-block:: php + + // app/config/config.php + $container->loadFromExtension('framework', array( + 'trusted_hosts' => array('acme.com', 'acme.org'), + )); + +Hosts can also be configured using regular expressions, which make it easier to +respond to any subdomain: + +.. configuration-block:: + + .. code-block:: yaml + + # app/config/config.yml + framework: + trusted_hosts: ['.*\.?acme.com$', '.*\.?acme.org$'] + + .. code-block:: xml + + + + + + + .*\.?acme.com$ + .*\.?acme.org$ + + + + + .. code-block:: php + + // app/config/config.php + $container->loadFromExtension('framework', array( + 'trusted_hosts' => array('.*\.?acme.com$', '.*\.?acme.org$'), + )); + +In addition, you can also set the trusted hosts in the front controller using +the ``Request::setTrustedHosts()`` method:: + + // web/app.php + Request::setTrustedHosts(array('.*\.?acme.com$', '.*\.?acme.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`_. + +.. _reference-framework-form: + +form +~~~~ + +.. _reference-form-enabled: + +enabled +....... + +**type**: ``boolean`` **default**: ``false`` + +Whether to enable the form services or not in the service 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:`/book/forms`. + +csrf_protection ~~~~~~~~~~~~~~~ -**type**: ``array`` +.. seealso:: -Configures the IP addresses that should be trusted as proxies. For more details, -see :doc:`/cookbook/request/load_balancer_reverse_proxy`. + For more information about CSRF protection in forms, see :ref:`forms-csrf`. -.. 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``). +.. _reference-form-csrf_protection-enabled: + +enabled +....... + +**type**: ``boolean`` **default**: ``true`` + +Whether to enable the CSRF support in forms or not. Setting this option to +``true`` requires the `secret`_ to be set and `session`_ to be enabled. It +becomes the service container parameter named ``form.type_extension.csrf.enabled``. + +This option will automatically be set to ``true`` when one of the child +settings is configured. + +.. seealso:: + + Read more about CSRF in :ref:`the Book `. + +field_name +.......... + +**type**: ``string`` **default**: ``'_token'`` + +The name of the hidden field containing the CSRF token in the form. It becomes +the service container parameter named ``form.type_extension.csrf.field_name``. + +esi +~~~ + +.. seealso:: + + You can read more about Edge Side Includes (ESI) in :ref:`edge-side-includes`. + +.. _reference-esi-enabled: + +enabled +....... + +**type**: ``boolean`` **default**: ``false`` + +Whether to enable the edge side includes support in the framework. + +You can also set ``esi`` to ``true`` to enable it: .. configuration-block:: @@ -181,39 +451,277 @@ see :doc:`/cookbook/request/load_balancer_reverse_proxy`. # app/config/config.yml framework: - trusted_proxies: [192.0.0.1, 10.0.0.0/8] + esi: true + + .. code-block:: xml + + + + + + + + + + + .. code-block:: php + + // app/config/config.php + $container->loadFromExtension('framework', array( + 'esi' => true, + )); + +fragments +~~~~~~~~~ + +.. seealso:: + + Learn more about fragments in the + :ref:`HTTP Cache article `. + +.. _reference-fragments-enabled: + +enabled +....... + +**type**: ``boolean`` **default**: ``false`` + +Whether to enable the fragment listener or not. The fragment listener is used +to render ESI fragments independently of the rest of the page. + +This setting is automatically set to ``true`` when one of the child settings is +configured. + +.. _reference-fragments-path: + +path +.... + +**type**: ``string`` **default**: ``'/_fragment'`` + +The path prefix for fragments. The fragment listener will only be executed +when the request starts with this path. It becomes the service container +parameter called ``fragment.path``. + +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**: ``true`` in the ``dev`` and ``test`` environments + +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 it. + +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. 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. It becomes the service +container parameter called ``profiler_listener.only_exceptions``. + +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). It becomes the service container +parameter called ``profiler_listener.only_master_requests``. + +dsn +... + +**type**: ``string`` **default**: ``'file:%kernel.cache_dir%/profiler'`` + +The DSN where to save the profiling information. The supported drivers (part +before the colon) are: + +* file +* sqlite +* mysql +* mongodb +* memcache +* memcached +* redis + +It becomes the service container parameter called ``profiler.storage.dsn``. + +username +........ + +**type**: ``string`` **default**: ``''`` + +When needed, the username for the profiling storage. It becomes the service +container parameter called ``profiler.storage.username``. + +password +........ + +**type**: ``string`` **default**: ``''`` + +When needed, the password for hte profiling storage. It becomes the service +container parameter called ``profiler.storage.password``. + +lifetime +........ + +**type**: ``integer`` **default**: ``86400`` + +The lifetime of the profiling storage in seconds. The data will be deleted when +the lifetime is expired. It becomes the service container parameter called +``profiler.storage.lifetime``. + + +matcher +....... + +.. seealso:: + + See :doc:`/cookbook/profiler/matchers` for more information about using + matchers to enable/disable the profiler. + +ip +"" + +**type**: ``string`` + +If set, the profiler will only be enabled when the current IP address matches. + +.. _reference-profiler-matcher-path: + +path +"""" + +**type**: ``string`` + +If set, the profiler will only be enabled when the current path matches. + +service +""""""" + +**type**: ``string`` + +This setting contains the service id of a custom matcher. + +router +~~~~~~ + +resource +........ + +**type**: ``string`` **required** + +Specifies the path to the routes used by the default router. + +It becomes the service container parameter called ``router.resource``. + +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). + +It becomes the service container parameter called ``router.resource``. - .. code-block:: xml +https_port +.......... - - - +**type**: ``integer`` **default**: ``443`` - - +The port for https requests (this is used when matching the scheme). - .. code-block:: php +strict_requirements +................... - // app/config/config.php - $container->loadFromExtension('framework', array( - 'trusted_proxies' => array('192.0.0.1', '10.0.0.0/8'), - )); +**type**: ``mixed`` **default**: ``true`` -.. _reference-framework-form: +Determines the behaviour when a route matches, but the parameters do not match +the specified requirements for that route. Can be one of: -form -~~~~ +``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). -csrf_protection -~~~~~~~~~~~~~~~ +``false`` is recommended in the development environment, while ``false`` or +``null`` might be preferred in production. session ~~~~~~~ +storage_id +.......... + +**type**: ``string`` **default**: ``'session.storage.native'`` + +The service id used for session storage. The ``session.storage`` service alias +will be set to this service id. + +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. + name .... @@ -251,20 +759,27 @@ to the cookie specification. cookie_secure ............. -**type**: ``Boolean`` **default**: ``false`` +**type**: ``boolean`` **default**: ``false`` This determines whether cookies should only be sent over secure connections. cookie_httponly ............... -**type**: ``Boolean`` **default**: ``false`` +**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 .............. @@ -275,13 +790,6 @@ 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_divisor -.......... - -**type**: ``integer`` **default**: ``100`` - -See `gc_probability`_. - gc_maxlifetime .............. @@ -294,7 +802,7 @@ and depends on `gc_divisor`_ and `gc_probability`_. save_path ......... -**type**: ``string`` **default**: ``%kernel.cache.dir%/sessions`` +**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. @@ -310,7 +818,7 @@ the value to ``null``: # app/config/config.yml framework: session: - save_path: null + save_path: ~ .. code-block:: xml @@ -336,42 +844,9 @@ the value to ``null``: ), )); -.. _configuration-framework-serializer: - -serializer -~~~~~~~~~~ - -.. _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`. - templating ~~~~~~~~~~ -assets_base_urls -................ - -**default**: ``{ http: [], ssl: [] }`` - -This option allows you to define base URLs to be used for assets referenced -from ``http`` and ``ssl`` (``https``) pages. A string value may be provided in -lieu of a single-element array. If multiple base URLs are provided, Symfony -will select one from the collection each time it generates an asset's path. - -For your convenience, ``assets_base_urls`` can be set directly with a string or -array of strings, which will be automatically organized into collections of base -URLs for ``http`` and ``https`` requests. If a URL starts with ``https://`` or -is `protocol-relative`_ (i.e. starts with `//`) it will be added to both -collections. URLs starting with ``http://`` will only be added to the -``http`` collection. - .. _ref-framework-assets-version: assets_version @@ -379,7 +854,7 @@ assets_version **type**: ``string`` -This option is used to *bust* the cache on assets by globally adding a query +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. @@ -439,19 +914,24 @@ Now, the same asset will be rendered as ``/images/logo.png?v2`` If you use this feature, you **must** manually increment the ``assets_version`` value before each deployment so that the query parameters change. -You can also control how the query string works via the `assets_version_format`_ -option. +.. tip:: + + As with all settings, you can use a parameter as value for the + ``assets_version``. This makes it easier to increment the cache on each + deployment. + +.. _reference-templating-version-format: assets_version_format ..................... -**type**: ``string`` **default**: ``%%s?%%s`` +**type**: ``string`` **default**: ``'%%s?%%s'`` -This specifies a :phpfunction:`sprintf` pattern that will be used with the `assets_version`_ -option to construct an asset's path. By default, the pattern adds the asset's -version as a query string. For example, if ``assets_version_format`` is set to -``%%s?version=%%s`` and ``assets_version`` is set to ``5``, the asset's path -would be ``/images/logo.png?version=5``. +This specifies a :phpfunction:`sprintf` pattern that will be used with the +`assets_version`_ option to construct an asset's path. By default, the pattern +adds the asset's version as a query string. For example, if +``assets_version_format`` is set to ``%%s?version=%%s`` and ``assets_version`` +is set to ``5``, the asset's path would be ``/images/logo.png?version=5``. .. note:: @@ -477,47 +957,211 @@ would be ``/images/logo.png?version=5``. The latter option is useful if you would like older asset versions to remain accessible at their original URL. -profiler -~~~~~~~~ +hinclude_default_template +......................... + +**type**: ``string`` **default**: ``null`` -.. _profiler.enabled: +Sets the content shown during the loading of the fragment or when JavaScript is +disabled. This can be either a template name or the content itself. It becomes +the service container parameter named ``fragment.renderer.hinclude.global_template``. -enabled +.. seealso:: + + See :ref:`book-templating-hinclude` for more information about hinclude. + +.. _reference-templating-form: + +form +.... + +resources +""""""""" + +**type**: ``string[]`` **default**: ``['FrameworkBundle:Form']`` + +A list of all resources for form theming in PHP. If you have custom global form +themes in ``src/WebsiteBundle/Resources/views/Form``, you can configure this like: + +.. configuration-block:: + + .. code-block:: yaml + + # app/config/config.yml + framework: + templating: + form: + resources: + - 'WebsiteBundle:Form' + + .. code-block:: xml + + + + + + + + + + + + WebsiteBundle:Form + + + + + + + + + .. code-block:: php + + // app/config/config.php + $container->loadFromExtension('framework', array( + 'templating' => array( + 'form' => array( + 'resources' => array( + 'WebsiteBundle:Form' + ), + ), + ), + )); + +.. note:: + + The default form templates from ``FrameworkBundle:Form`` will always be + included in the form resources. + +.. _reference-templating-base-urls: + +assets_base_urls +................ + +**type**: ``{ http: [], ssl: [] }`` + +This option allows you to define base URLs to be used for assets referenced +from ``http`` and ``ssl`` (``https``) pages. A string value may be provided in +lieu of a single-element array. If multiple base URLs are provided, Symfony2 +will select one from the collection each time it generates an asset's path. + +For your convenience, ``assets_base_urls`` can be set directly with a string or +array of strings, which will be automatically organized into collections of base +URLs for ``http`` and ``https`` requests. If a URL starts with ``https://`` or +is `protocol-relative`_ (i.e. starts with ``//``), it will be added to both +collections. URLs starting with ``http://`` will only be added to the +``http`` collection. + +.. _reference-templating-cache: + +cache +..... + +**type**: ``string`` + +The path to the cache directory for templates. When this is not set, caching is +disabled. It becomes the service container parameter named +``templating.loader.cache.path``. + +engines ....... -.. 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**: ``string[]`` / ``string`` **required** -**type**: ``boolean`` **default**: ``false`` +The Templating Engine to use. This can either be a string (when only one engine +is configured) or an array of engines. It becomes the service container +parameter named ``templating.engines``. -The profiler can be enabled by setting this key to ``true``. When you are -using the Symfony Standard Edition, the profiler is enabled in the ``dev`` -and ``test`` environments. +At least one engine is required. -collect +loaders ....... -.. 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**: ``string[]`` -**type**: ``boolean`` **default**: ``true`` +An array (or a string when configuring just one loader) of service ids for +templating loaders. -This option configures the way the profiler behaves when it is enabled. If set -to ``true``, the profiler collects data for all requests. If you want to only -collect information on-demand, you can set the ``collect`` flag to ``false`` -and activate the data collectors by hand:: +packages +........ - $profiler->enable(); +You can group assets into packages, to specify different base URLs for them: + +.. configuration-block:: + + .. code-block:: yaml + + # app/config/config.yml + framework: + # ... + templating: + packages: + avatars: + base_urls: 'http://static_cdn.example.com/avatars' + + .. code-block:: xml + + + + + + + + + + + + + + + + + .. code-block:: php + + // app/config/config.php + $container->loadFromExtension('framework', array( + // ... + 'templating' => array( + 'packages' => array( + 'avatars' => array( + 'base_urls' => 'http://static_cdn.example.com/avatars', + ), + ), + ), + )); + +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 ` translator ~~~~~~~~~~ -.. _translator.enabled: +.. _reference-translator-enabled: enabled ....... @@ -529,7 +1173,7 @@ Whether or not to enable the ``translator`` service in the service container. fallback ........ -**type**: ``string`` **default**: ``en`` +**type**: ``string`` **default**: ``'en'`` This option is used when the translation key for the current locale wasn't found. @@ -538,6 +1182,21 @@ For more details, see :doc:`/book/translation`. validation ~~~~~~~~~~ +.. _reference-validation-enabled: + +enabled +....... + +**type**: ``boolean`` **default**: ``true`` is ``form`` is enabled, ``false`` +otherwise + +Whether to enable the validation or not. + +This option will automatically be set to ``true`` when one of the child +settings is configured. + +.. _reference-validation-cache: + cache ..... @@ -559,11 +1218,64 @@ If this option is enabled, validation constraints can be defined using annotatio translation_domain .................. -**type**: ``string`` **default**: ``validators`` +**type**: ``string`` **default**: ``'validators'`` The translation domain that is used when translating validation constraint error messages. +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. + +.. _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 -------------------------- @@ -693,4 +1405,6 @@ Full default Configuration .. _`protocol-relative`: http://tools.ietf.org/html/rfc3986#section-4.2 .. _`PhpStormOpener`: https://github.com/pinepain/PhpStormOpener -.. _`egulias/email-validator`: https://github.com/egulias/EmailValidator +.. _`HTTP Host header attacks`: http://www.skeletonscribe.net/2013/05/practical-http-host-header-attacks.html +.. _`Security Advisory Blog post`: http://symfony.com/blog/security-releases-symfony-2-0-24-2-1-12-2-2-5-and-2-3-3-released#cve-2013-4752-request-gethost-poisoning +.. _`Doctrine Cache`: http://docs.doctrine-project.org/projects/doctrine-common/en/latest/reference/caching.html From e19cd05d0e4a7050ab1d3a9e5dd3ee7b75e39ea5 Mon Sep 17 00:00:00 2001 From: WouterJ Date: Sun, 4 Jan 2015 01:46:51 +0100 Subject: [PATCH 2/8] Removed config dump --- reference/configuration/framework.rst | 127 -------------------------- 1 file changed, 127 deletions(-) diff --git a/reference/configuration/framework.rst b/reference/configuration/framework.rst index ca7ba13c95e..10dd9f595a6 100644 --- a/reference/configuration/framework.rst +++ b/reference/configuration/framework.rst @@ -1276,133 +1276,6 @@ Whether to enable the ``serializer`` service or not in the service container. For more details, see :doc:`/cookbook/serializer`. -Full default Configuration --------------------------- - -.. configuration-block:: - - .. code-block:: yaml - - framework: - secret: ~ - http_method_override: true - trusted_proxies: [] - ide: ~ - test: ~ - default_locale: en - - # form configuration - form: - enabled: false - csrf_protection: - enabled: false - field_name: _token - - # esi configuration - esi: - enabled: false - - # fragments configuration - fragments: - enabled: false - path: /_fragment - - # profiler configuration - profiler: - enabled: false - collect: true - only_exceptions: false - only_master_requests: false - dsn: file:%kernel.cache_dir%/profiler - username: - password: - lifetime: 86400 - matcher: - ip: ~ - - # use the urldecoded format - path: ~ # Example: ^/path to resource/ - service: ~ - - # router configuration - router: - resource: ~ # Required - type: ~ - http_port: 80 - https_port: 443 - - # set to true to throw an exception when a parameter does not match the requirements - # set to false to disable exceptions when a parameter does not match the requirements (and return null instead) - # set to null to disable parameter checks against requirements - # 'true' is the preferred configuration in development mode, while 'false' or 'null' might be preferred in production - strict_requirements: true - - # session configuration - 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 configuration - serializer: - enabled: false - - # templating configuration - templating: - assets_version: ~ - assets_version_format: "%%s?%%s" - hinclude_default_template: ~ - form: - resources: - - # Default: - - FrameworkBundle:Form - assets_base_urls: - http: [] - ssl: [] - cache: ~ - engines: # Required - - # Example: - - twig - loaders: [] - packages: - - # Prototype - name: - version: ~ - version_format: "%%s?%%s" - base_urls: - http: [] - ssl: [] - - # translator configuration - translator: - enabled: false - fallback: en - - # validation configuration - validation: - enabled: false - cache: ~ - enable_annotations: false - translation_domain: validators - - # annotation configuration - annotations: - cache: file - file_cache_dir: "%kernel.cache_dir%/annotations" - debug: "%kernel.debug%" - .. _`protocol-relative`: http://tools.ietf.org/html/rfc3986#section-4.2 .. _`PhpStormOpener`: https://github.com/pinepain/PhpStormOpener .. _`HTTP Host header attacks`: http://www.skeletonscribe.net/2013/05/practical-http-host-header-attacks.html From 5ee19ed29c4e28997ee046590c9287f8d2765885 Mon Sep 17 00:00:00 2001 From: WouterJ Date: Sun, 4 Jan 2015 14:59:02 +0100 Subject: [PATCH 3/8] lowercase --- reference/configuration/framework.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/reference/configuration/framework.rst b/reference/configuration/framework.rst index 10dd9f595a6..d355dc97124 100644 --- a/reference/configuration/framework.rst +++ b/reference/configuration/framework.rst @@ -1211,7 +1211,7 @@ to implement the :class:`Symfony\\Component\\Validator\\Mapping\\Cache\\CacheInt enable_annotations .................. -**type**: ``Boolean`` **default**: ``false`` +**type**: ``boolean`` **default**: ``false`` If this option is enabled, validation constraints can be defined using annotations. From b560fab85d9f71fe00a11fd216bc9351e9f04a99 Mon Sep 17 00:00:00 2001 From: WouterJ Date: Fri, 20 Feb 2015 11:28:56 +0100 Subject: [PATCH 4/8] Added message from #5008 --- reference/configuration/framework.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/reference/configuration/framework.rst b/reference/configuration/framework.rst index d355dc97124..6585bbf1adf 100644 --- a/reference/configuration/framework.rst +++ b/reference/configuration/framework.rst @@ -120,8 +120,9 @@ http_method_override 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``. +method gets called automatically, unless the application uses a kernel based on +the cache, where you need to invoke that method manually (see +:ref:`symfony2-reverse-proxy` for details). .. seealso:: From d9b1a085589593d564e651aa11c6008f92f285c0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89ric=20Rog=C3=A9?= Date: Thu, 20 Nov 2014 10:59:14 +0100 Subject: [PATCH 5/8] Most recent Phpstorm version natively file links Conflicts: reference/configuration/framework.rst --- reference/configuration/framework.rst | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/reference/configuration/framework.rst b/reference/configuration/framework.rst index 6585bbf1adf..6e4f44597ea 100644 --- a/reference/configuration/framework.rst +++ b/reference/configuration/framework.rst @@ -197,8 +197,8 @@ using the following keys: 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 -have installed `PhpStormOpener`_ and use PHPstorm, you will do something like: +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:: @@ -206,7 +206,7 @@ have installed `PhpStormOpener`_ and use PHPstorm, you will do something like: # app/config/config.yml framework: - ide: "pstorm://%%f:%%l" + ide: "phpstorm://open?file=%%f&line=%%l" .. code-block:: xml @@ -218,14 +218,14 @@ have installed `PhpStormOpener`_ and use PHPstorm, 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' => 'pstorm://%%f:%%l', + 'ide' => 'phpstorm://open?file=%%f&line=%%l', )); Of course, since every developer uses a different IDE, it's better to set @@ -1278,7 +1278,6 @@ Whether to enable the ``serializer`` service or not in the service container. For more details, see :doc:`/cookbook/serializer`. .. _`protocol-relative`: http://tools.ietf.org/html/rfc3986#section-4.2 -.. _`PhpStormOpener`: https://github.com/pinepain/PhpStormOpener .. _`HTTP Host header attacks`: http://www.skeletonscribe.net/2013/05/practical-http-host-header-attacks.html .. _`Security Advisory Blog post`: http://symfony.com/blog/security-releases-symfony-2-0-24-2-1-12-2-2-5-and-2-3-3-released#cve-2013-4752-request-gethost-poisoning .. _`Doctrine Cache`: http://docs.doctrine-project.org/projects/doctrine-common/en/latest/reference/caching.html From 90c9ac0cae1b2036dc3078e092c77fd0eb76d642 Mon Sep 17 00:00:00 2001 From: WouterJ Date: Fri, 20 Feb 2015 12:09:45 +0100 Subject: [PATCH 6/8] Added tip for windows devs --- reference/configuration/framework.rst | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/reference/configuration/framework.rst b/reference/configuration/framework.rst index 6e4f44597ea..ac0be8968af 100644 --- a/reference/configuration/framework.rst +++ b/reference/configuration/framework.rst @@ -228,6 +228,11 @@ PHPstorm on the Mac OS platform, you will do something like: 'ide' => 'phpstorm://open?file=%%f&line=%%l', )); +.. tip:: + + If you're on a Windows PC, you can install the `PhpStormOpener`_ 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 this configuration value @@ -1281,3 +1286,4 @@ For more details, see :doc:`/cookbook/serializer`. .. _`HTTP Host header attacks`: http://www.skeletonscribe.net/2013/05/practical-http-host-header-attacks.html .. _`Security Advisory Blog post`: http://symfony.com/blog/security-releases-symfony-2-0-24-2-1-12-2-2-5-and-2-3-3-released#cve-2013-4752-request-gethost-poisoning .. _`Doctrine Cache`: http://docs.doctrine-project.org/projects/doctrine-common/en/latest/reference/caching.html +.. _`PhpStormOpener`: https://github.com/aik099/PhpStormProtocol From b037d8ce5a37c63675196c8311533b5246d97fcd Mon Sep 17 00:00:00 2001 From: WouterJ Date: Wed, 25 Mar 2015 16:17:09 +0100 Subject: [PATCH 7/8] Applied the easier comments --- book/forms.rst | 4 + book/routing.rst | 2 + reference/configuration/framework.rst | 118 ++++++++------------------ 3 files changed, 41 insertions(+), 83 deletions(-) diff --git a/book/forms.rst b/book/forms.rst index c6c366ce3c6..94bc22138ea 100644 --- a/book/forms.rst +++ b/book/forms.rst @@ -1584,6 +1584,8 @@ override the default error rendering for *all* fields, copy and customize the .. index:: single: Forms; Global Theming +.. _book-forms-theming-global: + Global Form Theming ~~~~~~~~~~~~~~~~~~~ @@ -1591,6 +1593,8 @@ In the above example, you used the ``form_theme`` helper (in Twig) to "import" the custom form fragments into *just* that form. You can also tell Symfony to import form customizations across your entire project. +.. _book-forms-theming-twig: + Twig .... diff --git a/book/routing.rst b/book/routing.rst index 10d15be0df1..b7a4a8ed509 100644 --- a/book/routing.rst +++ b/book/routing.rst @@ -547,6 +547,8 @@ URL Route Parameters .. index:: single: Routing; Requirements +.. _book-routing-requirements: + Adding Requirements ~~~~~~~~~~~~~~~~~~~ diff --git a/reference/configuration/framework.rst b/reference/configuration/framework.rst index ac0be8968af..cc7b0bf34e2 100644 --- a/reference/configuration/framework.rst +++ b/reference/configuration/framework.rst @@ -6,7 +6,7 @@ FrameworkBundle Configuration ("framework") The FrameworkBundle contains most of the "base" framework functionality and can be configured under the ``framework`` key in your application -configuration. When using XML, you can use the +configuration. When using XML, you must use the ``http://symfony.com/schema/dic/symfony`` namespace. This includes settings related to sessions, translation, forms, validation, @@ -142,40 +142,6 @@ service container parameter called ``kernel.trusted_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 ~~~ @@ -275,11 +241,11 @@ trusted_hosts **type**: ``array`` | ``string`` **default**: ``array()`` -A lot of different attacks have been discovered relying on inconsistencies -between the handling of the ``Host`` header by various software (web servers, -reverse proxies, web frameworks, etc.). Basically, everytime 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. +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, everytime 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:: @@ -327,40 +293,8 @@ response. 'trusted_hosts' => array('acme.com', 'acme.org'), )); -Hosts can also be configured using regular expressions, which make it easier to -respond to any subdomain: - -.. configuration-block:: - - .. code-block:: yaml - - # app/config/config.yml - framework: - trusted_hosts: ['.*\.?acme.com$', '.*\.?acme.org$'] - - .. code-block:: xml - - - - - - - .*\.?acme.com$ - .*\.?acme.org$ - - - - - .. code-block:: php - - // app/config/config.php - $container->loadFromExtension('framework', array( - 'trusted_hosts' => array('.*\.?acme.com$', '.*\.?acme.org$'), - )); +Hosts can also be configured using regular expressions (e.g. +``.*\.?acme.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:: @@ -605,7 +539,7 @@ password **type**: ``string`` **default**: ``''`` -When needed, the password for hte profiling storage. It becomes the service +When needed, the password for the profiling storage. It becomes the service container parameter called ``profiler.storage.password``. lifetime @@ -621,6 +555,9 @@ the lifetime is expired. It becomes the service container parameter called matcher ....... +Matcher options are configured to dynamically enable the profiler. For +instance, based on `ip`_ or :ref:`path `. + .. seealso:: See :doc:`/cookbook/profiler/matchers` for more information about using @@ -657,7 +594,8 @@ resource **type**: ``string`` **required** -Specifies the path to the routes used by the default router. +The path the main routing resource (e.g. a YAML file) that contains the routes +and imports the router should load. It becomes the service container parameter called ``router.resource``. @@ -691,8 +629,11 @@ strict_requirements **type**: ``mixed`` **default**: ``true`` -Determines the behaviour when a route matches, but the parameters do not match -the specified requirements for that route. Can be one of: +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. + +The value can be one of: ``true`` Throw an exception when the requirements are not met; @@ -703,7 +644,7 @@ the specified requirements for that route. Can be one of: Disable checking the requirements (thus, match the route even when the requirements don't match). -``false`` is recommended in the development environment, while ``false`` or +``true`` is recommended in the development environment, while ``false`` or ``null`` might be preferred in production. session @@ -986,8 +927,12 @@ resources **type**: ``string[]`` **default**: ``['FrameworkBundle:Form']`` -A list of all resources for form theming in PHP. If you have custom global form -themes in ``src/WebsiteBundle/Resources/views/Form``, you can configure this like: +A list of all resources for form theming in PHP. This setting is not required +if you're using the Twig format for your templates, in that case refer to +:ref:`the form book chapter `. + +Assume you have custom global form themes in +``src/WebsiteBundle/Resources/views/Form``, you can configure this like: .. configuration-block:: @@ -1043,6 +988,10 @@ themes in ``src/WebsiteBundle/Resources/views/Form``, you can configure this lik The default form templates from ``FrameworkBundle:Form`` will always be included in the form resources. +.. seealso:: + + See :ref:`book-forms-theming-global` for more information. + .. _reference-templating-base-urls: assets_base_urls @@ -1090,7 +1039,9 @@ loaders **type**: ``string[]`` An array (or a string when configuring just one loader) of service ids for -templating loaders. +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`. packages ........ @@ -1264,7 +1215,8 @@ 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. +debug mode in production, which will happen automatically if you use the +default value. .. _configuration-framework-serializer: From bb9a1e7c04b570509c94f58bf32c22f1f3a3ce57 Mon Sep 17 00:00:00 2001 From: WouterJ Date: Thu, 26 Mar 2015 18:13:59 +0100 Subject: [PATCH 8/8] Some final fixes --- cookbook/profiler/storage.rst | 16 ++-- reference/configuration/framework.rst | 133 +++++++++++--------------- 2 files changed, 66 insertions(+), 83 deletions(-) diff --git a/cookbook/profiler/storage.rst b/cookbook/profiler/storage.rst index 3e87bc9016c..e91ef883eaa 100644 --- a/cookbook/profiler/storage.rst +++ b/cookbook/profiler/storage.rst @@ -58,12 +58,12 @@ uses MySQL as the storage for the profiler with a lifetime of one hour: )); The :doc:`HttpKernel component ` currently -supports the following profiler storage implementations: +supports the following profiler storage drivers: -* :class:`Symfony\\Component\\HttpKernel\\Profiler\\FileProfilerStorage` -* :class:`Symfony\\Component\\HttpKernel\\Profiler\\MemcachedProfilerStorage` -* :class:`Symfony\\Component\\HttpKernel\\Profiler\\MemcacheProfilerStorage` -* :class:`Symfony\\Component\\HttpKernel\\Profiler\\MongoDbProfilerStorage` -* :class:`Symfony\\Component\\HttpKernel\\Profiler\\MysqlProfilerStorage` -* :class:`Symfony\\Component\\HttpKernel\\Profiler\\RedisProfilerStorage` -* :class:`Symfony\\Component\\HttpKernel\\Profiler\\SqliteProfilerStorage` +* file +* sqlite +* mysql +* mongodb +* memcache +* memcached +* redis diff --git a/reference/configuration/framework.rst b/reference/configuration/framework.rst index cc7b0bf34e2..53f4c0efafb 100644 --- a/reference/configuration/framework.rst +++ b/reference/configuration/framework.rst @@ -135,8 +135,7 @@ trusted_proxies **type**: ``array`` -Configures the IP addresses that should be trusted as proxies. It becomes the -service container parameter called ``kernel.trusted_proxies``. +Configures the IP addresses that should be trusted as proxies. .. seealso:: @@ -211,14 +210,14 @@ test **type**: ``boolean`` -If this configuration parameter 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 +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:`/book/testing`. + For more information, see :doc:`/book/testing`. default_locale ~~~~~~~~~~~~~~ @@ -226,8 +225,7 @@ default_locale **type**: ``string`` **default**: ``'en'`` The default locale is used if no ``_locale`` routing parameter has been set. It -becomes the service container parameter named ``kernel.default_locale`` and it -is also available with the +is available with the :method:`Request::getDefaultLocale ` method. @@ -252,14 +250,13 @@ might have been manipulated by an attacker. 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. +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:: @@ -293,8 +290,8 @@ response. 'trusted_hosts' => array('acme.com', 'acme.org'), )); -Hosts can also be configured using regular expressions (e.g. -``.*\.?acme.com$``), which make it easier to respond to any subdomain. +Hosts can also be configured using regular expressions (e.g. ``.*\.?acme.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:: @@ -349,8 +346,7 @@ enabled **type**: ``boolean`` **default**: ``true`` Whether to enable the CSRF support in forms or not. Setting this option to -``true`` requires the `secret`_ to be set and `session`_ to be enabled. It -becomes the service container parameter named ``form.type_extension.csrf.enabled``. +``true`` requires the `secret`_ to be set and `session`_ to be enabled. This option will automatically be set to ``true`` when one of the child settings is configured. @@ -364,8 +360,7 @@ field_name **type**: ``string`` **default**: ``'_token'`` -The name of the hidden field containing the CSRF token in the form. It becomes -the service container parameter named ``form.type_extension.csrf.field_name``. +The name of the hidden field containing the CSRF token in the form. esi ~~~ @@ -444,8 +439,7 @@ path **type**: ``string`` **default**: ``'/_fragment'`` The path prefix for fragments. The fragment listener will only be executed -when the request starts with this path. It becomes the service container -parameter called ``fragment.path``. +when the request starts with this path. profiler ~~~~~~~~ @@ -469,8 +463,8 @@ and ``test`` environments. .. note:: The profiler works independently from the Web Developer Toolbar, see the - :doc:`WebProfilerBundle configuration - ` on how to disable/enable it. + :doc:`WebProfilerBundle configuration ` + on how to disable/enable the toolbar. collect ....... @@ -484,9 +478,10 @@ collect **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. If you want to only -collect information on-demand, you can set the ``collect`` flag to ``false`` -and activate the data collectors manually:: +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(); @@ -496,8 +491,7 @@ 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. It becomes the service -container parameter called ``profiler_listener.only_exceptions``. +exception is thrown during the handling of the request. only_master_requests .................... @@ -505,42 +499,33 @@ 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). It becomes the service container -parameter called ``profiler_listener.only_master_requests``. +requests (and not on the subrequests). dsn ... **type**: ``string`` **default**: ``'file:%kernel.cache_dir%/profiler'`` -The DSN where to save the profiling information. The supported drivers (part -before the colon) are: +The DSN where to store the profiling information. -* file -* sqlite -* mysql -* mongodb -* memcache -* memcached -* redis +.. seealso:: -It becomes the service container parameter called ``profiler.storage.dsn``. + See :doc:`/cookbook/profiler/storage` for more information about the + profiler storage. username ........ **type**: ``string`` **default**: ``''`` -When needed, the username for the profiling storage. It becomes the service -container parameter called ``profiler.storage.username``. +When needed, the username for the profiling storage. password ........ **type**: ``string`` **default**: ``''`` -When needed, the password for the profiling storage. It becomes the service -container parameter called ``profiler.storage.password``. +When needed, the password for the profiling storage. lifetime ........ @@ -548,15 +533,13 @@ lifetime **type**: ``integer`` **default**: ``86400`` The lifetime of the profiling storage in seconds. The data will be deleted when -the lifetime is expired. It becomes the service container parameter called -``profiler.storage.lifetime``. - +the lifetime is expired. matcher ....... Matcher options are configured to dynamically enable the profiler. For -instance, based on `ip`_ or :ref:`path `. +instance, based on the `ip`_ or :ref:`path `. .. seealso:: @@ -597,8 +580,6 @@ resource The path the main routing resource (e.g. a YAML file) that contains the routes and imports the router should load. -It becomes the service container parameter called ``router.resource``. - type .... @@ -615,8 +596,6 @@ http_port The port for normal http requests (this is used when matching the scheme). -It becomes the service container parameter called ``router.resource``. - https_port .......... @@ -650,14 +629,6 @@ The value can be one of: session ~~~~~~~ -storage_id -.......... - -**type**: ``string`` **default**: ``'session.storage.native'`` - -The service id used for session storage. The ``session.storage`` service alias -will be set to this service id. - handler_id .......... @@ -669,23 +640,38 @@ 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:`/cookbook/configuration/pdo_session_storage`. + +storage_id +.......... + +**type**: ``string`` **default**: ``'session.storage.native'`` + +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`. + 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. +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. It will use ``null`` by -default, which means ``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. +This determines the lifetime of the session - in seconds. It will use ``null`` +by default, which means ``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 ........... @@ -910,8 +896,7 @@ hinclude_default_template **type**: ``string`` **default**: ``null`` Sets the content shown during the loading of the fragment or when JavaScript is -disabled. This can be either a template name or the content itself. It becomes -the service container parameter named ``fragment.renderer.hinclude.global_template``. +disabled. This can be either a template name or the content itself. .. seealso:: @@ -1019,8 +1004,7 @@ cache **type**: ``string`` The path to the cache directory for templates. When this is not set, caching is -disabled. It becomes the service container parameter named -``templating.loader.cache.path``. +disabled. engines ....... @@ -1028,8 +1012,7 @@ engines **type**: ``string[]`` / ``string`` **required** The Templating Engine to use. This can either be a string (when only one engine -is configured) or an array of engines. It becomes the service container -parameter named ``templating.engines``. +is configured) or an array of engines. At least one engine is required.