Merge remote-tracking branch 'upstream/6.2' into 6.2

* upstream/6.2:
  Add the versionadded directive
  Minor tweak
  [Kernel] Mention extra interfaces in `MicroKernel` section
  Minor typo
  Minor tweaks
  Minor rewords
  [Messenger] Add new `messenger:stats` command that return a list of transports with their "to be processed" message count.
  Minor tweaks
  [Console] Update console.rst
  [Uuid] 17258 Add documentation for Uuid 7 and 8
  Mailer: remove port 99 for requestbin.com
  [Testing] Add a section to mock service dependencies
  document default context for the serializer

Author: OskarStark

components/uid.rst

@@ -63,6 +63,21 @@ to create each type of UUID::
     // It's defined in http://gh.peabody.io/uuidv6/
     $uuid = Uuid::v6(); // $uuid is an instance of Symfony\Component\Uid\UuidV6
 
+    // UUID version 7 features a time-ordered value field derived from the well known
+    // Unix Epoch timestamp source: the number of seconds since midnight 1 Jan 1970 UTC, leap seconds excluded.
+    // As well as improved entropy characteristics over versions 1 or 6.
+    $uuid = Uuid::v7();
+
+    // UUID version 8 provides an RFC-compatible format for experimental or vendor-specific use cases.
+    // The only requirement is that the variant and version bits MUST be set as defined in Section 4:
+    // https://www.ietf.org/archive/id/draft-peabody-dispatch-new-uuid-format-04.html#variant_and_version_fields
+    // UUIDv8 uniqueness will be implementation-specific and SHOULD NOT be assumed.
+    $uuid = Uuid::v8();
+
+.. versionadded:: 6.2
+
+    UUID versions 7 and 8 were introduced in Symfony 6.2.
+
 If your UUID value is already generated in another format, use any of the
 following methods to create a ``Uuid`` object from it::
 

configuration/micro_kernel_trait.rst

@@ -99,6 +99,44 @@ that define your bundles, your services and your routes:
     ``RoutingConfigurator`` has methods that make adding routes in PHP more
     fun. You can also load external routing files (shown below).
 
+Adding Interfaces to "Micro" Kernel
+-----------------------------------
+
+When using the ``MicroKernelTrait``, you can also implement the
+``CompilerPassInterface`` to automatically register the kernel itself as a
+compiler pass as explained in the dedicated
+:ref:`compiler pass section <kernel-as-compiler-pass>`.
+
+It is also possible to implement the ``EventSubscriberInterface`` to handle
+events directly from the kernel, again it will be registered automatically::
+
+    // ...
+    use App\Exception\Danger;
+    use Symfony\Component\EventDispatcher\EventSubscriberInterface;
+    use Symfony\Component\HttpKernel\Event\ExceptionEvent;
+    use Symfony\Component\HttpKernel\KernelEvents;
+
+    class Kernel extends BaseKernel implements EventSubscriberInterface
+    {
+        use MicroKernelTrait;
+
+        // ...
+
+        public function onKernelException(ExceptionEvent $event): void
+        {
+            if ($event->getException() instanceof Danger) {
+                $event->setResponse(new Response('It\'s dangerous to go alone. Take this ⚔'));
+            }
+        }
+
+        public static function getSubscribedEvents(): array
+        {
+            return [
+                KernelEvents::EXCEPTION => 'onKernelException',
+            ];
+        }
+    }
+
 Advanced Example: Twig, Annotations and the Web Debug Toolbar
 -------------------------------------------------------------
 

console.rst

@@ -334,6 +334,12 @@ method, which returns an instance of
             $section1->clear(2);
             // Output is now completely empty!
 
+            // setting the max height of a section will make new lines replace the old ones
+            $section1->setMaxHeight(2);
+            $section1->writeln('Line1');
+            $section1->writeln('Line2');
+            $section1->writeln('Line3');
+
             return Command::SUCCESS;
         }
     }
@@ -342,6 +348,10 @@ method, which returns an instance of
 
     A new line is appended automatically when displaying information in a section.
 
+.. versionadded:: 6.2
+
+    The feature to limit the height of a console section was introduced in Symfony 6.2.
+
 Output sections let you manipulate the Console output in advanced ways, such as
 :ref:`displaying multiple progress bars <console-multiple-progress-bars>` which
 are updated independently and :ref:`appending rows to tables <console-modify-rendered-tables>`

mailer.rst

@@ -202,7 +202,6 @@ Infobip              infobip+smtp://KEY@default                           n/a
 
         # .env
         MAILER_DSN=mailgun+https://KEY:DOMAIN@requestbin.com
-        MAILER_DSN=mailgun+https://KEY:DOMAIN@requestbin.com:99
 
     Note that the protocol is *always* HTTPs and cannot be changed.
 

messenger.rst

@@ -640,8 +640,35 @@ You can limit the worker to only process messages from specific queue(s):
     # you can pass the --queues option more than once to process multiple queues
     $ php bin/console messenger:consume my_transport --queues=fasttrack1 --queues=fasttrack2
 
-To allow using the ``queues`` option, the receiver must implement the
-:class:`Symfony\\Component\\Messenger\\Transport\\Receiver\\QueueReceiverInterface`.
+.. note::
+
+    To allow using the ``queues`` option, the receiver must implement the
+    :class:`Symfony\\Component\\Messenger\\Transport\\Receiver\\QueueReceiverInterface`.
+
+.. _messenger-message-count:
+
+Checking the Number of Queued Messages Per Transport
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Run the ``messenger:stats`` command to know how many messages are in the "queues"
+of some or all transports:
+
+.. code-block:: terminal
+
+    # displays the number of queued messages in all transports
+    $ php bin/console messenger:stats
+
+    # shows stats only for some transports
+    $ php bin/console messenger:stats my_transport_name other_transport_name
+
+.. note::
+    
+    In order for this command to work, the configured transport's receiver must implement
+    :class:`Symfony\\Component\\Messenger\\Transport\\Receiver\\MessageCountAwareInterface`.
+
+.. versionadded:: 6.2
+
+    The ``messenger:stats`` command was introduced in Symfony 6.2.
 
 .. _messenger-supervisor:
 

reference/configuration/framework.rst

@@ -2764,6 +2764,9 @@ A map with default context options that will be used with each ``serialize`` and
 call. This can be used for example to set the json encoding behavior by setting ``json_encode_options``
 to a `json_encode flags bitmask`_.
 
+You can inspect the :ref:`serializer context builders <serializer-using-context-builders>`
+to discover the available settings.
+
 php_errors
 ~~~~~~~~~~
 

reference/constraints/Uuid.rst

@@ -112,19 +112,24 @@ will allow alternate input formats like:
 ``versions``
 ~~~~~~~~~~~~
 
-**type**: ``int[]`` **default**: ``[1,2,3,4,5,6]``
+**type**: ``int[]`` **default**: ``[1,2,3,4,5,6,7,8]``
 
-This option can be used to only allow specific `UUID versions`_.  Valid versions are 1 - 6.
-The following PHP constants can also be used:
+This option can be used to only allow specific `UUID versions`_ (by default, all
+of them are allowed). Valid versions are 1 - 8. Instead of using numeric values,
+you can also use the following PHP constants to refer to each UUID version:
 
 * ``Uuid::V1_MAC``
 * ``Uuid::V2_DCE``
 * ``Uuid::V3_MD5``
 * ``Uuid::V4_RANDOM``
 * ``Uuid::V5_SHA1``
 * ``Uuid::V6_SORTABLE``
+* ``Uuid::V7_MONOTONIC``
+* ``Uuid::V8_CUSTOM``
 
-All six versions are allowed by default.
+.. versionadded:: 6.2
+
+    UUID versions 7 and 8 were introduced in Symfony 6.2.
 
 .. _`Universally unique identifier (UUID)`: https://en.wikipedia.org/wiki/Universally_unique_identifier
 .. _`RFC 4122`: https://tools.ietf.org/html/rfc4122

serializer.rst

@@ -130,14 +130,15 @@ configuration:
             serializer:
                 default_context:
                     enable_max_depth: true
+                    yaml_indentation: 2
 
     .. code-block:: xml
 
         <!-- config/packages/framework.xml -->
         <framework:config>
             <!-- ... -->
             <framework:serializer>
-                <default-context enable-max-depth="true"/>
+                <default-context enable-max-depth="true" yaml-indentation="2"/>
             </framework:serializer>
         </framework:config>
 
@@ -146,15 +147,21 @@ configuration:
         // config/packages/framework.php
         use Symfony\Config\FrameworkConfig;
         use Symfony\Component\Serializer\Normalizer\AbstractObjectNormalizer;
+        use Symfony\Component\Serializer\Encoder\YamlEncoder;
 
         return static function (FrameworkConfig $framework) {
             $framework->serializer()
                 ->defaultContext([
-                    AbstractObjectNormalizer::ENABLE_MAX_DEPTH => true
+                    AbstractObjectNormalizer::ENABLE_MAX_DEPTH => true,
+                    YamlEncoder::YAML_INDENTATION => 2,
                 ])
             ;
         };
 
+.. versionadded:: 6.2
+
+    The option to configure YAML indentation was introduced in Symfony 6.2.
+
 .. _serializer-using-context-builders:
 
 Using Context Builders

service_container/compiler_passes.rst

@@ -32,6 +32,8 @@ Compiler passes are registered in the ``build()`` method of the application kern
         }
     }
 
+.. _kernel-as-compiler-pass:
+
 One of the most common use-cases of compiler passes is to work with :doc:`tagged
 services </service_container/tags>`. In those cases, instead of creating a
 compiler pass, you can make the kernel implement

testing.rst

@@ -281,6 +281,91 @@ It gives you access to both the public services and the non-removed
     are not used by any other services), you need to declare those private
     services as public in the ``config/services_test.yaml`` file.
 
+Mocking Dependencies
+--------------------
+
+Sometimes it can be useful to mock a dependency of a tested service.
+From the example in the previous section, let's assume the
+``NewsletterGenerator`` has a dependency to a private alias
+``NewsRepositoryInterface`` pointing to a private ``NewsRepository`` service
+and you'd like to use a mocked ``NewsRepositoryInterface`` instead of the
+concrete one::
+
+    // ...
+    use App\Contracts\Repository\NewsRepositoryInterface;
+
+    class NewsletterGeneratorTest extends KernelTestCase
+    {
+        public function testSomething()
+        {
+            // ... same bootstrap as the section above
+
+            $newsRepository = $this->createMock(NewsRepositoryInterface::class);
+            $newsRepository->expects(self::once())
+                ->method('findNewsFromLastMonth')
+                ->willReturn([
+                    new News('some news'),
+                    new News('some other news'),
+                ])
+            ;
+
+            // the following line won't work unless the alias is made public
+            $container->set(NewsRepositoryInterface::class, $newsRepository);
+
+            // will be injected the mocked repository
+            $newsletterGenerator = $container->get(NewsletterGenerator::class);
+
+            // ...
+        }
+    }
+
+In order to make the alias public, you will need to update configuration for
+the ``test`` environment as follows:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # config/services_test.yaml
+        services:
+            # redefine the alias as it should be while making it public
+            App\Contracts\Repository\NewsRepositoryInterface:
+                alias: App\Repository\NewsRepository
+                public: true
+
+    .. code-block:: xml
+
+        <!-- config/services_test.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
+                https://symfony.com/schema/dic/services/services-1.0.xsd
+        ">
+            <services>
+                <!-- redefine the alias as it should be while making it public -->
+                <service id="App\Contracts\Repository\NewsRepositoryInterface"
+                    alias="App\Repository\NewsRepository"
+                />
+            </services>
+        </container>
+
+    .. code-block:: php
+
+        // config/services_test.php
+        namespace Symfony\Component\DependencyInjection\Loader\Configurator;
+
+        use App\Contracts\Repository\NewsRepositoryInterface;
+        use App\Repository\NewsRepository;
+
+        return static function (ContainerConfigurator $container) {
+            $container->services()
+                // redefine the alias as it should be while making it public
+                ->alias(NewsRepositoryInterface::class, NewsRepository::class)
+                    ->public()
+            ;
+        };
+
 .. _testing-databases:
 
 Configuring a Database for Tests