8000 Merge branch '3.4' into 4.2 · trakos/symfony-docs@1115e13 · GitHub
[go: up one dir, main page]
Skip to content

Commit 1115e13

Browse files
javiereguiluzjaviereguiluz
committed
Merge branch '3.4' into 4.2
* 3.4: Documented the kernel.container_build_time parameter
2 parents 9f63522 + 59aec66 commit 1115e13

File tree

1 file changed

+99
-23
lines changed

1 file changed

+99
-23
lines changed

‎reference/configuration/kernel.rst

Lines changed: 99 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@ Configuration
1616
* `Project Directory`_
1717
* `Cache Directory`_
1818
* `Log Directory`_
19+
* `Container Build Time`_
1920

2021
.. _configuration-kernel-charset:
2122

@@ -24,9 +25,12 @@ Charset
2425

2526
**type**: ``string`` **default**: ``UTF-8``
2627

27-
This returns the charset that is used in the application. To change it,
28-
override the :method:`Symfony\\Component\\HttpKernel\\Kernel::getCharset`
29-
method and return another charset, for instance::
28+
This option defines the charset that is used in the application. This value is
29+
exposed via the ``kernel.charset`` configuration parameter and the
30+
:method:`Symfony\\Component\\HttpKernel\\Kernel::getCharset` method.
31+
32+
To change this value, override the ``getCharset()`` method and return another
33+
charset::
3034

3135
// src/Kernel.php
3236
use Symfony\Component\HttpKernel\Kernel as BaseKernel;
@@ -52,32 +56,35 @@ the kernel class)
5256
deprecated in Symfony 4.2. If you need a unique ID for your kernels use the
5357
``kernel.container_class`` parameter or the ``Kernel::getContainerClass()`` method.
5458

55-
To change this setting, override the :method:`Symfony\\Component\\HttpKernel\\Kernel::getName`
56-
method. Alternatively, move your kernel into a different directory. For
57-
example, if you moved the kernel into a ``foo/`` directory (instead of ``src/``),
58-
the kernel name will be ``foo``.
59-
6059
The name of the kernel isn't usually directly important - it's used in the
6160
generation of cache files - and you probably will only change it when
6261
:doc:`using applications with multiple kernels </configuration/multiple_kernels>`.
6362

64-
.. _configuration-kernel-project-directory:
63+
This value is exposed via the ``kernel.name`` configuration parameter and the
64+
:method:`Symfony\\Component\\HttpKernel\\Kernel::getName` method.
65+
66+
To change this setting, override the ``getName()`` method. Alternatively, move
67+
your kernel into a different directory. For example, if you moved the kernel
68+
into a ``foo/`` directory (instead of ``src/``), the kernel name will be ``foo``.
6569

6670
Project Directory
6771
~~~~~~~~~~~~~~~~~
6872

6973
**type**: ``string`` **default**: the directory of the project ``composer.json``
7074

71-
This returns the root directory of your Symfony project, which is used by
72-
applications to perform operations with file paths relative to the project's
73-
root directory.
75+
This returns the absolute path of the root directory of your Symfony project,
76+
which is used by applications to perform operations with file paths relative to
77+
the project's root directory.
7478

7579
By default, its value is calculated automatically as the directory where the
76-
main ``composer.json`` file is stored. If you don't use Composer, or have moved
77-
the ``composer.json`` file location or have deleted it entirely (for example in
78-
the production servers), you can override the
79-
:method:`Symfony\\Component\\HttpKernel\\Kernel::getProjectDir` method to return
80-
the right project directory::
80+
main ``composer.json`` file is stored. This value is exposed via the
81+
``kernel.project_dir`` configuration parameter and the
82+
:method:`Symfony\\Component\\HttpKernel\\Kernel::getProjectDir` method.
83+
84+
If you don't use Composer, or have moved the ``composer.json`` file location or
85+
have deleted it entirely (for example in the production servers), you can
86+
override the :method:`Symfony\\Component\\HttpKernel\\Kernel::getProjectDir`
87+
method to return the right project directory::
8188

8289
// src/Kernel.php
8390
use Symfony\Component\HttpKernel\Kernel as BaseKernel;
@@ -98,15 +105,84 @@ Cache Directory
98105

99106
**type**: ``string`` **default**: ``$this->rootDir/cache/$this->environment``
100107

101-
This returns the path to the cache directory. To change it, override the
102-
:method:`Symfony\\Component\\HttpKernel\\Kernel::getCacheDir` method. Read
103-
":ref:`override-cache-dir`" for more information.
108+
This returns the absolute path of the cache directory of your Symfony project.
109+
It's calculated automatically based on the current
110+
:doc:`environment </configuration/environments>`.
111+
112+
This value is exposed via the ``kernel.cache_dir`` configuration parameter and
113+
the :method:`Symfony\\Component\\HttpKernel\\Kernel::getCacheDir` method. To
114+
change this setting, override the ``getCacheDir()`` method to return the right
115+
cache directory.
104116

105117
Log Directory
106118
~~~~~~~~~~~~~
107119

108120
**type**: ``string`` **default**: ``$this->rootDir/log``
109121

110-
This returns the path to the log directory. To change it, override the
111-
:method:`Symfony\\Component\\HttpKernel\\Kernel::getLogDir` method. Read
112-
":ref:`override-logs-dir`" for more information.
122+
This returns the absolute path of the log directory of your Symfony project.
123+
It's calculated automatically based on the current
124+
:doc:`environment </configuration/environments>`.
125+
126+
This value is exposed via the ``kernel.log_dir`` configuration parameter and
127+
the :method:`Symfony\\Component\\HttpKernel\\Kernel::getLogDir` method. To
128+
change this setting, override the ``getLogDir()`` method to return the right
129+
log directory.
130+
131+
Container Build Time
132+
~~~~~~~~~~~~~~~~~~~~
133+
134+
**type**: ``string`` **default**: the result of executing ``time()``
135+
136+
Symfony follows the `reproducible builds`_ philosophy, which ensures that the
137+
result of compiling the exact same source code doesn't produce different
138+
results. This helps checking that a given binary or executable code was compiled
139+
from some trusted source code.
140+
141+
In practice, the compiled :doc:`service container </service_container>` of your
142+
application will always be the same if you don't change its source code. This is
143+
exposed via these configuration parameters:
144+
145+
* ``container.build_hash``, a hash of the contents of all your source files;
146+
* ``container.build_time``, a timestamp of the moment when the container was
147+
built (the result of executing PHP's :phpfunction:`time` function);
148+
* ``container.build_id``, the result of merging the two previous parameters and
149+
encoding the result using CRC32.
150+
151+
Since the ``container.build_time`` value will change every time you compile the
152+
application, the build will not be strictly reproducible. If you care about
153+
this, the solution is to use another configuration parameter called
154+
``kernel.container_build_time`` and set it to a non-changing build time to
155+
achieve a strict reproducible build::
156+
157+
.. configuration-block::
158+
159+
.. code-block:: yaml
160+
161+
# config/services.yaml
162+
parameters:
163+
# ...
164+
kernel.container_build_time: '1234567890'
165+
166+
.. code-block:: xml
167+
168+
<!-- config/services.xml -->
169+
<?xml version="1.0" encoding="UTF-8" ?>
170+
<container xmlns="http://symfony.com/schema/dic/services"
171+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
172+
xsi:schemaLocation="http://symfony.com/schema/dic/services https://symfony.com/schema/dic/services/services-1.0.xsd">
173+
174+
<parameters>
175+
<!-- ... -->
176+
<parameter key="kernel.container_build_time">1234567890</parameter>
177+
</parameters>
178+
</container>
179+
180+
.. code-block:: php
181+
182+
// config/services.php
183+
use Symfony\Component\DependencyInjection\Reference;
184+
185+
// ...
186+
$container->setParameter('kernel.container_build_time', '1234567890');
187+
188+
.. _`reproducible builds`: https://en.wikipedia.org/wiki/Reproducible_builds

0 commit comments

Comments
 (0)
0