Configuring in the Kernel
=========================

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.

.. _configuration-kernel-build-directory:

``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. :doc:`cache pools </cache>`). 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 :method:`Symfony\\Component\\HttpKernel\\Kernel::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 :doc:`bundles </bundles>` registered in the
application and the FQCN of their main bundle class::

    [
        'FrameworkBundle' => 'Symfony\Bundle\FrameworkBundle\FrameworkBundle',
        'TwigBundle' => 'Symfony\Bundle\TwigBundle\TwigBundle',
        // ...
    ]

This value is also exposed via the :method:`Symfony\\Component\\HttpKernel\\Kernel::getBundles`
method of the kernel class.

``kernel.bundles_metadata``
---------------------------

**type**: ``array`` **default**: ``[]``

This parameter stores the list of :doc:`bundles </bundles>` registered in the
application and some metadata about them::

    [
        '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
:ref:`configuration environment <configuration-environments>`. Your application
can write data to this path at runtime.

This value is also exposed via the :method:`Symfony\\Component\\HttpKernel\\Kernel::getCacheDir`
method of the kernel class, which you can override to return a different value.

.. _configuration-kernel-charset:

``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 :method:`Symfony\\Component\\HttpKernel\\Kernel::getCharset`
method of the kernel class, which you can override to return a different value::

    // 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 :doc:`service container </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 :phpfunction:`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:

.. configuration-block::

    .. code-block:: yaml

        # config/services.yaml
        parameters:
            # ...
            kernel.container_build_time: '1234567890'

    .. code-block:: 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="kernel.container_build_time">1234567890</parameter>
            </parameters>
        </container>

    .. code-block:: php

        // config/services.php

        // ...
        $container->setParameter('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
:doc:`using applications with multiple kernels </configuration/multiple_kernels>`.

The default value is generated by Symfony based on the current
:ref:`configuration environment <configuration-environments>` and the
:ref:`debug mode <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 :method:`Symfony\\Component\\HttpKernel\\Kernel::getContainerClass`
method of the kernel class, which you can override to return a different value::

    // 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 :ref:`debug mode <debug-mode>`
used by the application.

``kernel.default_locale``
-------------------------

This parameter stores the value of
:ref:`the framework.default_locale parameter <config-framework-default_locale>`.

``kernel.enabled_locales``
--------------------------

This parameter stores the value of
:ref:`the framework.enabled_locales parameter <reference-translator-enabled-locales>`.

.. _configuration-kernel-environment:

``kernel.environment``
----------------------

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

This parameter stores the name of the current :ref:`configuration environment <configuration-environments>`
used by the application.

This value defines the configuration options used to run the application, whereas
the :ref:`kernel.runtime_environment <configuration-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
:ref:`the framework.error_controller parameter <config-framework-error_controller>`.

``kernel.http_method_override``
-------------------------------

This parameter stores the value of
:ref:`the framework.http_method_override parameter <configuration-framework-http_method_override>`.

``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
:ref:`configuration environment <configuration-environments>`.

This value is also exposed via the :method:`Symfony\\Component\\HttpKernel\\Kernel::getLogDir`
method of the kernel class, which you can override to return a different value.

.. _configuration-kernel-project-directory:

``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
:method:`Symfony\\Component\\HttpKernel\\Kernel::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::

    // 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__);
        }
    }

.. _configuration-kernel-runtime-environment:

``kernel.runtime_environment``
------------------------------

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

This parameter stores the name of the current :doc:`runtime environment </components/runtime>`
used by the application.

This value defines the place where the application is deployed, whereas the
:ref:`kernel.environment <configuration-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
:ref:`the framework.secret parameter <configuration-framework-secret>`.

``kernel.trust_x_sendfile_type_header``
---------------------------------------

This parameter stores the value of
:ref:`the framework.trust_x_sendfile_type_header parameter <configuration-framework-http_method_override>`.

``kernel.trusted_hosts``
------------------------

This parameter stores the value of
:ref:`the framework.trusted_hosts parameter <configuration-framework-trusted-hosts>`.

``kernel.trusted_proxies``
--------------------------

This parameter stores the value of
:ref:`the framework.trusted_proxies parameter <reference-framework-trusted-proxies>`.

.. _`character encoding`: https://en.wikipedia.org/wiki/Character_encoding
.. _`reproducible builds`: https://en.wikipedia.org/wiki/Reproducible_builds
.. _`FrankenPHP`: https://frankenphp.dev
