Merge remote-tracking branch 'origin/3.4' into 4.0

* origin/3.4: (22 commits) event constant mistake Updated the default values of some Cache config options Update simple-example.rst to use const for jQuery Update shared-entry.rst to use Bootstrap 4's SCSS Removed an extra blank line Reword and added a note Link to proxy configuration docs from the routing scheme page Fixed typos Fixed security expression testing user Use matching closing tag Better explain render() and render_esi() functions Updated the embed controllers article updating the guard session migration details for Symfony 3.4 changes Avoiding authentication on every request with Guard [Filesystem] Improved the code of an example Removed another usage of mt_rand() Transition from mt_rand to random_int Mentioned Debian explicitly remove not existent label_attr options from buttons Fixed some code indentation ...
weaverryan · Jun 21, 2018 · 6e27e78 · 6e27e78
2 parents 31791c9 + 7ac5f7b
commit 6e27e78
Show file tree

Hide file tree

Showing 23 changed files with 367 additions and 111 deletions.
diff --git a/components/cache/adapters/chain_adapter.rst b/components/cache/adapters/chain_adapter.rst
@@ -46,7 +46,7 @@ slowest storage engines, :class:`Symfony\\Component\\Cache\\Adapter\\ApcuAdapter
     ));
 
 When calling this adapter's :method:`Symfony\\Component\\Cache\\ChainAdapter::prune` method,
-the call is deligated to all its compatibe cache adapters. It is safe to mix both adapters
+the call is delegated to all its compatible cache adapters. It is safe to mix both adapters
 that *do* and do *not* implement :class:`Symfony\\Component\\Cache\\PruneableInterface`, as
 incompatible adapters are silently ignored::
 

diff --git a/components/cache/cache_pools.rst b/components/cache/cache_pools.rst
@@ -146,18 +146,18 @@ Pruning Cache Items
 -------------------
 
 Some cache pools do not include an automated mechanism for pruning expired cache items.
-For example, the :ref:`FilesystemAdaper <component-cache-filesystem-adapter>` cache
+For example, the :ref:`FilesystemAdapter <component-cache-filesystem-adapter>` cache
 does not remove expired cache items *until an item is explicitly requested and determined to
 be expired*, for example, via a call to ``Psr\\Cache\\CacheItemPoolInterface::getItem``.
 Under certain workloads, this can cause stale cache entries to persist well past their
 expiration, resulting in a sizable consumption of wasted disk or memory space from excess,
 expired cache items.
 
-This shortcomming has been solved through the introduction of
+This shortcoming has been solved through the introduction of
 :class:`Symfony\\Component\\Cache\\PruneableInterface`, which defines the abstract method
 :method:`Symfony\\Component\\Cache\\PruneableInterface::prune`. The
 :ref:`ChainAdapter <component-cache-chain-adapter>`,
-:ref:`FilesystemAdaper <component-cache-filesystem-adapter>`,
+:ref:`FilesystemAdapter <component-cache-filesystem-adapter>`,
 :ref:`PdoAdapter <pdo-doctrine-adapter>`, and
 :ref:`PhpFilesAdapter <component-cache-files-adapter>` all implement this new interface,
 allowing manual removal of stale cache items::
@@ -171,7 +171,7 @@ allowing manual removal of stale cache items::
 The :ref:`ChainAdapter <component-cache-chain-adapter>` implementation does not directly
 contain any pruning logic itself. Instead, when calling the chain adapter's
 :method:`Symfony\\Component\\Cache\\ChainAdapter::prune` method, the call is delegated to all
-its compatibe cache adapters (and those that do not implement ``PruneableInterface`` are
+its compatible cache adapters (and those that do not implement ``PruneableInterface`` are
 silently ignored)::
 
     use Symfony\Component\Cache\Adapter\ApcuAdapter;

diff --git a/components/console/events.rst b/components/console/events.rst
@@ -149,7 +149,7 @@ Listeners receive a
 .. tip::
 
     This event is also dispatched when an exception is thrown by the command.
-    It is then dispatched just after the ``ConsoleEvents::EXCEPTION`` event.
+    It is then dispatched just after the ``ConsoleEvents::ERROR`` event.
     The exit code received in this case is the exception code.
 
 .. _`reserved exit codes`: http://www.tldp.org/LDP/abs/html/exitcodes.html
diff --git a/components/filesystem.rst b/components/filesystem.rst
@@ -29,7 +29,7 @@ endpoint for filesystem operations::
     $fileSystem = new Filesystem();
 
     try {
-        $fileSystem->mkdir('/tmp/random/dir/'.mt_rand());
+        $fileSystem->mkdir(sys_get_temp_dir().'/'.random_int(0, 1000));
     } catch (IOExceptionInterface $exception) {
         echo "An error occurred while creating your directory at ".$exception->getPath();
     }

diff --git a/components/http_foundation/session_configuration.rst b/components/http_foundation/session_configuration.rst
@@ -138,8 +138,8 @@ the ``php.ini`` directive ``session.gc_maxlifetime``. The meaning in this contex
 that any stored session that was saved more than ``gc_maxlifetime`` ago should be
 deleted. This allows one to expire records based on idle time.
 
-However, some operating systems do their own session handling and set the
-``session.gc_probability`` variable to ``0`` to stop PHP doing garbage
+However, some operating systems (e.g. Debian) do their own session handling and set
+the ``session.gc_probability`` variable to ``0`` to stop PHP doing garbage
 collection. That's why Symfony now overwrites this value to ``1``.
 
 If you wish to use the original value set in your ``php.ini``, add the following

diff --git a/configuration/external_parameters.rst b/configuration/external_parameters.rst
@@ -140,7 +140,7 @@ Environment Variable Processors
 .. versionadded:: 3.4
     Environment variable processors were introduced in Symfony 3.4.
 
-The values of the environment variables are considered strings by default.
+The values of environment variables are considered strings by default.
 However, your code may expect other data types, like integers or booleans.
 Symfony solves this problem with *processors*, which modify the contents of the
 given environment variables. The following example uses the integer processor to
@@ -159,7 +159,6 @@ turn the value of the ``HTTP_PORT`` env var into an integer:
 
         <!-- config/packages/framework.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"
             xmlns:framework="http://symfony.com/schema/dic/symfony"
@@ -169,57 +168,152 @@ turn the value of the ``HTTP_PORT`` env var into an integer:
                 http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
 
             <framework:config>
-                <framework:router http_port="%env(int:HTTP_PORT)%" />
+                <framework:router http-port="%env(int:HTTP_PORT)%" />
             </framework:config>
         </container>
 
     .. code-block:: php
 
-        // config/packages/doctrine.php
+        // config/packages/framework.php
         $container->loadFromExtension('framework', array(
             'router' => array(
                 'http_port' => '%env(int:HTTP_PORT)%',
-            )
+            ),
         ));
 
 Symfony provides the following env var processors:
 
 ``env(string:FOO)``
     Casts ``FOO`` to a string:
 
-    .. code-block:: yaml
+    .. configuration-block::
 
-        parameters:
-            env(SECRET): "some_secret"
-        framework:
-           secret: '%env(string:SECRET)%'
+        .. code-block:: yaml
+
+            # config/packages/framework.yaml
+            parameters:
+                env(SECRET): 'some_secret'
+            framework:
+               secret: '%env(string:SECRET)%'
+
+        .. code-block:: xml
+
+            <!-- config/packages/framework.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"
+                xmlns:framework="http://symfony.com/schema/dic/symfony"
+                xsi:schemaLocation="http://symfony.com/schema/dic/services
+                    http://symfony.com/schema/dic/services/services-1.0.xsd
+                    http://symfony.com/schema/dic/symfony
+                    http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
+
+                <parameters>
+                    <parameter key="env(SECRET)">some_secret</parameter>
+                </parameters>
+
+                <framework:config secret="%env(string:SECRET)%" />
+            </container>
+
+        .. code-block:: php
+
+            // config/packages/framework.php
+            $container->setParameter('env(SECRET)', 'some_secret');
+            $container->loadFromExtension('framework', array(
+                'secret' => '%env(string:SECRET)%',
+            ));
 
 ``env(bool:FOO)``
     Casts ``FOO`` to a bool:
 
-    .. code-block:: yaml
+    .. configuration-block::
 
-        parameters:
-            env(HTTP_METHOD_OVERRIDE): "true"
-        framework:
-           http_method_override: '%env(bool:HTTP_METHOD_OVERRIDE)%'
+        .. code-block:: yaml
+
+            # config/packages/framework.yaml
+            parameters:
+                env(HTTP_METHOD_OVERRIDE): 'true'
+            framework:
+               http_method_override: '%env(bool:HTTP_METHOD_OVERRIDE)%'
+
+        .. code-block:: xml
+
+            <!-- config/packages/framework.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"
+                xmlns:framework="http://symfony.com/schema/dic/symfony"
+                xsi:schemaLocation="http://symfony.com/schema/dic/services
+                    http://symfony.com/schema/dic/services/services-1.0.xsd
+                    http://symfony.com/schema/dic/symfony
+                    http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
+
+                <parameters>
+                    <parameter key="env(HTTP_METHOD_OVERRIDE)">true</parameter>
+                </parameters>
+
+                <framework:config http-methode-override="%env(bool:HTTP_METHOD_OVERRIDE)%" />
+            </container>
+
+        .. code-block:: php
+
+            // config/packages/framework.php
+            $container->setParameter('env(HTTP_METHOD_OVERRIDE)', 'true');
+            $container->loadFromExtension('framework', array(
+                'http_method_override' => '%env(bool:HTTP_METHOD_OVERRIDE)%',
+            ));
 
 ``env(int:FOO)``
     Casts ``FOO`` to an int.
 
 ``env(float:FOO)``
-    Casts ``FOO`` to an float.
+    Casts ``FOO`` to a float.
 
 ``env(const:FOO)``
     Finds the const value named in ``FOO``:
 
-    .. code-block:: yaml
-
-        parameters:
-            env(HEALTH_CHECK_METHOD): "Symfony\Component\HttpFoundation\Request:METHOD_HEAD"
-        security:
-           access_control:
-             - { path: '^/health-check$', methods: '%env(const:HEALTH_CHECK_METHOD)%' }
+    .. configuration-block::
+
+        .. code-block:: yaml
+
+            # config/packages/security.yaml
+            parameters:
+                env(HEALTH_CHECK_METHOD): 'Symfony\Component\HttpFoundation\Request::METHOD_HEAD'
+            security:
+               access_control:
+                 - { path: '^/health-check$', methods: '%env(const:HEALTH_CHECK_METHOD)%' }
+
+        .. code-block:: xml
+
+            <!-- config/packages/security.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"
+                xmlns:security="http://symfony.com/schema/dic/security"
+                xsi:schemaLocation="http://symfony.com/schema/dic/services
+                    http://symfony.com/schema/dic/services/services-1.0.xsd">
+
+                <parameters>
+                    <parameter key="env(HEALTH_CHECK_METHOD)">Symfony\Component\HttpFoundation\Request::METHOD_HEAD</parameter>
+                </parameters>
+
+                <security:config>
+                    <rule path="^/health-check$" methods="%env(const:HEALTH_CHECK_METHOD)%" />
+                </security:config>
+            </container>
+
+        .. code-block:: php
+
+            // config/packages/security.php
+            $container->setParameter('env(HEALTH_CHECK_METHOD)', 'Symfony\Component\HttpFoundation\Request::METHOD_HEAD');
+            $container->loadFromExtension('security', array(
+                'access_control' => array(
+                    array(
+                        'path' => '^/health-check$',
+                        'methods' => '%env(const:HEALTH_CHECK_METHOD)%',
+                    ),
+                ),
+            ));
 
 ``env(base64:FOO)``
     Decodes the content of ``FOO``, which is a base64 encoded string.
@@ -228,34 +322,123 @@ Symfony provides the following env var processors:
     Decodes the content of ``FOO``, which is a JSON encoded string. It returns
     either an array or ``null``:
 
-    .. code-block:: yaml
+    .. configuration-block::
 
-        parameters:
-            env(TRUSTED_HOSTS): "['10.0.0.1', '10.0.0.2']"
-        framework:
-           trusted_hosts: '%env(json:TRUSTED_HOSTS)%'
+        .. code-block:: yaml
+
+            # config/packages/framework.yaml
+            parameters:
+                env(TRUSTED_HOSTS): '["10.0.0.1", "10.0.0.2"]'
+            framework:
+               trusted_hosts: '%env(json:TRUSTED_HOSTS)%'
+
+        .. code-block:: xml
+
+            <!-- config/packages/framework.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"
+                xmlns:framework="http://symfony.com/schema/dic/symfony"
+                xsi:schemaLocation="http://symfony.com/schema/dic/services
+                    http://symfony.com/schema/dic/services/services-1.0.xsd
+                    http://symfony.com/schema/dic/symfony
+                    http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
+
+                <parameters>
+                    <parameter key="env(TRUSTED_HOSTS)">["10.0.0.1", "10.0.0.2"]</parameter>
+                </parameters>
+
+                <framework:config trusted-hosts="%env(json:TRUSTED_HOSTS)%" />
+            </container>
+
+        .. code-block:: php
+
+            // config/packages/framework.php
+            $container->setParameter('env(TRUSTED_HOSTS)', '["10.0.0.1", "10.0.0.2"]');
+            $container->loadFromExtension('framework', array(
+                'trusted_hosts' => '%env(json:TRUSTED_HOSTS)%',
+            ));
 
 ``env(resolve:FOO)``
     Replaces the string ``FOO`` by the value of a config parameter with the
     same name:
 
-    .. code-block:: yaml
+    .. configuration-block::
 
-        parameters:
-            env(HOST): '10.0.0.1'
-            env(SENTRY_DSN): "http://%env(HOST)%/project"
-        sentry:
-            dsn: '%env(resolve:SENTRY_DSN)%'
+        .. code-block:: yaml
+
+            # config/packages/sentry.yaml
+            parameters:
+                env(HOST): '10.0.0.1'
+                env(SENTRY_DSN): 'http://%env(HOST)%/project'
+            sentry:
+                dsn: '%env(resolve:SENTRY_DSN)%'
+
+        .. code-block:: xml
+
+            <!-- config/packages/sentry.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
+                    http://symfony.com/schema/dic/services/services-1.0.xsd">
+
+                <parameters>
+                    <parameter key="env(HOST)">10.0.0.1</parameter>
+                    <parameter key="env(SENTRY_DSN)">http://%env(HOST)%/project</parameter>
+                </parameters>
+
+                <sentry:config dsn="%env(resolve:SENTRY_DSN)%" />
+            </container>
+
+        .. code-block:: php
+
+            // config/packages/sentry.php
+            $container->setParameter('env(HOST)', '10.0.0.1');
+            $container->setParameter('env(SENTRY_DSN)', 'http://%env(HOST)%/project');
+            $container->loadFromExtension('sentry', array(
+                'dsn' => '%env(resolve:SENTRY_DSN)%',
+            ));
 
 ``env(file:FOO)``
     Returns the contents of a file whose path is the value of the ``FOO`` env var:
 
-    .. code-block:: yaml
+    .. configuration-block::
 
-        parameters:
-            env(AUTH_FILE): "../config/auth.json"
-        google:
-           auth: '%env(file:AUTH_FILE)%'
+        .. code-block:: yaml
+
+            # config/packages/framework.yaml
+            parameters:
+                env(AUTH_FILE): '../config/auth.json'
+            google:
+                auth: '%env(file:AUTH_FILE)%'
+
+        .. code-block:: xml
+
+            <!-- config/packages/framework.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"
+                xmlns:framework="http://symfony.com/schema/dic/symfony"
+                xsi:schemaLocation="http://symfony.com/schema/dic/services
+                    http://symfony.com/schema/dic/services/services-1.0.xsd
+                    http://symfony.com/schema/dic/symfony
+                    http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
+
+                <parameters>
+                    <parameter key="env(AUTH_FILE)">../config/auth.json</parameter>
+                </parameters>
+
+                <google auth="%env(file:AUTH_FILE)%" />
+            </container>
+
+        .. code-block:: php
+
+            // config/packages/framework.php
+            $container->setParameter('env(AUTH_FILE)', '../config/auth.json');
+            $container->loadFromExtension('google', array(
+                'auth' => '%env(file:AUTH_FILE)%',
+            ));
 
 It is also possible to combine any number of processors: