symfony · hmoreau · May 31, 2022 · Jun 2, 2022 · Jun 2, 2022 · Jun 2, 2022
diff --git a/_build/maintainer_guide.rst b/_build/maintainer_guide.rst
@@ -39,22 +39,22 @@ contributes again, it's OK to mention some of the minor issues to educate them.
 
     $ gh merge 11059
 
-      Working on symfony/symfony-docs (branch 6.1)
+      Working on symfony/symfony-docs (branch 6.2)
       Merging Pull Request 11059: dmaicher/patch-3
 
       ...
 
       # This is important!! Say NO to push the changes now
       Push the changes now? (Y/n) n
-      Now, push with: git push gh "6.1" refs/notes/github-comments
+      Now, push with: git push gh "6.2" refs/notes/github-comments
 
       # Now, open your editor and make the needed changes ...
 
       $ git commit -a
       # Use "Minor reword", "Minor tweak", etc. as the commit message
 
       # now run the 'push' command shown above by 'gh' (it's different each time)
-      $ git push gh "6.1" refs/notes/github-comments
+      $ git push gh "6.2" refs/notes/github-comments
 
 Merging Pull Requests
 ---------------------

diff --git a/best_practices.rst b/best_practices.rst
@@ -234,14 +234,6 @@ configuration. You don't need to browse several files created with different
 formats (YAML, XML, PHP): all the configuration is just where you need it and
 it only uses one format.
 
-Don't Use Annotations to Configure the Controller Template
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The ``@Template`` annotation is useful, but also involves some *magic*.
-Moreover, most of the time ``@Template`` is used without any parameters, which
-makes it more difficult to know which template is being rendered. It also hides
-the fact that a controller should always return a ``Response`` object.
-
 Use Dependency Injection to Get Services
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

diff --git a/components/expression_language/syntax.rst b/components/expression_language/syntax.rst
@@ -343,6 +343,23 @@ Ternary Operators
 * ``foo ?: 'no'`` (equal to ``foo ? foo : 'no'``)
 * ``foo ? 'yes'`` (equal to ``foo ? 'yes' : ''``)
 
+Null Coalescing Operator
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+This is the same as the PHP `null-coalescing operator`_, which combines
+the ternary operator and ``isset()``. It returns the left hand-side if it exists
+and it's not ``null``; otherwise it returns the right hand-side. Note that you
+can chain multiple coalescing operators.
+
+* ``foo ?? 'no'``
+* ``foo.baz ?? 'no'``
+* ``foo[3] ?? 'no'``
+* ``foo.baz ?? foo['baz'] ?? 'no'``
+
+.. versionadded:: 6.2
+
+    The null-coalescing operator was introduced in Symfony 6.2.
+
 Built-in Objects and Variables
 ------------------------------
 

diff --git a/components/finder.rst b/components/finder.rst
@@ -336,12 +336,17 @@ instance. The file is excluded from the result set if the Closure returns
 Sorting Results
 ---------------
 
-Sort the results by name or by type (directories first, then files)::
+Sort the results by name, extension, size or type (directories first, then files)::
 
     $finder->sortByName();
-
+    $finder->sortByExtension();
+    $finder->sortBySize();
     $finder->sortByType();
 
+.. versionadded:: 6.2
+
+    The ``sortByExtension()`` and ``sortBySize()`` methods were introduced in Symfony 6.2.
+
 .. tip::
 
     By default, the ``sortByName()`` method uses the :phpfunction:`strcmp` PHP

diff --git a/components/http_kernel.rst b/components/http_kernel.rst
@@ -409,12 +409,12 @@ return a ``Response``.
 
 .. sidebar:: ``kernel.view`` in the Symfony Framework
 
-    There is no default listener inside the Symfony Framework for the ``kernel.view``
-    event. However, `SensioFrameworkExtraBundle`_ *does* add a listener to this
-    event. If your controller returns an array, and you place the `@Template`_
-    annotation above the controller, then this listener renders a template,
-    passes the array you returned from your controller to that template, and
-    creates a ``Response`` containing the returned content from that template.
+    There is a default listener inside the Symfony Framework for the ``kernel.view``
+    event. If your controller action returns an array, and you apply the
+    :ref:`#[Template()] attribute <templates-template-attribute>` to that
+    controller action, then this listener renders a template, passes the array
+    you returned from your controller to that template, and creates a ``Response``
+    containing the returned content from that template.
 
     Additionally, a popular community bundle `FOSRestBundle`_ implements
     a listener on this event which aims to give you a robust view layer
@@ -751,5 +751,4 @@ Learn more
 .. _`PHP FPM`: https://www.php.net/manual/en/install.fpm.php
 .. _`SensioFrameworkExtraBundle`: https://symfony.com/doc/current/bundles/SensioFrameworkExtraBundle/index.html
 .. _`@ParamConverter`: https://symfony.com/doc/current/bundles/SensioFrameworkExtraBundle/annotations/converters.html
-.. _`@Template`: https://symfony.com/doc/current/bundles/SensioFrameworkExtraBundle/annotations/view.html
 .. _variadic: https://www.php.net/manual/en/functions.arguments.php#functions.variable-arg-list
diff --git a/components/uid.rst b/components/uid.rst
@@ -84,6 +84,11 @@ Use these methods to transform the UUID object into different bases::
     $uuid->toBase32();  // string(26) "6SWYGR8QAV27NACAHMK5RG0RPG"
     $uuid->toBase58();  // string(22) "TuetYWNHhmuSQ3xPoVLv9M"
     $uuid->toRfc4122(); // string(36) "d9e7a184-5d5b-11ea-a62a-3499710062d0"
+    $uuid->toHex();     // string(34) "0xd9e7a1845d5b11eaa62a3499710062d0"
+
+.. versionadded:: 6.2
+
+    The ``toHex()`` method was introduced in Symfony 6.2.
 
 Working with UUIDs
 ~~~~~~~~~~~~~~~~~~
@@ -258,6 +263,11 @@ Use these methods to transform the ULID object into different bases::
     $ulid->toBase32();  // string(26) "01E439TP9XJZ9RPFH3T1PYBCR8"
     $ulid->toBase58();  // string(22) "1BKocMc5BnrVcuq2ti4Eqm"
     $ulid->toRfc4122(); // string(36) "0171069d-593d-97d3-8b3e-23d06de5b308"
+    $ulid->toHex();     // string(34) "0x0171069d593d97d38b3e23d06de5b308"
+
+.. versionadded:: 6.2
+
+    The ``toHex()`` method was introduced in Symfony 6.2.
 
 Working with ULIDs
 ~~~~~~~~~~~~~~~~~~

@@ -338,6 +338,35 @@ syntax to parse them as proper PHP constants::
     $parameters = Yaml::parse($yaml, Yaml::PARSE_CONSTANT);
     // $parameters = ['foo' => 'PHP_INT_SIZE', 'bar' => 8];
 
+Parsing PHP Enumerations
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+The YAML parser supports `PHP enumerations`_, both unit and backed enums.
+By default, they are parsed as regular strings. Use the ``PARSE_CONSTANT`` flag
+and the special ``!php/enum`` syntax to parse them as proper PHP enums::
+
+    enum FooEnum: string
+    {
+        case Foo = 'foo';
+        case Bar = 'bar';
+    }
+
+    // ...
+
+    $yaml = '{ foo: FooEnum::Foo, bar: !php/enum FooEnum::Foo }';
+    $parameters = Yaml::parse($yaml, Yaml::PARSE_CONSTANT);
+    // the value of the 'foo' key is a string because it missed the `!php/enum` syntax
+    // $parameters = ['foo' => 'FooEnum::Foo', 'bar' => FooEnum::Foo];
+
+    $yaml = '{ foo: FooEnum::Foo, bar: !php/enum FooEnum::Foo->value }';
+    $parameters = Yaml::parse($yaml, Yaml::PARSE_CONSTANT);
+    // the value of the 'foo' key is a string because it missed the `!php/enum` syntax
+    // $parameters = ['foo' => 'FooEnum::Foo', 'bar' => 'foo'];
+
+.. versionadded:: 6.2
+
+    The support for PHP enumerations was introduced in Symfony 6.2.
+
 Parsing and Dumping of Binary Data
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -460,3 +489,4 @@ Learn More
 .. _`YAML`: https://yaml.org/
 .. _`YAML 1.2 version specification`: https://yaml.org/spec/1.2/spec.html
 .. _`ISO-8601`: https://www.iso.org/iso-8601-date-and-time-format.html
+.. _`PHP enumerations`: https://www.php.net/manual/en/language.types.enumerations.php
diff --git a/configuration.rst b/configuration.rst
@@ -847,6 +847,13 @@ Use the ``debug:dotenv`` command to understand how Symfony parses the different
      ALICE      BOB     BOB        bob
     ---------- ------- ---------- ------
 
+    # look for a specific variable passing its full or partial name as an argument
+    $ php bin/console debug:dotenv foo
+
+.. versionadded:: 6.2
+
+    The option to pass variable names to ``debug:dotenv`` was introduced in Symfony 6.2.
+
 Additionally, and regardless of how you set environment variables, you can see all
 environment variables, with their values, referenced in Symfony's container configuration:
 

diff --git a/configuration/env_var_processors.rst b/configuration/env_var_processors.rst
@@ -379,6 +379,59 @@ Symfony provides the following env var processors:
                 $framework->trustedHosts(env('TRUSTED_HOSTS')->csv());
             };
 
+``env(shuffle:FOO)``
+    Randomly shuffles values of the ``FOO`` env var, which must be an array.
+
+    .. configuration-block::
+
+        .. code-block:: yaml
+
+            # config/packages/framework.yaml
+            parameters:
+                env(REDIS_NODES): "127.0.0.1:6380,127.0.0.1:6381"
+            services:
+                RedisCluster:
+                    class: RedisCluster
+                    arguments: [null, "%env(shuffle:csv:REDIS_NODES)%"]
+
+        .. 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
+                    https://symfony.com/schema/dic/services/services-1.0.xsd
+                    http://symfony.com/schema/dic/symfony
+                    https://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
+
+                <parameters>
+                    <parameter key="env(REDIS_NODES)">redis://127.0.0.1:6380,redis://127.0.0.1:6381</parameter>
+                </parameters>
+
+                <services>
+                    <service id="RedisCluster" class="RedisCluster">
+                        <argument>null</argument>
+                        <argument>%env(shuffle:csv:REDIS_NODES)%</argument>
+                    </service>
+                </services>
+            </container>
+
+        .. code-block:: php
+
+            // config/services.php
+            use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;
+
+            return static function (ContainerConfigurator $configurator): void {
+                $container = $configurator->services()
+                    ->set(\RedisCluster::class, \RedisCluster::class)->args([null, '%env(shuffle:csv:REDIS_NODES)%']);
+            };
+
+    .. versionadded:: 6.2
+
+        The ``env(shuffle:...)`` env var processor was introduced in Symfony 6.2.
+
 ``env(file:FOO)``
     Returns the contents of a file whose path is the value of the ``FOO`` env var:
 
@@ -698,6 +751,53 @@ Symfony provides the following env var processors:
                 ],
             ]);
 
+``env(enum:FooEnum:BAR)``
+    Tries to convert an environment variable to an actual ``\BackedEnum`` value.
+    This processor takes the fully qualified name of the ``\BackedEnum`` as an argument.
+
+    .. code-block:: php
+
+        # App\Enum\Environment
+        enum Environment: string
+        {
+            case Development = 'dev';
+            case Production = 'prod';
+        }
+
+    .. configuration-block::
+
+        .. code-block:: yaml
+
+            # config/services.yaml
+            parameters:
+                typed_env: '%env(enum:App\Enum\Environment:APP_ENV)%'
+
+        .. 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"
+                xmlns:framework="http://symfony.com/schema/dic/symfony"
+                xsi:schemaLocation="http://symfony.com/schema/dic/services
+                    https://symfony.com/schema/dic/services/services-1.0.xsd
+                    http://symfony.com/schema/dic/symfony
+                    https://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
+
+                <parameters>
+                    <parameter key="typed_env">%env(enum:App\Enum\Environment:APP_ENV)%</parameter>
+                </parameters>
+            </container>
+
+        .. code-block:: php
+
+            // config/services.php
+            $container->setParameter('typed_env', '%env(enum:App\Enum\Environment:APP_ENV)%');
+
+    .. versionadded:: 6.2
+
+        The ``env(enum:...)`` env var processor was introduced in Symfony 6.2.
+
 It is also possible to combine any number of processors:
 
 .. configuration-block::

diff --git a/console/style.rst b/console/style.rst
@@ -324,6 +324,16 @@ User Input Methods
 
         $io->choice('Select the queue to analyze', ['queue1', 'queue2', 'queue3'], 'queue1');
 
+    Finally, you can allow users to select multiple choices. To do so, users must
+    separate each choice with a comma (e.g. typing ``1, 2`` will select choice 1
+    and 2)::
+
+        $io->choice('Select the queue to analyze', ['queue1', 'queue2', 'queue3'], multiSelect: true);
+
+.. versionadded:: 6.2
+
+    The ``multiSelect`` option of ``choice()`` was introduced in Symfony 6.2.
+
 Result Methods
 ~~~~~~~~~~~~~~
 

diff --git a/controller/argument_value_resolver.rst b/controller/argument_value_resolver.rst
@@ -252,10 +252,10 @@ retrieved from the token storage::
     namespace App\ArgumentResolver;
 
     use App\Entity\User;
+    use Symfony\Bundle\SecurityBundle\Security\Security;
     use Symfony\Component\HttpFoundation\Request;
     use Symfony\Component\HttpKernel\Controller\ArgumentValueResolverInterface;
     use Symfony\Component\HttpKernel\ControllerMetadata\ArgumentMetadata;
-    use Symfony\Component\Security\Core\Security;
 
     class UserValueResolver implements ArgumentValueResolverInterface
     {

diff --git a/form/dynamic_form_modification.rst b/form/dynamic_form_modification.rst
@@ -233,7 +233,7 @@ The problem is now to get the current user and create a choice field that
 contains only this user's friends. This can be done injecting the ``Security``
 service into the form type so you can get the current user object::
 
-    use Symfony\Component\Security\Core\Security;
+    use Symfony\Bundle\SecurityBundle\Security\Security;
     // ...
 
     class FriendMessageFormType extends AbstractType
@@ -260,9 +260,9 @@ security helper to fill in the listener logic::
     use App\Entity\User;
     use Doctrine\ORM\EntityRepository;
     use Symfony\Bridge\Doctrine\Form\Type\EntityType;
+    use Symfony\Bundle\SecurityBundle\Security\Security;
     use Symfony\Component\Form\Extension\Core\Type\TextareaType;
     use Symfony\Component\Form\Extension\Core\Type\TextType;
-    use Symfony\Component\Security\Core\Security;
     // ...
 
     class FriendMessageFormType extends AbstractType