Framework Configuration Reference (FrameworkBundle)¶

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.

# displays the default config values defined by Symfony
$ php bin/console config:dump-reference framework

# displays the actual config values used by your application
$ php bin/console debug:config framework

Note

When using XML, you must use the http://symfony.com/schema/dic/symfony namespace and the related XSD schema is available at: https://symfony.com/schema/dic/symfony/symfony-1.0.xsd

Configuration¶

annotations
- cache
- debug
- file_cache_dir
assets
- base_path
- base_urls
- json_manifest_path
- packages
- version_format
- version_strategy
- version
cache
- app
- default_doctrine_provider
- default_memcached_provider
- default_pdo_provider
- default_psr6_provider
- default_redis_provider
- directory
- pools
  - name
    - adapter
    - clearer
    - default_lifetime
    - provider
    - public
    - tags
- prefix_seed
- system
csrf_protection
- enabled
default_locale
disallow_search_engine_index
error_controller
esi
- enabled
form
- enabled
fragments
- enabled
- hinclude_default_template
- path
http_client
- default_options
  - bindto
  - buffer
  - cafile
  - capath
  - ciphers
  - headers
  - http_version
  - local_cert
  - local_pk
  - max_redirects
  - no_proxy
  - passphrase
  - peer_fingerprint
  - proxy
  - resolve
  - timeout
  - max_duration
  - verify_host
  - verify_peer
- max_host_connections
- scoped_clients
  - scope
  - auth_basic
  - auth_bearer
  - auth_ntlm
  - base_uri
  - bindto
  - buffer
  - cafile
  - capath
  - ciphers
  - headers
  - http_version
  - local_cert
  - local_pk
  - max_redirects
  - no_proxy
  - passphrase
  - peer_fingerprint
  - proxy
  - query
  - resolve
  - timeout
  - max_duration
  - verify_host
  - verify_peer
http_method_override
ide
lock
- enabled
- resources
  - name
php_errors
- log
- throw
profiler
- collect
- dsn
- enabled
- only_exceptions
- only_master_requests
property_access
- magic_call
- throw_exception_on_invalid_index
- throw_exception_on_invalid_property_path
property_info
- enabled
request:
- formats
router
- http_port
- https_port
- resource
- strict_requirements
- type
- utf8
secret
serializer
- circular_reference_handler
- enable_annotations
- enabled
- mapping
  - paths
- name_converter
session
- cache_limiter
- cookie_domain
- cookie_httponly
- cookie_lifetime
- cookie_path
- cookie_samesite
- cookie_secure
- enabled
- gc_divisor
- gc_maxlifetime
- gc_probability
- handler_id
- metadata_update_threshold
- name
- save_path
- sid_length
- sid_bits_per_character
- storage_id
- use_cookies
test
translator
- cache_dir
- default_path
- enabled
- enabled_locales
- fallbacks
- formatter
- logging
- paths
trusted_hosts
trusted_proxies
validation
- cache
- email_validation_mode
- enable_annotations
- enabled
- mapping
  - paths
- not_compromised_password
  - enabled
  - endpoint
- static_method
- translation_domain
workflows
- enabled
- name

secret¶

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 remember me functionality and for creating signed URIs when using ESI (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.

http_method_override¶

type: boolean default: true

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.

See also

Changing the Action and HTTP Method of Symfony forms.

Caution

If you’re using the HttpCache 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:

// public/index.php

// ...
$kernel = new CacheKernel($kernel);

Request::enableHttpMethodParameterOverride(); // <-- add this line
$request = Request::createFromGlobals();
// ...

trusted_proxies¶

The trusted_proxies option was removed in Symfony 3.3. See How to Configure Symfony to Work behind a Load Balancer or a Reverse Proxy.

ide¶

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

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

YAML

# config/packages/framework.yaml
framework:
    ide: 'myide://open?url=file://%%f&line=%%l'

XML

<!-- config/packages/framework.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
        https://symfony.com/schema/dic/services/services-1.0.xsd
        http://symfony.com/schema/dic/symfony https://symfony.com/schema/dic/symfony/symfony-1.0.xsd">

    <framework:config ide="myide://open?url=file://%%f&line=%%l"/>
</container>

PHP

// config/packages/framework.php
$container->loadFromExtension('framework', [
    '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 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 /var/www/app/ as /projects/my_project/ also
'myide://%%f:%%l&/path/to/guest/>/path/to/host/&/var/www/app/>/projects/my_project/&...'

// example for PhpStorm
'phpstorm://open?file=%%f&line=%%l&/var/www/app/>/projects/my_project/'

test¶

type: boolean

If this configuration setting is present (and not false), then the services related to testing your application (e.g. test.client) are loaded. This setting should be present in your test environment (usually via config/packages/test/framework.yaml).

See also

For more information, see Testing.

default_locale¶

type: string default: en

The default locale is used if no _locale routing parameter has been set. It is available with the Request::getDefaultLocale method.

See also

You can read more information about the default locale in Setting a Default Locale.

disallow_search_engine_index¶

type: boolean default: true when the debug mode is enabled, false otherwise.

If true, Symfony adds a X-Robots-Tag: noindex HTTP tag to all responses (unless your own app adds that header, in which case it’s not modified). This X-Robots-Tag HTTP header tells search engines to not index your web site. This option is a protection measure in case you accidentally publish your site in debug mode.

trusted_hosts¶

type: array | string default: []

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.

See also

You can read “HTTP Host header attacks” for more information about these kinds of attacks.

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 of the regular expressions in this list, the application won’t respond and the user will receive a 400 response.

YAML

# config/packages/framework.yaml
framework:
    trusted_hosts:  ['^example\.com$', '^example\.org$']

XML

<!-- config/packages/framework.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
        https://symfony.com/schema/dic/services/services-1.0.xsd
        http://symfony.com/schema/dic/symfony https://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>

PHP

// config/packages/framework.php
$container->loadFromExtension('framework', [
    'trusted_hosts' => ['^example\.com$', '^example\.org$'],
]);

Hosts can also be configured to respond to any subdomain, via ^(.+\.)?example\.com$ for instance.

In addition, you can also set the trusted hosts in the front controller using the Request::setTrustedHosts() method:

// public/index.php
Request::setTrustedHosts(['^(.+\.)?example\.com$', '^(.+\.)?example\.org$']);

The default value for this option is an empty array, meaning that the application can respond to any given host.

See also

Read more about this in the Security Advisory Blog post.

form¶

enabled¶

type: boolean default: true or false depending on your installation

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.

See also

For more details, see Forms.

csrf_protection¶

See also

For more information about CSRF protection, see How to Implement CSRF Protection.

enabled¶

type: boolean default: true or false depending on your installation

This option can be used to disable CSRF protection on all forms. But you can also disable CSRF protection on individual forms.

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.

error_controller¶

type: string default: error_controller

This is the controller that is called when an exception is thrown anywhere in your application. The default controller (ErrorController) renders specific templates under different error conditions (see How to Customize Error Pages).

esi¶

See also

You can read more about Edge Side Includes (ESI) in Working with Edge Side Includes.

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:

YAML

# config/packages/framework.yaml
framework:
    esi: true

XML

<!-- config/packages/framework.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
        https://symfony.com/schema/dic/services/services-1.0.xsd
        http://symfony.com/schema/dic/symfony https://symfony.com/schema/dic/symfony/symfony-1.0.xsd">

    <framework:config>
        <framework:esi/>
    </framework:config>
</container>

PHP

// config/packages/framework.php
$container->loadFromExtension('framework', [
    'esi' => true,
]);

fragments¶

See also

Learn more about fragments in the HTTP Cache article.

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.

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.

See also

See How to Embed Asynchronous Content with hinclude.js for more information about hinclude.

path¶

type: string default: '/_fragment'

The path prefix for fragments. The fragment listener will only be executed when the request starts with this path.

http_client¶

When the HttpClient component is installed, an HTTP client is available as a service named http_client or using the autowiring alias HttpClientInterface.

This service can be configured using framework.http_client.default_options:

# config/packages/framework.yaml
framework:
    # ...
    http_client:
        max_host_connections: 10
        default_options:
            headers: { 'X-Powered-By': 'ACME App' }
            max_redirects: 7

Multiple pre-configured HTTP client services can be defined, each with its service name defined as a key under scoped_clients. Scoped clients inherit the default options defined for the http_client service. You can override these options and can define a few others:

# config/packages/framework.yaml
framework:
    # ...
    http_client:
        scoped_clients:
            my_api.client:
                auth_bearer: secret_bearer_token
                # ...

Options defined for scoped clients apply only to URLs that match either their base_uri or the scope option when it is defined. Non-matching URLs always use default options.

Each scoped client also defines a corresponding named autowiring alias. If you use for example Symfony\Contracts\HttpClient\HttpClientInterface $myApiClient as the type and name of an argument, autowiring will inject the my_api.client service into your autowired classes.

auth_basic¶

type: string

The username and password used to create the Authorization HTTP header used in HTTP Basic authentication. The value of this option must follow the format username:password.

auth_bearer¶

type: string

The token used to create the Authorization HTTP header used in HTTP Bearer authentication (also called token authentication).

auth_ntlm¶

type: string

The username and password used to create the Authorization HTTP header used in the Microsoft NTLM authentication protocol. The value of this option must follow the format username:password. This authentication mechanism requires using the cURL-based transport.

base_uri¶

type: string

URI that is merged into relative URIs, following the rules explained in the RFC 3986 standard. This is useful when all the requests you make share a common prefix (e.g. https://api.github.com/) so you can avoid adding it to every request.

Here are some common examples of how base_uri merging works in practice:

`base_uri`	Relative URI	Actual Requested URI
http://example.org	/bar	http://example.org/bar
http://example.org/foo	/bar	http://example.org/bar
http://example.org/foo	bar	http://example.org/bar
http://example.org/foo/	bar	http://example.org/foo/bar
http://example.org	http://symfony.com	http://symfony.com
http://example.org/?bar	bar	http://example.org/bar

bindto¶

type: string

A network interface name, IP address, a host name or a UNIX socket to use as the outgoing network interface.

buffer¶

type: bool | Closure

Buffering the response means that you can access its content multiple times without performing the request again. Buffering is enabled by default when the content type of the response is text/*, application/json or application/xml.

If this option is a boolean value, the response is buffered when the value is true. If this option is a closure, the response is buffered when the returned value is true (the closure receives as argument an array with the response headers).

cafile¶

type: string

The path of the certificate authority file that contains one or more certificates used to verify the other servers’ certificates.

capath¶

type: string

The path to a directory that contains one or more certificate authority files.

ciphers¶

type: string

A list of the names of the ciphers allowed for the SSL/TLS connections. They can be separated by colons, commas or spaces (e.g. 'RC4-SHA:TLS13-AES-128-GCM-SHA256').

headers¶

type: array

An associative array of the HTTP headers added before making the request. This value must use the format ['header-name' => header-value, ...].

http_version¶

type: string | null default: null

The HTTP version to use, typically '1.1' or '2.0'. Leave it to null to let Symfony select the best version automatically.

local_cert¶

type: string

The path to a file that contains the PEM formatted certificate used by the HTTP client. This is often combined with the local_pk and passphrase options.

local_pk¶

type: string

The path of a file that contains the PEM formatted private key of the certificate defined in the local_cert option.

max_host_connections¶

type: integer default: 6

Defines the maximum amount of simultaneously open connections to a single host (considering a “host” the same as a “host name + port number” pair). This limit also applies for proxy connections, where the proxy is considered to be the host for which this limit is applied.

max_redirects¶

type: integer default: 20

The maximum number of redirects to follow. Use 0 to not follow any redirection.

no_proxy¶

type: string | null default: null

A comma separated list of hosts that do not require a proxy to be reached, even if one is configured. Use the '*' wildcard to match all hosts and an empty string to match none (disables the proxy).

passphrase¶

type: string

The passphrase used to encrypt the certificate stored in the file defined in the local_cert option.

peer_fingerprint¶

type: array

When negotiating a TLS or SSL connection, the server sends a certificate indicating its identity. A public key is extracted from this certificate and if it does not exactly match any of the public keys provided in this option, the connection is aborted before sending or receiving any data.

The value of this option is an associative array of algorithm => hash (e.g ['pin-sha256' => '...']).

proxy¶

type: string | null

The HTTP proxy to use to make the requests. Leave it to null to detect the proxy automatically based on your system configuration.

query¶

type: array

An associative array of the query string values added to the URL before making the request. This value must use the format ['parameter-name' => parameter-value, ...].

resolve¶

type: array

A list of hostnames and their IP addresses to pre-populate the DNS cache used by the HTTP client in order to avoid a DNS lookup for those hosts. This option is useful to improve security when IPs are checked before the URL is passed to the client and to make your tests easier.

The value of this option is an associative array of domain => IP address (e.g ['symfony.com' => '46.137.106.254', ...]).

scope¶

type: string

For scoped clients only: the regular expression that the URL must match before applying all other non-default options. By default, the scope is derived from base_uri.

timeout¶

type: float default: depends on your PHP config

Time, in seconds, to wait for a response. If the response stales for longer, a TransportException is thrown. Its default value is the same as the value of PHP’s default_socket_timeout config option.

max_duration¶

type: float default: 0

The maximum execution time, in seconds, that the request and the response are allowed to take. A value lower than or equal to 0 means it is unlimited.

verify_host¶

type: boolean

If true, the certificate sent by other servers is verified to ensure that their common name matches the host included in the URL. This is usually combined with verify_peer to also verify the certificate authenticity.

verify_peer¶

type: boolean

If true, the certificate sent by other servers when negotiating a TLS or SSL connection is verified for authenticity. Authenticating the certificate is not enough to be sure about the server, so you should combine this with the verify_host option.

profiler¶

enabled¶

type: boolean default: false

The profiler can be enabled by setting this option to true. When you install it using Symfony Flex, the profiler is enabled in the dev and test environments.

Note

The profiler works independently from the Web Developer Toolbar, see the WebProfilerBundle configuration on how to disable/enable the toolbar.

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:

$profiler->enable();

only_exceptions¶

type: boolean default: false

When this is set to true, the profiler will only be enabled when an exception is thrown during the handling of the request.

only_master_requests¶

type: boolean default: false

When this is set to true, the profiler will only be enabled on the master requests (and not on the subrequests).

dsn¶

type: string default: 'file:%kernel.cache_dir%/profiler'

The DSN where to store the profiling information.

request¶

formats¶

type: array default: []

This setting is used to associate additional request formats (e.g. html) to one or more mime types (e.g. text/html), which will allow you to use the format & mime types to call Request::getFormat($mimeType) or Request::getMimeType($format).

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.

To configure a jsonp format:

YAML

# config/packages/framework.yaml
framework:
    request:
        formats:
            jsonp: 'application/javascript'

XML

<!-- config/packages/framework.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
        https://symfony.com/schema/dic/services/services-1.0.xsd
        http://symfony.com/schema/dic/symfony
        https://symfony.com/schema/dic/symfony/symfony-1.0.xsd">

    <framework:config>
        <framework:request>
            <framework:format name="jsonp">
                <framework:mime-type>application/javascript</framework:mime-type>
            </framework:format>
        </framework:request>
    </framework:config>
</container>

PHP

// config/packages/framework.php
$container->loadFromExtension('framework', [
    'request' => [
        'formats' => [
            'jsonp' => 'application/javascript',
        ],
    ],
]);

router¶

resource¶

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¶

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, .yaml, .php).

http_port¶

type: integer default: 80

The port for normal http requests (this is used when matching the scheme).

https_port¶

type: integer default: 443

The port for https requests (this is used when matching the scheme).

strict_requirements¶

type: mixed default: true

Determines the routing generator behavior. When generating a route that has specific parameter 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 null instead;
null: Disable checking the requirements (thus, match the route even when the requirements don’t match).

true is recommended in the development environment, while false or null might be preferred in production.

utf8¶

type: boolean default: false

Deprecated since version 5.1: Not setting this option is deprecated since Symfony 5.1. Moreover, the default value of this option will change to true in Symfony 6.0.

When this option is set to true, the regular expressions used in the requirements of route parameters will be run using the utf-8 modifier. This will for example match any UTF-8 character when using ., instead of matching only a single byte.

If the charset of your application is UTF-8 (as defined in the getCharset() method of your kernel) it’s recommended to set it to true. This will make non-UTF8 URLs to generate 404 errors.

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. This class has to implement SessionStorageInterface.

handler_id¶

type: string default: null

The service id used for session storage. The default null value means to use the native PHP session mechanism. Set it to 'session.handler.native_file' to let Symfony manage the sessions itself using files to store the session metadata. You can also store sessions in a database.

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.

cache_limiter¶

type: string or int default: ''

If set to 0, Symfony won’t set any particular header related to the cache and it will rely on the cache control method configured in the session.cache-limiter PHP.ini option.

Unlike the other session options, cache_limiter is set as a regular container parameter:

YAML

# config/services.yaml
parameters:
    session.storage.options:
        cache_limiter: 0

XML

<!-- config/services.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"
    xsi:schemaLocation="http://symfony.com/schema/dic/services
        https://symfony.com/schema/dic/services/services-1.0.xsd">

    <parameters>
        <parameter key="session.storage.options" type="collection">
            <parameter key="cache_limiter">0</parameter>
        </parameter>
    </parameters>
</container>

PHP

// config/services.php
$container->setParameter('session.storage.options', [
    'cache_limiter' => 0,
]);

gc_divisor¶

type: integer default: 100

See gc_probability.

gc_probability¶

type: integer default: 1

This defines the probability that the garbage collector (GC) process is started on every session initialization. The probability is calculated by using gc_probability / gc_divisor, e.g. 1/100 means there is a 1% chance that the GC process will start on each request.

gc_maxlifetime¶

type: integer default: 1440

This determines the number of seconds after which data will be seen as “garbage” and potentially cleaned up. Garbage collection may occur during session start and depends on gc_divisor and gc_probability.

sid_length¶

type: integer default: 32

This determines the length of session ID string, which can be an integer between 22 and 256 (both inclusive), being 32 the recommended value. Longer session IDs are harder to guess.

This option is related to the session.sid_length PHP option.

sid_bits_per_character¶

type: integer default: 4

This determines the number of bits in encoded session ID character. The possible values are 4 (0-9, a-f), 5 (0-9, a-v), and 6 (0-9, a-z, A-Z, “-“, “,”). The more bits results in stronger session ID. 5 is recommended value for most environments.

This option is related to the session.sid_bits_per_character PHP option.

save_path¶

type: string default: %kernel.cache_dir%/sessions

This determines the argument to be passed to the save handler. If you choose the default file handler, this is the path where the session files are created.

You can also set this value to the save_path of your php.ini by setting the value to null:

YAML

# config/packages/framework.yaml
framework:
    session:
        save_path: ~

XML

<!-- config/packages/framework.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
        https://symfony.com/schema/dic/services/services-1.0.xsd
        http://symfony.com/schema/dic/symfony https://symfony.com/schema/dic/symfony/symfony-1.0.xsd">

    <framework:config>
        <framework:session save-path="null"/>
    </framework:config>
</container>

PHP

// config/packages/framework.php
$container->loadFromExtension('framework', [
    'session' => [
        'save_path' => null,
    ],
]);

metadata_update_threshold¶

type: integer default: 0

This is how many seconds to wait between updating/writing the session metadata. This can be useful if, for some reason, you want to limit the frequency at which the session persists, instead of doing that on every request.

enabled¶

type: boolean default: true

Whether to enable the session support in the framework.

YAML

# config/packages/framework.yaml
framework:
    session:
        enabled: true

XML

<!-- config/packages/framework.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
        https://symfony.com/schema/dic/services/services-1.0.xsd
        http://symfony.com/schema/dic/symfony https://symfony.com/schema/dic/symfony/symfony-1.0.xsd">

    <framework:config>
        <framework:session enabled="true"/>
    </framework:config>
</container>

PHP

// config/packages/framework.php
$container->loadFromExtension('framework', [
    'session' => [
        'enabled' => true,
    ],
]);

use_cookies¶

type: boolean default: null

This specifies if the session ID is stored on the client side using cookies or not. By default, it will use the value defined in the php.ini with the session.use_cookies directive.

assets¶

base_path¶

type: string

This option allows you to define a base path to be used for assets:

YAML

# config/packages/framework.yaml
framework:
    # ...
    assets:
        base_path: '/images'

XML

<!-- config/packages/framework.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
        https://symfony.com/schema/dic/services/services-1.0.xsd
        http://symfony.com/schema/dic/symfony https://symfony.com/schema/dic/symfony/symfony-1.0.xsd">

    <framework:config>
        <framework:assets base-path="/images"/>
    </framework:config>
</container>

PHP

// config/packages/framework.php
$container->loadFromExtension('framework', [
    // ...
    'assets' => [
        'base_path' => '/images',
    ],
]);

base_urls¶

type: array

This option allows you to define base URLs to be used for assets. If multiple base URLs are provided, Symfony will select one from the collection each time it generates an asset’s path:

YAML

# config/packages/framework.yaml
framework:
    # ...
    assets:
        base_urls:
            - 'http://cdn.example.com/'

XML

<!-- config/packages/framework.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
        https://symfony.com/schema/dic/services/services-1.0.xsd
        http://symfony.com/schema/dic/symfony https://symfony.com/schema/dic/symfony/symfony-1.0.xsd">

    <framework:config>
        <framework:assets base-url="http://cdn.example.com/"/>
    </framework:config>
</container>

PHP

// config/packages/framework.php
$container->loadFromExtension('framework', [
    // ...
    'assets' => [
        'base_urls' => ['http://cdn.example.com/'],
    ],
]);

packages¶

You can group assets into packages, to specify different base URLs for them:

YAML

# config/packages/framework.yaml
framework:
    # ...
    assets:
        packages:
            avatars:
                base_urls: 'http://static_cdn.example.com/avatars'

XML

<!-- config/packages/framework.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
        https://symfony.com/schema/dic/services/services-1.0.xsd
        http://symfony.com/schema/dic/symfony https://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>

PHP

// config/packages/framework.php
$container->loadFromExtension('framework', [
    // ...
    'assets' => [
        'packages' => [
            'avatars' => [
                'base_urls' => 'http://static_cdn.example.com/avatars',
            ],
        ],
    ],
]);

Now you can use the avatars package in your templates:

<img src="{{ asset('...', 'avatars') }}">

Each package can configure the following options:

base_path
base_urls
version_strategy
version
version_format
json_manifest_path

version¶

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

For example, suppose you have the following:

<img src="{{ asset('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:

YAML

# config/packages/framework.yaml
framework:
    # ...
    assets:
        version: 'v2'

XML

<!-- config/packages/framework.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
        https://symfony.com/schema/dic/services/services-1.0.xsd
        http://symfony.com/schema/dic/symfony https://symfony.com/schema/dic/symfony/symfony-1.0.xsd">

    <framework:config>
        <framework:assets version="v2"/>
    </framework:config>
</container>

PHP

// config/packages/framework.php
$container->loadFromExtension('framework', [
    // ...
    'assets' => [
        '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 or json_manifest_path.

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.

version_format¶

type: string default: %%s?%%s

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.

version_strategy¶

type: string default: null

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

# config/packages/framework.yaml
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'

XML

<!-- config/packages/framework.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 https://symfony.com/schema/dic/services/services-1.0.xsd
        http://symfony.com/schema/dic/symfony https://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>

PHP

// config/packages/framework.php
$container->loadFromExtension('framework', [
    'assets' => [
        'version_strategy' => 'app.asset.my_versioning_strategy',
        'packages' => [
            'foo_package' => [
                // this package removes any versioning (its assets won't be versioned)
                'version' => null,
            ],
            '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',
            ],
        ],
    ],
]);

Note

This parameter cannot be set at the same time as version or json_manifest_path.

json_manifest_path¶

type: string default: null

The file path or absolute URL 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.

Tip

Symfony’s Webpack Encore supports outputting hashed assets. Moreover, this can be incorporated into many other workflows, including Webpack and Gulp using webpack-manifest-plugin and gulp-rev, respectively.

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

YAML

# config/packages/framework.yaml
framework:
    assets:
        # this manifest is applied to every asset (including packages)
        json_manifest_path: "%kernel.project_dir%/public/build/manifest.json"
        # you can use absolute URLs too and Symfony will download them automatically
        # json_manifest_path: 'https://cdn.example.com/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

<!-- config/packages/framework.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 https://symfony.com/schema/dic/services/services-1.0.xsd
        http://symfony.com/schema/dic/symfony https://symfony.com/schema/dic/symfony/symfony-1.0.xsd">

    <framework:config>
        <!-- this manifest is applied to every asset (including packages) -->
        <framework:assets json-manifest-path="%kernel.project_dir%/public/build/manifest.json">
        <!-- you can use absolute URLs too and Symfony will download them automatically -->
        <!-- <framework:assets json-manifest-path="https://cdn.example.com/manifest.json"> -->
            <!-- this package uses its own manifest (the default file is ignored) -->
            <framework:package
                name="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:package
                name="bar_package"
                base-path="/images"/>
        </framework:assets>
    </framework:config>
</container>

PHP

// config/packages/framework.php
$container->loadFromExtension('framework', [
    'assets' => [
        // this manifest is applied to every asset (including packages)
        'json_manifest_path' => '%kernel.project_dir%/public/build/manifest.json',
        // you can use absolute URLs too and Symfony will download them automatically
        // 'json_manifest_path' => 'https://cdn.example.com/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',
            ],
        ],
    ],
]);

New in version 5.1: The option to use an absolute URL in json_manifest_path was introduced in Symfony 5.1.

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.

Note

If an URL is set, the JSON manifest is downloaded on each request using the http_client.

translator¶

cache_dir¶

type: string | null default: %kernel.cache_dir%/translations/

Defines the directory where the translation cache is stored. Use null to disable this cache.

enabled¶

type: boolean default: true or false depending on your installation

Whether or not to enable the translator service in the service container.

enabled_locales¶

type: array default: [] (empty array = enable all locales)

New in version 5.1: The enabled_locales option was introduced in Symfony 5.1.

Symfony applications generate by default the translation files for validation and security messages in all locales. If your application only uses some locales, use this option to restrict the files generated by Symfony and improve performance a bit:

YAML

# config/packages/translation.yaml
framework:
    translator:
        enabled_locales: ['en', 'es']

XML

<!-- config/packages/translation.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
        https://symfony.com/schema/dic/services/services-1.0.xsd
        http://symfony.com/schema/dic/symfony https://symfony.com/schema/dic/symfony/symfony-1.0.xsd">

    <framework:config>
        <framework:translator>
            <enabled-locale>en</enabled-locale>
            <enabled-locale>es</enabled-locale>
        </framework:translator>
    </framework:config>
</container>

PHP

// config/packages/translation.php
$container->loadFromExtension('framework', [
    'translator' => [
        'enabled_locales' => ['en', 'es'],
    ],
]);

If some user makes requests with a locale not included in this option, the application won’t display any error because Symfony will display contents using the fallback locale.

fallbacks¶

type: string|array default: value of default_locale

This option is used when the translation key for the current locale wasn’t found.

See also

For more details, see Translations.

logging¶

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.

formatter¶

type: string default: translator.formatter.default

The ID of the service used to format translation messages. The service class must implement the MessageFormatterInterface.

paths¶

type: array default: []

This option allows to define an array of paths where the component will look for translation files.

default_path¶

type: string default: %kernel.project_dir%/translations

This option allows to define the path where the application translations files are stored.

property_access¶

magic_call¶

type: boolean default: false

When enabled, the property_accessor service uses PHP’s magic __call() method when its getValue() method is called.

throw_exception_on_invalid_index¶

type: boolean default: false

When enabled, the property_accessor service throws an exception when you try to access an invalid index of an array.

throw_exception_on_invalid_property_path¶

type: boolean default: true

When enabled, the property_accessor service throws an exception when you try to access an invalid property path of an object.

property_info¶

enabled¶

type: boolean default: true or false depending on your installation

validation¶

enabled¶

type: boolean default: true or false depending on your installation

Whether or not to enable validation support.

This option will automatically be set to true when one of the child settings is configured.

cache¶

type: string

The service that is used to persist class metadata in a cache. The service has to implement the CacheInterface.

Set this option to validator.mapping.cache.doctrine.apc to use the APC cache provide from the Doctrine project.

enable_annotations¶

type: boolean default: false

If this option is enabled, validation constraints can be defined using annotations.

translation_domain¶

type: string | false default: validators

The translation domain that is used when translating validation constraint error messages. Use false to disable translations.

not_compromised_password¶

The NotCompromisedPassword constraint makes HTTP requests to a public API to check if the given password has been compromised in a data breach.

enabled¶

type: boolean default: true

If you set this option to false, no HTTP requests will be made and the given password will be considered valid. This is useful when you don’t want or can’t make HTTP requests, such as in dev and test environments or in continuous integration servers.

endpoint¶

type: string default: null

By default, the NotCompromisedPassword constraint uses the public API provided by haveibeenpwned.com. This option allows to define a different, but compatible, API endpoint to make the password checks. It’s useful for example when the Symfony application is run in an intranet without public access to Internet.

static_method¶

type: string | array default: ['loadValidatorMetadata']

Defines the name of the static method which is called to load the validation metadata of the class. You can define an array of strings with the names of several methods. In that case, all of them will be called in that order to load the metadata.

email_validation_mode¶

type: string default: loose

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;
strict, it uses the egulias/email-validator library (which you must install separately) to validate the addresses according to the RFC 5322.

mapping¶

paths¶

type: array default: ['config/validation/']

This option allows to define an array of paths with files or directories where the component will look for additional validation files:

YAML

# config/packages/framework.yaml
framework:
    validation:
        mapping:
            paths:
                - "%kernel.project_dir%/config/validation/"

XML

<!-- config/packages/framework.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
        https://symfony.com/schema/dic/services/services-1.0.xsd
        http://symfony.com/schema/dic/symfony https://symfony.com/schema/dic/symfony/symfony-1.0.xsd">

    <framework:config>
        <framework:validation>
            <framework:mapping>
                <framework:path>%kernel.project_dir%/config/validation/</framework:path>
            </framework:mapping>
        </framework:validation>
    </framework:config>
</container>

PHP

// config/packages/framework.php
$container->loadFromExtension('framework', [
    'validation' => [
        'mapping' => [
            'paths' => [
                '%kernel.project_dir%/config/validation/',
            ],
        ],
    ],
]);

annotations¶

cache¶

type: string default: 'file'

This option can be one of the following values:

file: Use the filesystem to cache annotations
none: Disable the caching of annotations
a service id: A service id referencing a Doctrine Cache implementation

file_cache_dir¶

type: string default: '%kernel.cache_dir%/annotations'

The directory to store cache files for annotations, in case annotations.cache is set to 'file'.

debug¶

type: boolean default: %kernel.debug%

Whether to enable debug mode for caching. If enabled, the cache will automatically update when the original file is changed (both with code and annotation changes). For performance reasons, it is recommended to disable debug mode in production, which will happen automatically if you use the default value.

serializer¶

enabled¶

type: boolean default: true or false depending on your installation

Whether to enable the serializer service or not in the service container.

enable_annotations¶

type: boolean default: false

If this option is enabled, serialization groups can be defined using annotations.

See also

For more information, see Using Serialization Groups Annotations.

name_converter¶

type: string

The name converter to use. The CamelCaseToSnakeCaseNameConverter name converter can enabled by using the serializer.name_converter.camel_case_to_snake_case value.

See also

For more information, see Converting Property Names when Serializing and Deserializing.

circular_reference_handler¶

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.

See also

For more information, see Handling Circular References.

mapping¶

paths¶

type: array default: []

This option allows to define an array of paths with files or directories where the component will look for additional serialization files.

php_errors¶

log¶

type: boolean|int default: %kernel.debug%

Use the application logger instead of the PHP logger for logging PHP errors. When an integer value is used, it also sets the log level. Those integer values must be the same used in the error_reporting PHP option.

throw¶

type: boolean default: %kernel.debug%

Throw PHP errors as \ErrorException instances. The parameter debug.error_handler.throw_at controls the threshold.

cache¶

app¶

type: string default: cache.adapter.filesystem

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, cache.adapter.memcached and cache.adapter.pdo.

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

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.

system¶

type: string default: cache.adapter.system

The cache adapter used by the cache.system service. It supports the same adapters available for the cache.app service.

directory¶

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

default_doctrine_provider¶

type: string

The service name to use as your default Doctrine provider. The provider is available as the cache.default_doctrine_provider service.

default_psr6_provider¶

type: string

The service name to use as your default PSR-6 provider. It is available as the cache.default_psr6_provider service.

default_redis_provider¶

type: string default: redis://localhost

The DSN to use by the Redis provider. The provider is available as the cache.default_redis_provider service.

default_memcached_provider¶

type: string default: memcached://localhost

The DSN to use by the Memcached provider. The provider is available as the cache.default_memcached_provider service.

default_pdo_provider¶

type: string default: doctrine.dbal.default_connection

The service id of the database connection, which should be either a PDO or a Doctrine DBAL instance. The provider is available as the cache.default_pdo_provider service.

pools¶

type: array

A list of cache pools to be created by the framework extension.

See also

For more information about how pools works, see cache pools.

To configure a Redis cache pool with a default lifetime of 1 hour, do the following:

YAML

# config/packages/framework.yaml
framework:
    cache:
        pools:
            cache.mycache:
                adapter: cache.adapter.redis
                default_lifetime: 3600

XML

<!-- config/packages/framework.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
        https://symfony.com/schema/dic/services/services-1.0.xsd
        http://symfony.com/schema/dic/symfony https://symfony.com/schema/dic/symfony/symfony-1.0.xsd">

    <framework:config>
        <framework:cache>
            <framework:pool
                name="cache.mycache"
                adapter="cache.adapter.redis"
                default-lifetime=3600
            />
        </framework:cache>
        <!-- ... -->
    </framework:config>
</container>

PHP

// config/packages/framework.php
$container->loadFromExtension('framework', [
    'cache' => [
        'pools' => [
            'cache.mycache' => [
                'adapter' => 'cache.adapter.redis',
                'default_lifetime' => 3600,
            ],
        ],
    ],
]);

name¶

type: prototype

Name of the pool you want to create.

Note

Your pool name must differ from cache.app or cache.system.

adapter¶

type: string default: cache.app

The service name of the adapter to use. You can specify one of the default services that follow the pattern cache.adapter.[type]. Alternatively you can specify another cache pool as base, which will make this pool inherit the settings from the base pool as defaults.

Note

Your service MUST implement the Psr\Cache\CacheItemPoolInterface interface.

public¶

type: boolean default: false

Whether your service should be public or not.

tags¶

type: boolean | string default: null

Whether your service should be able to handle tags or not. Can also be the service id of another cache pool where tags will be stored.

default_lifetime¶

type: integer

Default lifetime of your cache items in seconds.

provider¶

type: string

Overwrite the default service name or DSN respectively, if you do not want to use what is configured as default_X_provider under cache. See the description of the default provider setting above for the type of adapter you use for information on how to specify the provider.

clearer¶

type: string

The cache clearer used to clear your PSR-6 cache.

See also

For more information, see Psr6CacheClearer.

prefix_seed¶

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

lock¶

type: string | array

The default lock adapter. If not defined, the value is set to semaphore when available, or to flock otherwise. Store’s DSN are also allowed.

enabled¶

type: boolean default: true

Whether to enable the support for lock or not. This setting is automatically set to true when one of the child settings is configured.

resources¶

type: array

A list of lock stores to be created by the framework extension.

YAML

# config/packages/lock.yaml
framework:
    # these are all the supported lock stores
    lock: ~
    lock: 'flock'
    lock: 'flock:///path/to/file'
    lock: 'semaphore'
    lock: 'memcached://m1.docker'
    lock: ['memcached://m1.docker', 'memcached://m2.docker']
    lock: 'redis://r1.docker'
    lock: ['redis://r1.docker', 'redis://r2.docker']
    lock: '%env(MEMCACHED_OR_REDIS_URL)%'

    # named locks
    lock:
        invoice: ['redis://r1.docker', 'redis://r2.docker']
        report: 'semaphore'

XML

<!-- config/packages/lock.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
        https://symfony.com/schema/dic/services/services-1.0.xsd
        http://symfony.com/schema/dic/symfony https://symfony.com/schema/dic/symfony/symfony-1.0.xsd">

    <framework:config>
        <framework:lock>
            <!-- these are all the supported lock stores -->
            <framework:resource>flock</framework:resource>

            <framework:resource>flock:///path/to/file</framework:resource>

            <framework:resource>semaphore</framework:resource>

            <framework:resource>memcached://m1.docker</framework:resource>

            <framework:resource>memcached://m1.docker</framework:resource>
            <framework:resource>memcached://m2.docker</framework:resource>

            <framework:resource>redis://r1.docker</framework:resource>

            <framework:resource>redis://r1.docker</framework:resource>
            <framework:resource>redis://r2.docker</framework:resource>

            <framework:resource>%env(REDIS_URL)%</framework:resource>

            <!-- named locks -->
            <framework:resource name="invoice">redis://r1.docker</framework:resource>
            <framework:resource name="invoice">redis://r2.docker</framework:resource>
            <framework:resource name="report">semaphore</framework:resource>
        </framework:lock>
    </framework:config>
</container>

PHP

// config/packages/lock.php
$container->loadFromExtension('framework', [
    // these are all the supported lock stores
    'lock' => null,
    'lock' => 'flock',
    'lock' => 'flock:///path/to/file',
    'lock' => 'semaphore',
    'lock' => 'memcached://m1.docker',
    'lock' => ['memcached://m1.docker', 'memcached://m2.docker'],
    'lock' => 'redis://r1.docker',
    'lock' => ['redis://r1.docker', 'redis://r2.docker'],
    'lock' => '%env(MEMCACHED_OR_REDIS_URL)%',

    // named locks
    'lock' => [
        'invoice' => ['redis://r1.docker', 'redis://r2.docker'],
        'report' => 'semaphore',
    ],
]);

name¶

type: prototype

Name of the lock you want to create.

Tip

If you want to use the RetryTillSaveStore for non-blocking locks, you can do it by decorating the store service:

lock.invoice.retry_till_save.store:
    class: Symfony\Component\Lock\Store\RetryTillSaveStore
    decorates: lock.invoice.store
    arguments: ['@.inner', 100, 50]

workflows¶

type: array

A list of workflows to be created by the framework extension:

YAML

# config/packages/workflow.yaml
framework:
    workflows:
        my_workflow:
            # ...

XML

<!-- config/packages/workflow.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
        https://symfony.com/schema/dic/services/services-1.0.xsd
        http://symfony.com/schema/dic/symfony https://symfony.com/schema/dic/symfony/symfony-1.0.xsd">

    <framework:config>
        <framework:workflows>
            <framework:workflow
                name="my_workflow"/>
        </framework:workflows>
        <!-- ... -->
    </framework:config>
</container>

PHP

// config/packages/workflow.php
$container->loadFromExtension('framework', [
    'workflows' => [
        'my_workflow' => // ...
    ],
]);

See also

See also the article about using workflows in Symfony applications.

enabled¶

type: boolean default: false

Whether to enable the support for workflows or not. This setting is automatically set to true when one of the child settings is configured.

name¶

type: prototype

Name of the workflow you want to create.

audit_trail¶

type: bool

If set to true, the AuditTrailListener will be enabled.

initial_marking¶

type: string | array

One of the places or empty. If not null and the supported object is not already initialized via the workflow, this place will be set.

marking_store¶

type: array

Each marking store can define any of these options:

arguments (type: array)
service (type: string)
type (type: string allow value: 'method')

metadata¶

type: array

Metadata available for the workflow configuration. Note that places and transitions can also have their own metadata entry.

places¶

type: array

All available places (type: string) for the workflow configuration.

supports¶

type: string | array

The FQCN (fully-qualified class name) of the object supported by the workflow configuration or an array of FQCN if multiple objects are supported.

support_strategy¶

type: string

transitions¶

type: array

Each marking store can define any of these options:

from (type: string or array) value from the places, multiple values are allowed for both workflow and state_machine;
guard (type: string) an ExpressionLanguage compatible expression to block the transition;
name (type: string) the name of the transition;
to (type: string or array) value from the places, multiple values are allowed only for workflow.

type¶

type: string possible values: 'workflow' or 'state_machine'

Defines the kind of workflow that is going to be created, which can be either a normal workflow or a state machine. Read this article to know their differences.

Framework Configuration Reference (FrameworkBundle)¶

Configuration¶

secret¶

http_method_override¶

trusted_proxies¶

ide¶

test¶

default_locale¶

disallow_search_engine_index¶

trusted_hosts¶

form¶

enabled¶

csrf_protection¶

enabled¶

error_controller¶

esi¶

enabled¶

fragments¶

enabled¶

hinclude_default_template¶

path¶

http_client¶

auth_basic¶

auth_bearer¶

auth_ntlm¶

base_uri¶

bindto¶

buffer¶

cafile¶

capath¶

ciphers¶

headers¶

http_version¶

local_cert¶

local_pk¶

max_host_connections¶

max_redirects¶

no_proxy¶

passphrase¶

peer_fingerprint¶

proxy¶

query¶

resolve¶

scope¶

timeout¶

max_duration¶

verify_host¶

verify_peer¶

profiler¶

enabled¶

collect¶

only_exceptions¶

only_master_requests¶

dsn¶

request¶

formats¶

router¶

resource¶

type¶

http_port¶

https_port¶

strict_requirements¶

utf8¶

session¶

storage_id¶

handler_id¶

name¶

cookie_lifetime¶

cookie_path¶

cache_limiter¶

cookie_domain¶

cookie_samesite¶

cookie_secure¶

cookie_httponly¶

gc_divisor¶

gc_probability¶

gc_maxlifetime¶

sid_length¶

sid_bits_per_character¶

save_path¶