Skip to content

Commit 59aec66

Browse files
committed
minor symfony#11361 Documented the kernel.container_build_time parameter (javiereguiluz)
This PR was squashed before being merged into the 3.4 branch (closes symfony#11361). Discussion ---------- Documented the kernel.container_build_time parameter Commits ------- 9fad870 Documented the kernel.container_build_time parameter
2 parents affe4cf + 9fad870 commit 59aec66

File tree

1 file changed

+102
-23
lines changed

1 file changed

+102
-23
lines changed

reference/configuration/kernel.rst

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

2021
Charset
2122
~~~~~~~
2223

2324
**type**: ``string`` **default**: ``UTF-8``
2425

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

2933
// app/AppKernel.php
3034

@@ -43,16 +47,18 @@ Kernel Name
4347
**type**: ``string`` **default**: ``app`` (i.e. the directory name holding
4448
the kernel class)
4549

46-
To change this setting, override the :method:`Symfony\\Component\\HttpKernel\\Kernel::getName`
47-
method. Alternatively, move your kernel into a different directory. For
48-
example, if you moved the kernel into a ``foo`` directory (instead of ``app``),
49-
the kernel name will be ``foo``.
50-
5150
The name of the kernel isn't usually directly important - it's used in the
5251
generation of cache files. If you have an application with multiple kernels,
5352
the easiest way to make each have a unique name is to duplicate the ``app``
5453
directory and rename it to something else (e.g. ``foo``).
5554

55+
This value is exposed via the ``kernel.name`` configuration parameter and the
56+
:method:`Symfony\\Component\\HttpKernel\\Kernel::getName` method.
57+
58+
To change this setting, override the ``getName()`` method. Alternatively, move
59+
your kernel into a different directory. For example, if you moved the kernel
60+
into a ``foo`` directory (instead of ``app``), the kernel name will be ``foo``.
61+
5662
Root Directory
5763
~~~~~~~~~~~~~~
5864

@@ -63,11 +69,13 @@ Root Directory
6369

6470
**type**: ``string`` **default**: the directory of ``AppKernel``
6571

66-
This returns the root directory of your kernel. If you use the Symfony Standard
67-
edition, the root directory refers to the ``app`` directory.
72+
This returns the absolute path of the directory where your kernel class is
73+
located. If you use the Symfony Standard edition, this is the ``app/`` directory
74+
of your project.
6875

69-
To change this setting, override the
70-
:method:`Symfony\\Component\\HttpKernel\\Kernel::getRootDir` method::
76+
This value is exposed via the ``kernel.root_dir`` configuration parameter and
77+
the :method:`Symfony\\Component\\HttpKernel\\Kernel::getRootDir` method. To
78+
change this setting, override the ``getRootDir()`` method::
7179

7280
// app/AppKernel.php
7381

@@ -91,12 +99,14 @@ Project Directory
9199

92100
**type**: ``string`` **default**: the directory of the project ``composer.json``
93101

94-
This returns the root directory of your Symfony project. It's calculated as
95-
the directory where the main ``composer.json`` file is stored.
102+
This returns the absolute path of the root directory of your Symfony project.
103+
It's calculated automatically as the directory where the main ``composer.json``
104+
file is stored.
96105

97-
If for some reason the ``composer.json`` file is not stored at the root of your
98-
project, you can override the :method:`Symfony\\Component\\HttpKernel\\Kernel::getProjectDir`
99-
method to return the right project directory::
106+
This value is exposed via the ``kernel.project_dir`` configuration parameter and
107+
the :method:`Symfony\\Component\\HttpKernel\\Kernel::getProjectDir` method. To
108+
change this setting, override the ``getProjectDir()`` method to return the right
109+
project directory::
100110

101111
// app/AppKernel.php
102112

@@ -116,15 +126,84 @@ Cache Directory
116126

117127
**type**: ``string`` **default**: ``$this->rootDir/cache/$this->environment``
118128

119-
This returns the path to the cache directory. To change it, override the
120-
:method:`Symfony\\Component\\HttpKernel\\Kernel::getCacheDir` method. Read
121-
":ref:`override-cache-dir`" for more information.
129+
This returns the absolute path of the cache directory of your Symfony project.
130+
It's calculated automatically based on the current
131+
:doc:`environment </configuration/environments>`.
132+
133+
This value is exposed via the ``kernel.cache_dir`` configuration parameter and
134+
the :method:`Symfony\\Component\\HttpKernel\\Kernel::getCacheDir` method. To
135+
change this setting, override the ``getCacheDir()`` method to return the right
136+
cache directory.
122137

123138
Log Directory
124139
~~~~~~~~~~~~~
125140

126141
**type**: ``string`` **default**: ``$this->rootDir/logs``
127142

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

0 commit comments

Comments
 (0)