Configuring in the Kernel

Edit this page

Symfony applications define a kernel class (which is located by default at src/Kernel.php) that includes several configurable options. This article explains how to configure those options and shows the list of container parameters created by Symfony based on that configuration.

kernel.build_dir

type: string default: $this->getCacheDir()

This parameter stores the absolute path of a build directory of your Symfony application. This directory can be used to separate read-only cache (i.e. the compiled container) from read-write cache (i.e. cache pools). Specify a non-default value when the application is deployed in a read-only filesystem like a Docker container or AWS Lambda.

This value is also exposed via the getBuildDir() method of the kernel class, which you can override to return a different value.

You can also change the build directory by defining an environment variable named APP_BUILD_DIR whose value is the absolute path of the build folder.

kernel.bundles

type: array default: []

This parameter stores the list of bundles registered in the application and the FQCN of their main bundle class:

1
2
3
4
5
[
    'FrameworkBundle' => 'Symfony\Bundle\FrameworkBundle\FrameworkBundle',
    'TwigBundle' => 'Symfony\Bundle\TwigBundle\TwigBundle',
    // ...
]

This value is also exposed via the getBundles() method of the kernel class.

kernel.bundles_metadata

type: array default: []

This parameter stores the list of bundles registered in the application and some metadata about them:

1
2
3
4
5
6
7
8
9
10
11
[
    'FrameworkBundle' => [
        'path' => '/<path-to-your-project>/vendor/symfony/framework-bundle',
        'namespace' => 'Symfony\Bundle\FrameworkBundle',
    ],
    'TwigBundle' => [
        'path' => '/<path-to-your-project>/vendor/symfony/twig-bundle',
        'namespace' => 'Symfony\Bundle\TwigBundle',
    ],
    // ...
]

This value is not exposed via any method of the kernel class, so you can only obtain it via the container parameter.

kernel.cache_dir

type: string default: $this->getProjectDir()/var/cache/$this->environment

This parameter stores the absolute path of the cache directory of your Symfony application. The default value is generated by Symfony based on the current configuration environment. Your application can write data to this path at runtime.

This value is also exposed via the getCacheDir() method of the kernel class, which you can override to return a different value.

kernel.charset

type: string default: UTF-8

This parameter stores the type of charset or character encoding that is used in the application. This value is also exposed via the getCharset() method of the kernel class, which you can override to return a different value:

1
2
3
4
5
6
7
8
9
10
11
12
13
// src/Kernel.php
namespace App;

use Symfony\Component\HttpKernel\Kernel as BaseKernel;
// ...

class Kernel extends BaseKernel
{
    public function getCharset(): string
    {
        return 'ISO-8859-1';
    }
}

kernel.container_build_time

type: string default: the result of executing time()

Symfony follows the reproducible builds philosophy, which ensures that the result of compiling the exact same source code doesn't produce different results. This helps checking that a given binary or executable code was compiled from some trusted source code.

In practice, the compiled service container of your application will always be the same if you don't change its source code. This is exposed via these container parameters:

  • container.build_hash, a hash of the contents of all your source files;
  • container.build_time, a timestamp of the moment when the container was built (the result of executing PHP's time function);
  • container.build_id, the result of merging the two previous parameters and encoding the result using CRC32.

Since the container.build_time value will change every time you compile the application, the build will not be strictly reproducible. If you care about this, the solution is to use another container parameter called kernel.container_build_time and set it to a non-changing build time to achieve a strict reproducible build:

1
2
3
4
# config/services.yaml
parameters:
    # ...
    kernel.container_build_time: '1234567890'

kernel.container_class

type: string default: (see explanation below)

This parameter stores a unique identifier for the container class. In practice, this is only important to ensure that each kernel has a unique identifier when using applications with multiple kernels.

The default value is generated by Symfony based on the current configuration environment and the debug mode. For example, if your application kernel is defined in the App namespace, runs in the dev environment and the debug mode is enabled, the value of this parameter is App_KernelDevDebugContainer.

This value is also exposed via the getContainerClass() method of the kernel class, which you can override to return a different value:

1
2
3
4
5
6
7
8
9
10
11
12
13
// src/Kernel.php
namespace App;

use Symfony\Component\HttpKernel\Kernel as BaseKernel;
// ...

class Kernel extends BaseKernel
{
    public function getContainerClass(): string
    {
        return sprintf('AcmeKernel%s', random_int(10_000, 99_999));
    }
}

kernel.debug

type: boolean default: (the value is passed as an argument when booting the kernel)

This parameter stores the value of the current debug mode used by the application.

kernel.default_locale

This parameter stores the value of the framework.default_locale parameter.

kernel.enabled_locales

This parameter stores the value of the framework.enabled_locales parameter.

kernel.environment

type: string default: (the value is passed as an argument when booting the kernel)

This parameter stores the name of the current configuration environment used by the application.

This value defines the configuration options used to run the application, whereas the kernel.runtime_environment option defines the place where the application is deployed. This allows for example to run an application with the prod config (kernel.environment) in different scenarios like staging or production (kernel.runtime_environment).

kernel.error_controller

This parameter stores the value of the framework.error_controller parameter.

kernel.http_method_override

This parameter stores the value of the framework.http_method_override parameter.

kernel.logs_dir

type: string default: $this->getProjectDir()/var/log

This parameter stores the absolute path of the log directory of your Symfony application. It's calculated automatically based on the current configuration environment.

This value is also exposed via the getLogDir() method of the kernel class, which you can override to return a different value.

kernel.project_dir

type: string default: the directory of the project's composer.json

This parameter stores the absolute path of the root directory of your Symfony application, which is used by applications to perform operations with file paths relative to the project's root directory.

By default, its value is calculated automatically as the directory where the main composer.json file is stored. This value is also exposed via the getProjectDir() method of the kernel class.

If you don't use Composer, or have moved the composer.json file location or have deleted it entirely (for example in the production servers), override the getProjectDir() method to return a different value:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
// src/Kernel.php
namespace App;

use Symfony\Component\HttpKernel\Kernel as BaseKernel;
// ...

class Kernel extends BaseKernel
{
    // ...

    public function getProjectDir(): string
    {
        // when defining a hardcoded string, don't add the trailing slash to the path
        // e.g. '/home/user/my_project', '/app', '/var/www/example.com'
        return \dirname(__DIR__);
    }
}

kernel.runtime_environment

type: string default: %env(default:kernel.environment:APP_RUNTIME_ENV)%

This parameter stores the name of the current runtime environment used by the application.

This value defines the place where the application is deployed, whereas the kernel.environment option defines the configuration options used to run the application. This allows for example to run an application with the prod config (kernel.environment) in different scenarios like staging or production (kernel.runtime_environment).

kernel.runtime_mode

type: string default: %env(query_string:default:container.runtime_mode:APP_RUNTIME_MODE)%

This parameter stores a query string of the current runtime mode used by the application. For example, the query string looks like web=1&worker=0 when the application is running in web mode and web=1&worker=1 when running in a long-running web server. This parameter can be set by using the APP_RUNTIME_MODE env var.

kernel.runtime_mode.web

type: boolean default: %env(bool:default::key:web:default:kernel.runtime_mode:)%

Whether the application is running in a web environment.

kernel.runtime_mode.cli

type: boolean default: %env(not:default:kernel.runtime_mode.web:)%

Whether the application is running in a CLI environment. By default, this value is the opposite of the kernel.runtime_mode.web parameter.

kernel.runtime_mode.worker

type: boolean default: %env(bool:default::key:worker:default:kernel.runtime_mode:)%

Whether the application is running in a worker/long-running environment. Not all web servers support it, and you have to use a long-running web server like FrankenPHP.

kernel.secret

type: string default: %env(APP_SECRET)%

This parameter stores the value of the framework.secret parameter.

kernel.trust_x_sendfile_type_header

This parameter stores the value of the framework.trust_x_sendfile_type_header parameter.

kernel.trusted_hosts

This parameter stores the value of the framework.trusted_hosts parameter.

kernel.trusted_proxies

This parameter stores the value of the framework.trusted_proxies parameter.

This work, including the code samples, is licensed under a Creative Commons BY-SA 3.0 license.
TOC
    Version