.. index::
single: Configuration reference; 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 must 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.
type: string required
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.
In practice, Symfony uses this value for encrypting the cookies used in the :doc:`remember me functionality </security/remember_me>` and for creating signed URIs when using :ref:`ESI (Edge Side Includes) <edge-side-includes>`.
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.
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.
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 <Symfony\\Component\\HttpFoundation\\Request::enableHttpMethodParameterOverride>`
method gets called automatically. It becomes the service container parameter
named kernel.http_method_override.
.. seealso::
For more information, see :doc:`/form/action_method`.
Caution!
If you're using the :ref:`AppCache Reverse Proxy <symfony2-reverse-proxy>`
with this option, the kernel will ignore the _method parameter,
which could lead to errors.
To fix this, invoke the enableHttpMethodParameterOverride() method
before creating the Request object:
// web/app.php // ... $kernel = new AppCache($kernel); Request::enableHttpMethodParameterOverride(); // <-- add this line $request = Request::createFromGlobals(); // ...
The trusted_proxies option was removed in Symfony 3.3. See :doc:`/request/load_balancer_reverse_proxy`.
type: string default: null
Symfony turns file paths seen in variable dumps and exception messages into
links that open those files right inside your browser. If you prefer to open
those files in your favorite IDE or text editor, set this option to any of the
following values: phpstorm, sublime, textmate, macvim and emacs.
Note
The phpstorm option is supported natively by PhpStorm on MacOS,
Windows requires PhpStormProtocol and Linux requires phpstorm-url-handler.
If you use another editor, the expected configuration value is a URL template
that contains an %f placeholder where the file path is expected and %l
placeholder for the line number (percentage signs (%) must be escaped by
doubling them to prevent Symfony from interpreting them as container parameters).
.. configuration-block::
.. code-block:: yaml
# app/config/config.yml
framework:
ide: 'myide://open?url=file://%%f&line=%%l'
.. code-block:: xml
<!-- app/config/config.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:framework="http://symfony.com/schema/dic/symfony"
xsi:schemaLocation="http://symfony.com/schema/dic/services
http://symfony.com/schema/dic/services/services-1.0.xsd
http://symfony.com/schema/dic/symfony http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
<framework:config ide="myide://open?url=file://%%f&line=%%l" />
</container>
.. code-block:: php
// app/config/config.php
$container->loadFromExtension('framework', array(
'ide' => 'myide://open?url=file://%%f&line=%%l',
));
Since every developer uses a different IDE, the recommended way to enable this
feature is to configure it on a system level. This can be done by setting the
xdebug.file_link_format option in your php.ini configuration file. The
format to use is the same as for the framework.ide option, but without the
need to escape the percent signs (%) by doubling them.
Note
If both framework.ide and xdebug.file_link_format are defined,
Symfony uses the value of the framework.ide option.
Tip
Setting the xdebug.file_link_format ini option works even if the Xdebug
extension is not enabled.
Tip
When running your app in a container or in a virtual machine, you can tell
Symfony to map files from the guest to the host by changing their prefix.
This map should be specified at the end of the URL template, using & and
> as guest-to-host separators:
// /path/to/guest/.../file will be opened // as /path/to/host/.../file on the host // and /foo/.../file as /bar/.../file also 'myide://%f:%l&/path/to/guest/>/path/to/host/&/foo/>/bar/&...'
.. versionadded:: 3.2
Guest to host mappings were introduced in Symfony 3.2.
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`.
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 <Symfony\\Component\\HttpFoundation\\Request::getDefaultLocale>`
method.
.. seealso::
You can read more information about the default locale in
:ref:`translation-default-locale`.
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() <Symfony\\Component\\HttpFoundation\\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 400 response.
.. configuration-block::
.. code-block:: yaml
# app/config/config.yml
framework:
trusted_hosts: ['example.com', 'example.org']
.. code-block:: xml
<!-- app/config/config.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:framework="http://symfony.com/schema/dic/symfony"
xsi:schemaLocation="http://symfony.com/schema/dic/services
http://symfony.com/schema/dic/services/services-1.0.xsd
http://symfony.com/schema/dic/symfony http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
<framework:config>
<framework:trusted-host>example.com</framework:trusted-host>
<framework:trusted-host>example.org</framework:trusted-host>
<!-- ... -->
</framework:config>
</container>
.. 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`_.
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`.
.. seealso::
For more information about CSRF protection in forms, see :doc:`/form/csrf_protection`.
type: boolean default: true if form support is enabled, false
otherwise
This option can be used to disable CSRF protection on all forms. But you can also :ref:`disable CSRF protection on individual forms <form-disable-csrf>`.
If you're using forms, but want to avoid starting your session (e.g. using
forms in an API-only website), csrf_protection will need to be set to
false.
.. seealso::
You can read more about Edge Side Includes (ESI) in :ref:`edge-side-includes`.
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::
.. code-block:: yaml
# app/config/config.yml
framework:
esi: true
.. code-block:: xml
<!-- app/config/config.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:framework="http://symfony.com/schema/dic/symfony"
xsi:schemaLocation="http://symfony.com/schema/dic/services
http://symfony.com/schema/dic/services/services-1.0.xsd
http://symfony.com/schema/dic/symfony http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
<framework:config>
<framework:esi />
</framework:config>
</container>
.. code-block:: php
// app/config/config.php
$container->loadFromExtension('framework', array(
'esi' => true,
));
.. seealso::
Learn more about fragments in the
:ref:`HTTP Cache article <http_cache-fragments>`.
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.
type: string default: '/_fragment'
The path prefix for fragments. The fragment listener will only be executed when the request starts with this path.
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 </reference/configuration/web_profiler>` on how to disable/enable the toolbar.
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();
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.
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).
type: string default: 'file:%kernel.cache_dir%/profiler'
The DSN where to store the profiling information.
.. seealso::
See :doc:`/profiler/storage` for more information about the
profiler storage.
Matcher options are configured to dynamically enable the profiler. For instance, based on the ip or :ref:`path <reference-profiler-matcher-path>`.
.. seealso::
See :doc:`/profiler/matchers` for more information about using
matchers to enable/disable the profiler.
type: string
If set, the profiler will only be enabled when the current IP address matches.
type: string
If set, the profiler will only be enabled when the current path matches.
type: string
This setting contains the service id of a custom matcher.
type: string required
The path the main routing resource (e.g. a YAML file) that contains the routes and imports the router should load.
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).
type: integer default: 80
The port for normal http requests (this is used when matching the scheme).
type: integer default: 443
The port for https requests (this is used when matching the scheme).
type: mixed default: true
Determines the routing generator behaviour. When generating a route that has specific :doc:`requirements </routing/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;
false- Disable exceptions when the requirements are not met and return
nullinstead; 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.
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`.
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`.
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.
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.
type: string default: /
This determines the path to set in the session cookie. By default it will
use /.
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.
type: boolean default: false
This determines whether cookies should only be sent over secure connections.
type: boolean default: true
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: integer default: 100
See 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.
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.
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
<!-- app/config/config.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:framework="http://symfony.com/schema/dic/symfony"
xsi:schemaLocation="http://symfony.com/schema/dic/services
http://symfony.com/schema/dic/services/services-1.0.xsd
http://symfony.com/schema/dic/symfony http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
<framework:config>
<framework:session save-path="null" />
</framework:config>
</container>
.. code-block:: php
// app/config/config.php
$container->loadFromExtension('framework', array(
'session' => array(
'save_path' => null,
),
));
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
<!-- app/config/config.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:framework="http://symfony.com/schema/dic/symfony"
xsi:schemaLocation="http://symfony.com/schema/dic/services
http://symfony.com/schema/dic/services/services-1.0.xsd
http://symfony.com/schema/dic/symfony http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
<framework:config>
<framework:assets base-path="/images" />
</framework:config>
</container>
.. code-block:: php
// app/config/config.php
$container->loadFromExtension('framework', array(
// ...
'assets' => array(
'base_path' => '/images',
),
));
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::
.. code-block:: yaml
# app/config/config.yml
framework:
# ...
assets:
base_urls:
- 'http://cdn.example.com/'
.. code-block:: xml
<!-- app/config/config.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:framework="http://symfony.com/schema/dic/symfony"
xsi:schemaLocation="http://symfony.com/schema/dic/services
http://symfony.com/schema/dic/services/services-1.0.xsd
http://symfony.com/schema/dic/symfony http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
<framework:config>
<framework:assets base-url="http://cdn.example.com/" />
</framework:config>
</container>
.. code-block:: php
// app/config/config.php
$container->loadFromExtension('framework', array(
// ...
'assets' => array(
'base_urls' => array('http://cdn.example.com/'),
),
));
You can group assets into packages, to specify different base URLs for them:
.. configuration-block::
.. code-block:: yaml
# app/config/config.yml
framework:
# ...
assets:
packages:
avatars:
base_urls: 'http://static_cdn.example.com/avatars'
.. code-block:: xml
<!-- app/config/config.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:framework="http://symfony.com/schema/dic/symfony"
xsi:schemaLocation="http://symfony.com/schema/dic/services
http://symfony.com/schema/dic/services/services-1.0.xsd
http://symfony.com/schema/dic/symfony http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
<framework:config>
<framework:assets>
<framework:package
name="avatars"
base-url="http://static_cdn.example.com/avatars" />
</framework:assets>
</framework:config>
</container>
.. code-block:: php
// app/config/config.php
$container->loadFromExtension('framework', array(
// ...
'assets' => 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+twig
<img src="{{ asset('...', 'avatars') }}">
.. code-block:: html+php
<img src="<?php echo $view['assets']->getUrl('...', 'avatars') ?>">
Each package can configure the following options:
- :ref:`base_path <reference-assets-base-path>`
- :ref:`base_urls <reference-assets-base-urls>`
- :ref:`version_strategy <reference-assets-version-strategy>`
- :ref:`version <reference-framework-assets-version>`
- :ref:`version_format <reference-assets-version-format>`
type: string
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.
For example, suppose you have the following:
.. configuration-block::
.. code-block:: html+twig
<img src="{{ asset('images/logo.png') }}" alt="Symfony!" />
.. code-block:: php
<img src="<?php echo $view['assets']->getUrl('images/logo.png') ?>" alt="Symfony!" />
By default, this will render a path to your image such as /images/logo.png.
Now, activate the version option:
.. configuration-block::
.. code-block:: yaml
# app/config/config.yml
framework:
# ...
assets:
version: 'v2'
.. code-block:: xml
<!-- app/config/config.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:framework="http://symfony.com/schema/dic/symfony"
xsi:schemaLocation="http://symfony.com/schema/dic/services
http://symfony.com/schema/dic/services/services-1.0.xsd
http://symfony.com/schema/dic/symfony http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
<framework:config>
<framework:assets version="v2" />
</framework:config>
</container>
.. code-block:: php
// app/config/config.php
$container->loadFromExtension('framework', array(
// ...
'assets' => array(
'version' => 'v2',
),
));
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.
Note
This parameter cannot be set at the same time as version_strategy.
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.
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.
type: string default: null
The service id of the :doc:`asset version strategy </frontend/custom_version_strategy>` applied to the assets. This option can be set globally for all assets and individually for each asset package:
.. configuration-block::
.. code-block:: yaml
# app/config/config.yml
framework:
assets:
# this strategy is applied to every asset (including packages)
version_strategy: 'app.asset.my_versioning_strategy'
packages:
foo_package:
# this package removes any versioning (its assets won't be versioned)
version: ~
bar_package:
# this package uses its own strategy (the default strategy is ignored)
version_strategy: 'app.asset.another_version_strategy'
baz_package:
# this package inherits the default strategy
base_path: '/images'
.. code-block:: xml
<!-- app/config/config.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:framework="http://symfony.com/schema/dic/symfony"
xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd
http://symfony.com/schema/dic/symfony http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
<framework:config>
<framework:assets version-strategy="app.asset.my_versioning_strategy">
<!-- this package removes any versioning (its assets won't be versioned) -->
<framework:package
name="foo_package"
version="null" />
<!-- this package uses its own strategy (the default strategy is ignored) -->
<framework:package
name="bar_package"
version-strategy="app.asset.another_version_strategy" />
<!-- this package inherits the default strategy -->
<framework:package
name="baz_package"
base_path="/images" />
</framework:assets>
</framework:config>
</container>
.. code-block:: php
// app/config/config.php
$container->loadFromExtension('framework', array(
'assets' => array(
'version_strategy' => 'app.asset.my_versioning_strategy',
'packages' => array(
'foo_package' => array(
// this package removes any versioning (its assets won't be versioned)
'version' => null,
),
'bar_package' => array(
// this package uses its own strategy (the default strategy is ignored)
'version_strategy' => 'app.asset.another_version_strategy',
),
'baz_package' => array(
// this package inherits the default strategy
'base_path' => '/images',
),
),
),
));
Note
This parameter cannot be set at the same time as version.
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.
.. seealso::
See :doc:`/templating/hinclude` for more information about hinclude.
type: string[] default: ['FrameworkBundle:Form']
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 article <forms-theming-twig>`.
Assume 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
<!-- app/config/config.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:framework="http://symfony.com/schema/dic/symfony"
xsi:schemaLocation="http://symfony.com/schema/dic/services
http://symfony.com/schema/dic/services/services-1.0.xsd
http://symfony.com/schema/dic/symfony http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
<framework:config>
<framework:templating>
<framework:form>
<framework:resource>WebsiteBundle:Form</framework:resource>
</framework:form>
</framework:templating>
</framework:config>
</container>
.. 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.
.. seealso::
See :ref:`forms-theming-global` for more information.
type: string
The path to the cache directory for templates. When this is not set, caching is disabled.
Note
When using Twig templating, the caching is already handled by the TwigBundle and doesn't need to be enabled for the FrameworkBundle.
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.
At least one engine is required.
type: string[]
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
Whether or not to enable the translator service in the service container.
type: string|array default: array('en')
This option is used when the translation key for the current locale wasn't found.
.. seealso::
For more details, see :doc:`/translation`.
default: true when the debug mode is enabled, false otherwise.
When true, a log entry is made whenever the translator cannot find a translation
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.
type: array default: []
This option allows to define an array of paths where the component will look for translation files.
type: boolean default: false
When enabled, the property_accessor service uses PHP's
:ref:`magic __call() method <components-property-access-magic-call>` when
its getValue() method is called.
type: boolean default: false
When enabled, the property_accessor service throws an exception when you
try to access an invalid index of an array.
type: boolean default: true if :ref:`form support is enabled <reference-form-enabled>`,
false otherwise
Whether or not to enable validation support.
This option will automatically be set to true when one of the child
settings is configured.
type: string
The service that is used to persist class metadata in a cache. The service has to implement the :class:`Symfony\\Component\\Validator\\Mapping\\Cache\\CacheInterface`.
Set this option to validator.mapping.cache.doctrine.apc to use the APC
cache provide from the Doctrine project.
type: boolean default: false
If this option is enabled, validation constraints can be defined using annotations.
type: string default: validators
The translation domain that is used when translating validation constraint error messages.
type: Boolean default: false
If this option is enabled, the egulias/email-validator library will be used by the :doc:`/reference/constraints/Email` constraint validator. Otherwise, the validator uses a simple regular expression to validate email addresses.
type: array default: []
This option allows to define an array of paths with files or directories where the component will look for additional validation files.
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
type: string default: '%kernel.cache_dir%/annotations'
The directory to store cache files for annotations, in case
annotations.cache is set to 'file'.
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.
type: boolean default: false
Whether to enable the serializer service or not in the service container.
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`.
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`.
type: string
The name converter to use.
The :class:`Symfony\\Component\\Serializer\\NameConverter\\CamelCaseToSnakeCaseNameConverter`
name converter can enabled by using the serializer.name_converter.camel_case_to_snake_case
value.
.. seealso::
For more information, see
:ref:`component-serializer-converting-property-names-when-serializing-and-deserializing`.
type string
The service id that is used as the circular reference handler of the default
serializer. The service has to implement the magic __invoke($object)
method.
.. seealso::
For more information, see
:ref:`component-serializer-handling-circular-references`.
.. versionadded:: 3.2
The ``log`` option was introduced in Symfony 3.2.
type: boolean default: false
Use the application logger instead of the PHP logger for logging PHP errors.
.. versionadded:: 3.2
The ``throw`` option was introduced in Symfony 3.2.
type: boolean default: %kernel.debug%
Throw PHP errors as \ErrorException instances. The parameter
debug.error_handler.throw_at controls the threshold.
type: string default: cache.adapter.filesystem
The cache adapter used by the cache.app service. The FrameworkBundle
ships with multiple adapters: apcu, doctrine, system, filesystem,
psr6 and redis.
Tip
It might be tough to understand at the beginning, so to avoid confusion remember that all pools perform the same actions but on different medium given the adapter they are based on. Internally, a pool wraps the definition of an adapter.
type: string default: cache.adapter.system
The cache adapter used by the cache.system service.
type: string default: %kernel.cache_dir%/pools
The path to the cache directory used by services inheriting from the
cache.adapter.filesystem adapter (including cache.app).
type: string
The service name to use as your default Doctrine provider. The provider is
available as the cache.doctrine service.
type: string
The service name to use as your default PSR-6 provider. It is available as
the cache.psr6 service.
type: string default: redis://localhost
The DSN to use by the Redis provider. The provider is available as the cache.redis
service.
type: array
A list of cache pools to be created by the framework extension.
.. seealso::
For more information about how pools works, see :ref:`cache pools <component-cache-cache-pools>`.
type: prototype
Name of the pool you want to create.
Note
Your pool name must differ from cache.app or cache.system.
type: string default: cache.app
The name of the adapter to use. You could also use your own implementation.
Note
Your service MUST implement the :class:`Psr\\Cache\\CacheItemPoolInterface` interface.
type: boolean default: false
Whether your service should be public or not.
type: integer
Default lifetime of your cache items in seconds.
type: string
The service name to use as provider when the specified adapter needs one.
type: string
The cache clearer used to clear your PSR-6 cache.
.. seealso::
For more information, see :class:`Symfony\\Component\\HttpKernel\\CacheClearer\\Psr6CacheClearer`.
.. versionadded:: 3.2
The ``prefix_seed`` option was introduced in Symfony 3.2.
type: string default: null
If defined, this value is used as part of the "namespace" generated for the
cache item keys. A common practice is to use the unique name of the application
(e.g. symfony.com) because that prevents naming collisions when deploying
multiple applications into the same path (on different servers) that share the
same cache backend.
It's also useful when using blue/green deployment strategies and more generally, when you need to abstract out the actual deployment directory (for example, when warming caches offline).
.. configuration-block::
.. code-block:: yaml
framework:
secret: ~
http_method_override: true
trusted_proxies: []
ide: ~
test: ~
default_locale: en
csrf_protection:
enabled: false
# form configuration
form:
enabled: false
csrf_protection:
enabled: true
field_name: ~
# 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
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
cache: ~
name_converter: ~
circular_reference_handler: ~
# assets configuration
assets:
base_path: ~
base_urls: []
version: ~
version_format: '%%s?%%s'
packages:
# Prototype
name:
base_path: ~
base_urls: []
version: ~
version_format: '%%s?%%s'
# templating configuration
templating:
hinclude_default_template: ~
form:
resources:
# Default:
- FrameworkBundle:Form
cache: ~
engines: # Required
# Example:
- twig
loaders: []
# translator configuration
translator:
enabled: false
fallbacks: [en]
logging: "%kernel.debug%"
paths: []
# validation configuration
validation:
enabled: false
cache: ~
enable_annotations: false
translation_domain: validators
mapping:
paths: []
# annotation configuration
annotations:
cache: file
file_cache_dir: '%kernel.cache_dir%/annotations'
debug: '%kernel.debug%'
# PHP errors handling configuration
php_errors:
log: false
throw: '%kernel.debug%'
# cache configuration
cache:
app: cache.app
system: cache.system
directory: '%kernel.cache_dir%/pools'
default_doctrine_provider: ~
default_psr6_provider: ~
default_redis_provider: 'redis://localhost'
pools:
# Prototype
name:
adapter: cache.app
public: false
default_lifetime: ~
provider: ~
clearer: ~