Framework Configuration Reference (FrameworkBundle) (Symfony Docs) (original) (raw)

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.

assets

The following options configure the behavior of theTwig asset() function.

base_path

type: string

This option allows you to prepend a base path to the URLs generated for assets:

With this configuration, a call to asset('logo.png') will generate/images/logo.png instead of /logo.png.

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:

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.

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

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. You can set strict_mode to true to get an exception when an asset is not found.

Note

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

After having configured one or more asset packages, you have two ways of injecting them in any service or controller:

(1) Use a specific argument name

Type-hint your constructor/method argument with PackageInterface and name the argument using this pattern: "asset package name in camelCase". For example, to inject the foo_package package defined earlier:

(2) Use the #[Target] attribute

When dealing with multiple implementations of the same typethe #[Target] attribute helps you select which one to inject. Symfony creates a target with the same name as the asset package.

For example, to select the foo_package package defined earlier:

strict_mode

type: boolean default: false

When enabled, the strict mode asserts that all requested assets are in the manifest file. This option is useful to detect typos or missing assets, the recommended value is %kernel.debug%.

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:

By default, this will render a path to your image such as /images/logo.png. Now, activate the version option:

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

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 theversion. 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 theversion option to construct an asset's path. By default, the pattern adds the asset's version as a query string. For example, ifversion_format is set to %%s?version=%%s and versionis 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 Container.

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 ofversion-%%2$s/%%1$s, which would result in the pathversion-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 strategyapplied to the assets. This option can be set globally for all assets and individually for each asset package:

Note

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

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.system,cache.adapter.filesystem, cache.adapter.psr6, cache.adapter.redis,cache.adapter.memcached, cache.adapter.pdo andcache.adapter.doctrine_dbal.

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.

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_memcached_provider

type: string default: memcached://localhost

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

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

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

directory

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

The path to the cache directory used by services inheriting from thecache.adapter.filesystem adapter (including cache.app).

pools

type: array

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

See also

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

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

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 needs to implement the Psr\Cache\CacheItemPoolInterface interface.

clearer

type: string

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

default_lifetime

type: integer | string

Default lifetime of your cache items. Give an integer value to set the default lifetime in seconds. A string value could be ISO 8601 time interval, like "PT5M"or a PHP date expression that is accepted by strtotime(), like "5 minutes".

If no value is provided, the cache adapter will fallback to the default value on the actual cache storage.

name

type: prototype

Name of the pool you want to create.

Note

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

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 information on how to specify your specific provider.

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.

prefix_seed

type: string default: _%kernel.project_dir%.%kernel.container_class%

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

Note

The prefix_seed option is used at compile time. This means that any change made to this value after container's compilation will have no effect.

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.

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

type: integer or bool default: false

Whether to check the CSRF token in an HTTP header in addition to the cookie when using stateless CSRF protection. You can also set this to 2 (the value of the CHECK_ONLY_HEADER constant on theSameOriginCsrfTokenManager class) to check only the header and ignore the cookie.

type: string default: csrf-token

The name of the cookie (and HTTP header) to use for the double-submit when usingstateless CSRF protection.

default_locale

type: string default: en

The default locale is used if no _locale routing parameter has been set. It is available with theRequest::getDefaultLocalemethod.

See also

You can read more information about the default locale inTranslations.

enabled_locales

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

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:

An added bonus of defining the enabled locales is that they are automatically added as a requirement of the special _locale parameter. For example, if you define this value as ['ar', 'he', 'ja', 'zh'], the_locale routing parameter will have an ar|he|ja|zh requirement. If some user makes requests with a locale not included in this option, they'll see a 404 error.

set_content_language_from_locale

type: boolean default: false

If this option is set to true, the response will have a Content-LanguageHTTP header set with the Request locale.

set_locale_from_accept_language

type: boolean default: false

If this option is set to true, the Request locale will automatically be set to the value of the Accept-Language HTTP header.

When the _locale request attribute is passed, the Accept-Language header is ignored.

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

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 (seeHow to Customize Error Pages).

esi

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:

exceptions

type: array

Defines the log level, log channeland HTTP status code applied to the exceptions that match the given exception class:

The order in which you configure exceptions is important because Symfony will use the configuration of the first exception that matches instanceof:

You can map a status code and a set of headers to an exception thanks to the #[WithHttpStatus] attribute on the exception class:

It is also possible to map a log level on a custom exception class using the #[WithLogLevel] attribute:

The attributes can also be added to interfaces directly:

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

field_name

type: string default: _token

This is the field name that you should give to the CSRF token field of your forms.

field_attr

type: array default: ['data-controller' => 'csrf-protection']

HTML attributes to add to the CSRF token field of your forms.

token_id

type: string default: null

The CSRF token ID used to validate the CSRF tokens of your forms. This setting applies only to form types that use service autoconfiguration, which typically means your own form types, not those registered by third-party bundles.

fragments

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.

path

type: string default: /_fragment

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

handle_all_throwables

type: boolean default: true

When set to true, the Symfony kernel will catch all \Throwable exceptions thrown by the application and will turn them into HTTP responses.

html_sanitizer

The html_sanitizer option (and its children) are used to configure custom HTML sanitizers. Read more about the options in theHTML sanitizer documentation.

http_cache

allow_reload

type: boolean default: false

Specifies whether the client can force a cache reload by including a Cache-Control "no-cache" directive in the request. Set it to truefor compliance with RFC 2616.

allow_revalidate

type: boolean default: false

Specifies whether the client can force a cache revalidate by including a Cache-Control "max-age=0" directive in the request. Set it to truefor compliance with RFC 2616.

debug

type: boolean default: %kernel.debug%

If true, exceptions are thrown when things go wrong. Otherwise, the cache will try to carry on and deliver a meaningful response.

default_ttl

type: integer default: 0

The number of seconds that a cache entry should be considered fresh when no explicit freshness information is provided in a response. Explicit Cache-Control or Expires headers override this value.

enabled

type: boolean default: false

type: array default: ['Authorization', 'Cookie']

Set of request headers that trigger "private" cache-control behavior on responses that don't explicitly state whether the response is public or private via a Cache-Control directive.

type: array default: Set-Cookie

Set of response headers that will never be cached even when the response is cacheable and public.

stale_if_error

type: integer default: 60

Specifies the default number of seconds (the granularity is the second) during which the cache can serve a stale response when an error is encountered. This setting is overridden by the stale-if-error HTTP Cache-Control extension (see RFC 5861).

stale_while_revalidate

type: integer default: 2

Specifies the default number of seconds (the granularity is the second as the Response TTL precision is a second) during which the cache can immediately return a stale response while it revalidates it in the background. This setting is overridden by the stale-while-revalidate HTTP Cache-Control extension (see RFC 5861).

type: string default: 'X-Symfony-Cache'

Header name to use for traces.

trace_level

type: string possible values: 'none', 'short' or 'full'

For 'short', a concise trace of the main request will be added as an HTTP header. 'full' will add traces for all requests (including ESI subrequests). (default: 'full' if in debug; 'none' otherwise)

http_client

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

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

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:

Options defined for scoped clients apply only to URLs that match either theirbase_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 exampleSymfony\Contracts\HttpClient\HttpClientInterface $myApiClientas the type and name of an argument, autowiring will inject the my_api.clientservice 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 theRFC 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:

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: boolean | 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 istrue. 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).

caching

type: array

This option configures the behavior of the HTTP client caching, including which types of requests to cache and how many times. The behavior is defined with the following options:

cache_pool

type: string

The service ID of the cache pool used to store the cached responses. The service must implement the TagAwareCacheInterface.

By default, it uses an instance of TagAwareAdapterwrapping the cache.app pool.

shared

type: boolean default: true

If true, it uses a shared cache so cached responses can be reused across users. Set it to false to use a private cache.

max_ttl

type: integer default: null

The maximum time-to-live (in seconds) for cached responses. By default, responses are cached for as long as the TTL specified by the server. When this option is set, server-provided TTLs are capped to this value.

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 TLS connections. They can be separated by colons, commas or spaces (e.g. 'RC4-SHA:TLS13-AES-128-GCM-SHA256').

crypto_method

type: integer

The minimum version of TLS to accept. The value must be one of theSTREAM_CRYPTO_METHOD_TLSv*_CLIENT constants defined by PHP.

type: array

Arbitrary additional data to pass to the HTTP client for further use. This can be particularly useful when decorating an existing client.

type: array

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

http_version

type: string | null default: null

The HTTP version to use, typically '1.1' or '2.0'. Leave it to nullto 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 passphraseoptions.

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

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 thelocal_cert option.

peer_fingerprint

type: array

When negotiating a TLS 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, ...].

rate_limiter

type: string

The service ID of the rate limiter used to limit the number of HTTP requests within a certain period. The service must implement theLimiterInterface.

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', ...]).

retry_failed

type: array

This option configures the behavior of the HTTP client when some request fails, including which types of requests to retry and how many times. The behavior is defined with the following options:

delay

type: integer default: 1000

The initial delay in milliseconds used to compute the waiting time between retries.

enabled

type: boolean default: false

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

jitter

type: float default: 0.1 (must be between 0.0 and 1.0)

This option adds some randomness to the delay. It's useful to avoid sending multiple requests to the server at the exact same time. The randomness is calculated as delay * jitter. For example: if delay is 1000ms and jitter is 0.2, the actual delay will be a number between 800 and 1200 (1000 +/- 20%).

max_delay

type: integer default: 0

The maximum amount of milliseconds initial to wait between retries. Use 0 to not limit the duration.

max_retries

type: integer default: 3

The maximum number of retries for failing requests. When the maximum is reached, the client returns the last received response.

multiplier

type: float default: 2

This value is multiplied to the delay each time a retry occurs, to distribute retries in time instead of making all of them sequentially.

retry_strategy

type: string

The service is used to decide if a request should be retried and to compute the time to wait between retries. By default, it uses an instance ofGenericRetryStrategy configured with http_codes, delay, max_delay, multiplier and jitteroptions. This class has to implementRetryStrategyInterface.

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

timeout

type: float default: depends on your PHP config

Time, in seconds, to wait for network activity. If the connection is idle for longer, aTransportException is thrown. Its default value is the same as the value of PHP's default_socket_timeoutconfig option.

verify_host

type: boolean default: true

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 default: true

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

http_method_override

type: boolean default: false

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

Warning

If you're using the HttpCache Reverse Proxywith 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:

allowed_http_method_override

type: array default: null

This option controls which HTTP methods can be overridden via the _methodrequest parameter or the X-HTTP-METHOD-OVERRIDE header whenhttp_method_override is enabled.

When set to null (the default), all HTTP methods can be overridden. When set to an empty array ([]), HTTP method overriding is completely disabled. When set to a specific list of methods, only those methods will be allowed as overrides:

This security feature is useful for hardening your application by explicitly defining which methods can be tunneled through POST requests. For example, if your application only needs to override POST requests to PUT and DELETE, you can restrict the allowed methods accordingly.

You can also configure this programmatically using theRequest::setAllowedHttpMethodOverridemethod:

ide

type: string default: %env(default::SYMFONY_IDE)%

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 and Windows; Linux requires installing 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 %lplaceholder 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. First, you can define this option in the SYMFONY_IDE environment variable, which Symfony reads automatically when framework.ide config is not set.

Another alternative is to set the xdebug.file_link_format option in yourphp.ini configuration file. The format to use is the same as for theframework.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:

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 map of lock stores to be created by the framework extension, with the name as key and DSN or service id as value:

name

type: prototype

Name of the lock you want to create.

mailer

dsn

type: string default: null

The DSN used by the mailer. When several DSN may be used, usetransports option (see below) instead.

envelope

recipients

type: array

The "envelope recipient" which is used as the value of RCPT TO during the the SMTP session. This value overrides any other recipient set in the code.

sender

type: string

The "envelope sender" which is used as the value of MAIL FROM during theSMTP session. This value overrides any other sender set in the code.

type: array

Headers to add to emails. The key (name attribute in xml format) is the header name and value the header value.

message_bus

type: string default: null or default bus if Messenger component is installed

Service identifier of the message bus to use when using theMessenger component (e.g. messenger.default_bus).

transports

type: array

A list of DSN that can be used by the mailer. A transport name is the key and the dsn is the value.

messenger

enabled

type: boolean default: true

Whether to enable or not Messenger.

php_errors

log

type: boolean, int or array<int, string> default: true

Use the application logger instead of the PHP logger for logging PHP errors. When an integer value is used, it defines a bitmask of PHP errors that will be logged. Those integer values must be the same used in theerror_reporting PHP option. The default log levels will be used for each PHP error. When a boolean value is used, true enables logging for all PHP errors while false disables logging entirely.

This option also accepts a map of PHP errors to log levels:

throw

type: boolean default: %kernel.debug%

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

profiler

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:

collect_parameter

type: string default: null

This specifies name of a query parameter, a body parameter or a request attribute used to enable or disable collection of data by the profiler for each request. Combine it with the collect option to enable/disable the profiler on demand:

dsn

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

The DSN where to store the profiling information.

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 devand test environments.

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_main_requests

type: boolean default: false

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

property_access

magic_call

type: boolean default: false

When enabled, the property_accessor service uses PHP'smagic __call() method when its getValue() method is called.

magic_get

type: boolean default: true

When enabled, the property_accessor service uses PHP'smagic __get() method when its getValue() method is called.

magic_set

type: boolean default: true

When enabled, the property_accessor service uses PHP'smagic __set() method when its setValue() 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

type: boolean default: true

Configures the property_info service to extract property information from the constructor arguments using the ConstructorExtractor.

8.0

The default value of the with_constructor_extractor option was changed to true in Symfony 8.0.

rate_limiter

name

type: prototype

Name of the rate limiter you want to create.

lock_factory

type: string default: lock.factory

The service that is used to create a lock. The service has to be an instance of the LockFactory class.

policy

type: string required

The name of the rate limiting algorithm to use. Example names are fixed_window,sliding_window and no_limit. See Rate Limiter Policies) for more 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 callRequest::getFormat($mimeType) orRequest::getMimeType($format).

In practice, this is important because Symfony uses it to automatically set theContent-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:

router

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

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.

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 ''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 falseor null might be preferred in production.

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

utf8

type: boolean default: true

When this option is set to true, the regular expressions used in therequirements 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 thegetCharset() method of your kernel) it's recommended setting it to true. This will make non-UTF8 URLs to generate 404 errors.

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). That's why you should treat this value as if it were a sensitive credential andnever make it public.

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.

secrets

decryption_env_var

type: string default: base64:default::SYMFONY_DECRYPTION_SECRET

The env var name that contains the vault decryption secret. By default, this value will be decoded from base64.

enabled

type: boolean default: true

Whether to enable or not secrets managements.

local_dotenv_file

type: string default: %kernel.project_dir%/.env.%kernel.environment%.local

The path to the local .env file. This file must contain the vault decryption key, given by the decryption_env_var option.

vault_directory

type: string default: %kernel.project_dir%/config/secrets/%kernel.runtime_environment%

The directory to store the secret vault. By default, the path includes the value of the kernel.runtime_environmentparameter.

semaphore

type: string | array

The default semaphore adapter. Store's DSN are also allowed.

enabled

type: boolean default: true

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

resources

type: array

A map of semaphore stores to be created by the framework extension, with the name as key and DSN or service id as value:

name

type: prototype

Name of the semaphore you want to create.

serializer

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.

default_context

type: array default: []

A map with default context options that will be used with each serialize and deserializecall. This can be used for example to set the json encoding behavior by setting json_encode_optionsto a json_encode flags bitmask.

You can inspect the serializer context buildersto discover the available settings.

enable_attributes

type: boolean default: true

Enables support for PHP attributes in the serializer component.

enabled

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

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

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.

name_converter

type: string

The name converter to use. The CamelCaseToSnakeCaseNameConvertername converter can enabled by using the serializer.name_converter.camel_case_to_snake_casevalue.

session

cache_limiter

type: string default: 0

If set to 0, Symfony won't set any particular header related to the cache and it will rely on php.ini's session.cache_limiter directive.

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

Be aware that if you configure it, you'll have to set other session-related options as parameters as well.

type: string

This determines the domain to set in the session cookie.

If not set, php.ini's session.cookie_domain directive will be relied on.

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

This determines the lifetime of the session - in seconds. Setting this value to 0 means the cookie is valid for the length of the browser session.

If not set, php.ini's session.cookie_lifetime directive will be relied on.

type: string

This determines the path to set in the session cookie.

If not set, php.ini's session.cookie_path directive will be relied on.

type: string or null default: 'lax'

It controls the way cookies are sent when the HTTP request did not originate from the same domain that is associated with the cookies. Setting this option is recommended to mitigate CSRF security attacks.

By default, browsers send all cookies related to the domain of the HTTP request. This may be a problem for example when you visit a forum and some malicious comment includes a link like https://some-bank.com/?send_money_to=attacker&amount=1000. If you were previously logged into your bank website, the browser will send all those cookies when making that HTTP request.

The possible values for this option are:

type: boolean or 'auto'

This determines whether cookies should only be sent over secure connections. In addition to true and false, there's a special 'auto' value that means true for HTTPS requests and false for HTTP requests.

If not set, php.ini's session.cookie_secure directive will be relied on.

enabled

type: boolean default: true

Whether to enable the session support in the framework.

gc_maxlifetime

type: integer

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.

If not set, php.ini's session.gc_maxlifetime directive will be relied on.

gc_probability

type: integer

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.

If not set, Symfony will use the value of the session.gc_probability directive in the php.ini configuration file.

handler_id

type: string | null default: null

If framework.session.save_path is not set, the default value of this option is null, which means to use the session handler configured in php.ini. If theframework.session.save_path option is set, then Symfony stores sessions using the native file session handler.

It is possible to store sessions in a database, and also to configure the session handler with a DSN:

Note

Supported DSN protocols are the following:

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.

name

type: string

This specifies the name of the session cookie.

If not set, php.ini's session.name directive will be relied on.

save_path

type: string | null 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.

If null, php.ini's session.save_path directive will be relied on:

storage_factory_id

type: string default: session.storage.factory.native

The service ID used for creating the SessionStorageInterface that stores the session. This service is available in the Symfony application via thesession.storage.factory service alias. The class has to implementSessionStorageFactoryInterface. To see a list of all available storages, run:

use_cookies

type: boolean

This specifies if the session ID is stored on the client side using cookies or not.

If not set, php.ini's session.use_cookies directive will be relied on.

ssi

enabled

type: boolean default: false

Whether to enable or not SSI support in your application.

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

See also

For more information, see Testing.

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.

default_path

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

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

enabled

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

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

fallbacks

type: string|array default: value of default_locale

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

formatter

type: string default: translator.formatter.default

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

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 at thedebug 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.

paths

type: array default: []

This option allows to define an array of paths where the component will look for translation files. The later a path is added, the more priority it has (translations from later paths overwrite earlier ones). Translations from thedefault_path have more priority than translations from all these paths.

providers

type: array default: []

This option enables and configures translation providersto push and pull your translations to/from third party translation services.

type: boolean default: %env(bool:default::SYMFONY_TRUST_X_SENDFILE_TYPE_HEADER)%

X-Sendfile is a special HTTP header that tells web servers to replace the response contents by the file that is defined in that header. This improves performance because files are no longer served by your application but directly by the web server.

This configuration option determines whether to trust x-sendfile header for BinaryFileResponse. If enabled, Symfony calls theBinaryFileResponse::trustXSendfileTypeHeadermethod automatically. It becomes the service container parameter namedkernel.trust_x_sendfile_type_header.

trusted_hosts

type: array | string default: ['%env(default::SYMFONY_TRUSTED_HOSTS)%']

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 configure a list of 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.

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:

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

validation

disable_translation

type: boolean default: false

Validation error messages are automatically translated to the current application locale. Set this option to true to disable translation of validation messages. This is useful to avoid "missing translation" errors in applications that use only a single language.

enable_attributes

type: boolean default: true

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

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.

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:

not_compromised_password

The NotCompromisedPasswordconstraint 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 NotCompromisedPasswordconstraint 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 the 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.

translation_domain

type: string | false default: validators

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

enabled

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

Adds a Link HTTP header to the response.

webhook

The webhook option (and its children) are used to configure the webhooks defined in your application. Read more about the options in the Webhook documentation.

workflows

type: array

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

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.

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:

metadata

type: array

Metadata available for the workflow configuration. Note that places and transitions can also have their ownmetadata 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:

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 articleto know their differences.