Merge branch '6.3' into attributes-overview-6.3

Author: alexandre-daubois

.doctor-rst.yaml

@@ -47,6 +47,7 @@ rules:
     space_between_label_and_link_in_doc: ~
     space_between_label_and_link_in_ref: ~
     string_replacement: ~
+    title_underline_length_must_match_title_length: ~
     typo: ~
     unused_links: ~
     use_deprecated_directive_instead_of_versionadded: ~

.github/workflows/ci.yaml

@@ -73,7 +73,7 @@ jobs:
                     key: ${{ runner.os }}-doctor-rst-${{ steps.extract_base_branch.outputs.branch }}
 
             -   name: "Run DOCtor-RST"
-                uses: docker://oskarstark/doctor-rst:1.40.1
+                uses: docker://oskarstark/doctor-rst:1.41.0
                 with:
                     args: --short --error-format=github --cache-file=/github/workspace/.cache/doctor-rst.cache
 

best_practices.rst

@@ -229,7 +229,7 @@ important parts of your application.
 .. _best-practice-controller-annotations:
 
 Use Attributes or Annotations to Configure Routing, Caching, and Security
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Using attributes or annotations for routing, caching, and security simplifies
 configuration. You don't need to browse several files created with different
@@ -437,7 +437,7 @@ specific tests for each page.
 .. _hardcode-urls-in-a-functional-test:
 
 Hard-code URLs in a Functional Test
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 In Symfony applications, it's recommended to :ref:`generate URLs <routing-generating-urls>`
 using routes to automatically update all links when a URL changes. However, if a

bundles/best_practices.rst

@@ -560,4 +560,3 @@ Learn more
 .. _`valid license identifier`: https://spdx.org/licenses/
 .. _`GitHub Actions`: https://docs.github.com/en/free-pro-team@latest/actions
 .. _`Travis CI`: https://docs.travis-ci.com/
-.. _`Symfony 4.4 bundle documentation`: https://symfony.com/doc/4.4/bundles.html#bundle-directory-structure

components/lock.rst

@@ -70,7 +70,7 @@ method can be safely called repeatedly, even if the lock is already acquired.
     third argument of the ``createLock()`` method to ``false``.
 
 Serializing Locks
-------------------
+-----------------
 
 The :class:`Symfony\\Component\\Lock\\Key` contains the state of the
 :class:`Symfony\\Component\\Lock\\Lock` and can be serialized. This

components/runtime.rst

@@ -3,7 +3,7 @@
    single: Components; Runtime
 
 The Runtime Component
-======================
+=====================
 
     The Runtime Component decouples the bootstrapping logic from any global state
     to make sure the application can run with runtimes like PHP-PM, ReactPHP,

components/serializer.rst

@@ -1000,7 +1000,7 @@ context to pass in these options using the key ``json_encode_options`` or
     $this->serializer->serialize($data, 'json', ['json_encode_options' => \JSON_PRESERVE_ZERO_FRACTION]);
 
 The ``CsvEncoder``
-~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~
 
 The ``CsvEncoder`` encodes to and decodes from CSV.
 

controller.rst

@@ -19,7 +19,7 @@ to render the content of a page.
    single: Controller; Basic example
 
 A Basic Controller
--------------------
+------------------
 
 While a controller can be any PHP callable (function, method on an object,
 or a ``Closure``), a controller is usually a method inside a controller

doctrine.rst

@@ -664,7 +664,7 @@ using the ``MapEntity`` attribute::
 .. tip::
 
     When enabled globally, it's possible to disabled the behavior on a specific
-    controller, by using the ``MapEntity`` set to ``disabled``.
+    controller, by using the ``MapEntity`` set to ``disabled``::
 
         public function show(
             #[CurrentUser]

frontend/encore/bootstrap.rst

@@ -74,7 +74,7 @@ Now, require bootstrap from any of your JavaScript files:
     });
 
 Using Bootstrap with Turbo
----------------------------
+--------------------------
 
 If you are using bootstrap with Turbo Drive, to allow your JavaScript to load on each page change,
 wrap the initialization in a ``turbo:load`` event listener:

frontend/encore/virtual-machine.rst

@@ -93,7 +93,7 @@ connections:
     otherwise other computers can have access to it.
 
 Fix "Invalid Host header" Issue
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Webpack will respond ``Invalid Host header`` when trying to access files from
 the dev-server. To fix this, set the ``allowedHosts`` option:

html_sanitizer.rst

@@ -828,7 +828,7 @@ URLs of ``<a>`` elements:
         );
 
 Force/Allow Media URLs
-~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~
 
 Like :ref:`link URLs <html-sanitizer-link-url>`, you can also control the
 URLs of other media in the HTML. The following attributes are checked by

mercure.rst

@@ -614,7 +614,7 @@ Checkout `the dedicated API Platform documentation`_ to learn more about
 its Mercure support.
 
 Testing
---------
+-------
 
 During unit testing it's usually not needed to send updates to Mercure.
 

reference/attributes.rst

@@ -4,9 +4,9 @@
 Symfony Attributes Overview
 ===========================
 
-Attributes are the successor of annotation since PHP 8. Attributes are native
+Attributes are the successor of annotations since PHP 8. Attributes are native
 to the language and Symfony takes full advantage of them across the framework
-ans its different components.
+and its different components.
 
 Doctrine Bridge
 ~~~~~~~~~~~~~~~

reference/configuration/framework.rst

@@ -1217,7 +1217,7 @@ The value of this option is an associative array of ``domain => IP address``
 (e.g ``['symfony.com' => '46.137.106.254', ...]``).
 
 retry_strategy
-...............
+..............
 
 **type**: ``string``
 

reference/configuration/security.rst

@@ -313,7 +313,7 @@ If ``true``, users are always redirected to the default target path regardless
 of the previous URL that was stored in the session.
 
 default_target_path
-....................
+...................
 
 **type**: ``string`` **default**: ``/``
 

reference/constraints/Expression.rst

@@ -263,7 +263,7 @@ Parameter        Description
 ===============  ==============================================================
 
 ``negate``
-~~~~~~~~~~~
+~~~~~~~~~~
 
 **type**: ``boolean`` **default**: ``true``
 

reference/forms/types/choice.rst

@@ -313,7 +313,7 @@ Field Variables
     faster to use the :ref:`selectedchoice <form-twig-selectedchoice>` test.
 
 Accessing Form Choice Data
-...........................
+..........................
 
 The ``form.vars`` variable of each choice entry holds data such as whether the
 choice is selected or not. If you need to get the full list of choices data and

reference/forms/types/tel.rst

@@ -2,7 +2,7 @@
    single: Forms; Fields; TelType
 
 TelType Field
-===============
+=============
 
 The ``TelType`` field is a text field that is rendered using the HTML5
 ``<input type="tel">`` tag. Following the recommended HTML5 behavior, the value

reference/twig_reference.rst

@@ -127,7 +127,7 @@ and :ref:`reference-assets-json-manifest-path` configuration options.
     Read more about :ref:`linking to web assets from templates <templates-link-to-assets>`.
 
 asset_version
-~~~~~~~~~~~~~~
+~~~~~~~~~~~~~
 
 .. code-block:: twig
 

service_container/lazy_services.rst

@@ -6,7 +6,8 @@ Lazy Services
 
 .. seealso::
 
-    Another way to inject services lazily is via a :doc:`service subscriber </service_container/service_subscribers_locators>`.
+    Other ways to inject services lazily are via a :doc:`service closure </service_container/service_closures>` or
+    :doc:`service subscriber </service_container/service_subscribers_locators>`.
 
 Why Lazy Services?
 ------------------

service_container/service_closures.rst

@@ -0,0 +1,111 @@
+.. index::
+    single: DependencyInjection; Service Closures
+
+Service Closures
+================
+
+This feature wraps the injected service into a closure allowing it to be
+lazily loaded when and if needed.
+This is useful if the service being injected is a bit heavy to instantiate
+or is used only in certain cases.
+The service is instantiated the first time the closure is called, while
+all subsequent calls return the same instance, unless the service is
+:doc:`not shared </service_container/shared>`::
+
+    // src/Service/MyService.php
+    namespace App\Service;
+
+    use Symfony\Component\Mailer\MailerInterface;
+
+    class MyService
+    {
+        /**
+         * @var callable(): MailerInterface
+         */
+        private \Closure $mailer;
+
+        public function __construct(\Closure $mailer)
+        {
+            $this->mailer = $mailer;
+        }
+
+        public function doSomething(): void
+        {
+            // ...
+
+            $this->getMailer()->send($email);
+        }
+
+        private function getMailer(): MailerInterface
+        {
+            return ($this->mailer)();
+        }
+    }
+
+To define a service closure and inject it to another service, create an
+argument of type ``service_closure``:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # config/services.yaml
+        services:
+            App\Service\MyService:
+                arguments: [!service_closure '@mailer']
+
+    .. 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"
+            xsi:schemaLocation="http://symfony.com/schema/dic/services https://symfony.com/schema/dic/services/services-1.0.xsd">
+
+            <services>
+                <service id="App\Service\MyService">
+                    <argument type="service_closure" id="mailer"/>
+                </service>
+            </services>
+        </container>
+
+    .. code-block:: php
+
+        // config/services.php
+        namespace Symfony\Component\DependencyInjection\Loader\Configurator;
+
+        use App\Service\MyService;
+
+        return function (ContainerConfigurator $containerConfigurator) {
+            $services = $containerConfigurator->services();
+
+            $services->set(MyService::class)
+                ->args([service_closure('mailer')]);
+
+            // In case the dependency is optional
+            // $services->set(MyService::class)
+            //     ->args([service_closure('mailer')->ignoreOnInvalid()]);
+        };
+
+.. seealso::
+
+    Another way to inject services lazily is via a
+    :doc:`service locator </service_container/service_subscribers_locators>`.
+
+Using a Service Closure in a Compiler Pass
+------------------------------------------
+
+In :doc:`compiler passes </service_container/compiler_passes>` you can create
+a service closure by wrapping the service reference into an instance of
+:class:`Symfony\\Component\\DependencyInjection\\Argument\\ServiceClosureArgument`::
+
+    use Symfony\Component\DependencyInjection\Argument\ServiceClosureArgument;
+    use Symfony\Component\DependencyInjection\ContainerBuilder;
+    use Symfony\Component\DependencyInjection\Reference;
+
+    public function process(ContainerBuilder $containerBuilder): void
+    {
+        // ...
+
+        $myService->addArgument(new ServiceClosureArgument(new Reference('mailer')));
+    }

service_container/service_subscribers_locators.rst

@@ -12,6 +12,11 @@ instantiation of the services to be lazy. However, that's not possible using
 the explicit dependency injection since services are not all meant to
 be ``lazy`` (see :doc:`/service_container/lazy_services`).
 
+.. seealso::
+
+    Another way to inject services lazily is via a
+    :doc:`service closure </service_container/service_closures>`.
+
 This can typically be the case in your controllers, where you may inject several
 services in the constructor, but the action called only uses some of them.
 Another example are applications that implement the `Command pattern`_

session.rst

@@ -1124,9 +1124,6 @@ These are parameters that you can configure:
 ``expiry_field`` (default ``expires_at``):
     The name of the field where to store the session lifetime.
 
-.. index::
-    single: Sessions, saving locale
-
 Migrating Between Session Handlers
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~