FrameworkBundle Configuration ("framework")

The FrameworkBundle defines the main framework configuration, from sessions and
translations to forms, validation, routing and more. All these options are
configured under the framework key in your application configuration.

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.

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.

This determines whether the _method request parameter is used as the
intended HTTP method on POST requests. If enabled, the
Request::enableHttpMethodParameterOverride
method gets called automatically. It becomes the service container parameter
named kernel.http_method_override.

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, emacs
and atom.

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).

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 xdebug.file_link_format 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/&...'

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
config/packages/test/framework.yaml).

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.

The Symfony 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.

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.

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:

In practice, this is important because Symfony uses it to automatically set the
Content-Type header on the Response (if you don't explicitly set one).
If you pass an array of mime types, the first will be used for the header.

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.

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.

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.

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.

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.

This specifies a 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 Service 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.

The service id of the asset version strategy
applied to the assets. This option can be set globally for all assets and
individually for each asset package:

YAML

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

# config/packages/framework.yamlframework: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 strategybase_path:'/images'

// config/packages/framework.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 or json_manifest_path.

The file path to a manifest.json file containing an associative array of asset
names and their respective compiled names. A common cache-busting technique using
a "manifest" file works by writing out assets with a "hash" appended to their
file names (e.g. main.ae433f1cb.css) during a front-end compilation routine.

This option can be set globally for all assets and individually for each asset
package:

YAML

1
2
3
4
5
6
7
8
9
10
11
12

# config/packages/framework.yamlframework:assets:# this manifest is applied to every asset (including packages)json_manifest_path:"%kernel.project_dir%/public/build/manifest.json"packages:foo_package:# this package uses its own manifest (the default file is ignored)json_manifest_path:"%kernel.project_dir%/public/build/a_different_manifest.json"bar_package:# this package uses the global manifest (the default file is used)base_path:'/images'

XML

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

<!-- config/packages/framework.xml --><?xml version="1.0" encoding="UTF-8" ?><containerxmlns="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><!-- this manifest is applied to every asset (including packages) --><framework:assetsjson-manifest-path="%kernel.project_dir%/public/build/manifest.json"><!-- this package uses its own manifest (the default file is ignored) --><framework:packagename="foo_package"json-manifest-path="%kernel.project_dir%/public/build/a_different_manifest.json"/><!-- this package uses the global manifest (the default file is used) --><framework:packagename="bar_package"base-path="/images"/></framework:assets></framework:config></container>

PHP

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

// config/packages/framework.php$container->loadFromExtension('framework',array('assets'=>array(// this manifest is applied to every asset (including packages)'json_manifest_path'=>'%kernel.project_dir%/public/build/manifest.json','packages'=>array('foo_package'=>array(// this package uses its own manifest (the default file is ignored)'json_manifest_path'=>'%kernel.project_dir%/public/build/a_different_manifest.json',),'bar_package'=>array(// this package uses the global manifest (the default file is used)'base_path'=>'/images',),),),));

Note

This parameter cannot be set at the same time as version or version_strategy.
Additionally, this option cannot be nullified at the package scope if a global manifest
file is specified.

Tip

If you request an asset that is not found in the manifest.json file, the original -
unmodified - asset path will be returned.

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 LoaderInterface.

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.

New in version 4.1: The email_validation_mode option was introduced in Symfony 4.1.

It controls the way email addresses are validated by the
Email validator. The possible values are:

loose, it uses a simple regular expression to validate the address (it
checks that at least one @ character is present, etc.). This validation is
too simple and it's recommended to use the html5 validation instead;

html5, it validates email addresses using the same regular expression
defined in the HTML5 standard, making the backend validation consistent with
the one provided by browsers;

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.

The cache adapter used by the cache.app service. The FrameworkBundle
ships with multiple adapters: cache.adapter.apcu, cache.adapter.doctrine,
cache.adapter.system, cache.adapter.filesystem, cache.adapter.psr6,
cache.adapter.redis and cache.adapter.memcached.

There's also a special adapter called cache.adapter.array which stores
contents in memory using a PHP array and it's used to disable caching (mostly on
the dev environment).

New in version 4.1: The cache.adapter.array adapter was introduced in Symfony 4.1.

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.

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).