diff --git a/reference/configuration/kernel.rst b/reference/configuration/kernel.rst index d85083993f4..da784e2e7d3 100644 --- a/reference/configuration/kernel.rst +++ b/reference/configuration/kernel.rst @@ -16,15 +16,19 @@ Configuration * `Root Directory`_ * `Cache Directory`_ * `Log Directory`_ +* `Container Build Time`_ Charset ~~~~~~~ **type**: ``string`` **default**: ``UTF-8`` -This returns the charset that is used in the application. To change it, -override the :method:`Symfony\\Component\\HttpKernel\\Kernel::getCharset` -method and return another charset, for instance:: +This option defines the charset that is used in the application. This value is +exposed via the ``kernel.charset`` configuration parameter and the +:method:`Symfony\\Component\\HttpKernel\\Kernel::getCharset` method. + +To change this value, override the ``getCharset()`` method and return another +charset:: // app/AppKernel.php @@ -43,16 +47,18 @@ Kernel Name **type**: ``string`` **default**: ``app`` (i.e. the directory name holding the kernel class) -To change this setting, override the :method:`Symfony\\Component\\HttpKernel\\Kernel::getName` -method. Alternatively, move your kernel into a different directory. For -example, if you moved the kernel into a ``foo`` directory (instead of ``app``), -the kernel name will be ``foo``. - The name of the kernel isn't usually directly important - it's used in the generation of cache files. If you have an application with multiple kernels, the easiest way to make each have a unique name is to duplicate the ``app`` directory and rename it to something else (e.g. ``foo``). +This value is exposed via the ``kernel.name`` configuration parameter and the +:method:`Symfony\\Component\\HttpKernel\\Kernel::getName` method. + +To change this setting, override the ``getName()`` method. Alternatively, move +your kernel into a different directory. For example, if you moved the kernel +into a ``foo`` directory (instead of ``app``), the kernel name will be ``foo``. + Root Directory ~~~~~~~~~~~~~~ @@ -63,11 +69,13 @@ Root Directory **type**: ``string`` **default**: the directory of ``AppKernel`` -This returns the root directory of your kernel. If you use the Symfony Standard -edition, the root directory refers to the ``app`` directory. +This returns the absolute path of the directory where your kernel class is +located. If you use the Symfony Standard edition, this is the ``app/`` directory +of your project. -To change this setting, override the -:method:`Symfony\\Component\\HttpKernel\\Kernel::getRootDir` method:: +This value is exposed via the ``kernel.root_dir`` configuration parameter and +the :method:`Symfony\\Component\\HttpKernel\\Kernel::getRootDir` method. To +change this setting, override the ``getRootDir()`` method:: // app/AppKernel.php @@ -91,12 +99,14 @@ Project Directory **type**: ``string`` **default**: the directory of the project ``composer.json`` -This returns the root directory of your Symfony project. It's calculated as -the directory where the main ``composer.json`` file is stored. +This returns the absolute path of the root directory of your Symfony project. +It's calculated automatically as the directory where the main ``composer.json`` +file is stored. -If for some reason the ``composer.json`` file is not stored at the root of your -project, you can override the :method:`Symfony\\Component\\HttpKernel\\Kernel::getProjectDir` -method to return the right project directory:: +This value is exposed via the ``kernel.project_dir`` configuration parameter and +the :method:`Symfony\\Component\\HttpKernel\\Kernel::getProjectDir` method. To +change this setting, override the ``getProjectDir()`` method to return the right +project directory:: // app/AppKernel.php @@ -116,15 +126,84 @@ Cache Directory **type**: ``string`` **default**: ``$this->rootDir/cache/$this->environment`` -This returns the path to the cache directory. To change it, override the -:method:`Symfony\\Component\\HttpKernel\\Kernel::getCacheDir` method. Read -":ref:`override-cache-dir`" for more information. +This returns the absolute path of the cache directory of your Symfony project. +It's calculated automatically based on the current +:doc:`environment `. + +This value is exposed via the ``kernel.cache_dir`` configuration parameter and +the :method:`Symfony\\Component\\HttpKernel\\Kernel::getCacheDir` method. To +change this setting, override the ``getCacheDir()`` method to return the right +cache directory. Log Directory ~~~~~~~~~~~~~ **type**: ``string`` **default**: ``$this->rootDir/logs`` -This returns the path to the log directory. To change it, override the -:method:`Symfony\\Component\\HttpKernel\\Kernel::getLogDir` method. Read -":ref:`override-logs-dir`" for more information. +This returns the absolute path of the log directory of your Symfony project. +It's calculated automatically based on the current +:doc:`environment `. + +This value is exposed via the ``kernel.log_dir`` configuration parameter and +the :method:`Symfony\\Component\\HttpKernel\\Kernel::getLogDir` method. To +change this setting, override the ``getLogDir()`` method to return the right +log directory. + +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 ` of your +application will always be the same if you don't change its source code. This is +exposed via these configuration 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 configuration 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 + + # app/config/services.yml + parameters: + # ... + kernel.container_build_time: '1234567890' + + .. code-block:: xml + + + + + + + + 1234567890 + + + + .. code-block:: php + + // app/config/services.php + use Symfony\Component\DependencyInjection\Reference; + + // ... + $container->setParameter('kernel.container_build_time', '1234567890'); + +.. _`reproducible builds`: https://en.wikipedia.org/wiki/Reproducible_builds