Merge branch '7.4' into 8.0

* 7.4:
  [Asset][Lock][RateLimiter] Use the `#[Target]` attribute in some examples
  [HtmlSanitizer] Use the native HTML5 parser when using PHP 8.4+

Author: javiereguiluz

html_sanitizer.rst

@@ -29,6 +29,13 @@ You can install the HTML Sanitizer component with:
 
     $ composer require symfony/html-sanitizer
 
+.. versionadded:: 7.4
+
+    Starting in Symfony 7.4, applications running on PHP 8.4 or higher will use
+    the native HTML5 parser provided by PHP. All other applications will continue
+    to use the third-party ``masterminds/html5`` parser, which is installed
+    automatically when installing the HTML Sanitizer package.
+
 Basic Usage
 -----------
 

lock.rst

@@ -291,25 +291,42 @@ provides :ref:`named lock <reference-lock-resources-name>`:
             ;
         };
 
-An autowiring alias is created for each named lock with a name using the camel
-case version of its name suffixed by ``LockFactory``.
+After having configured one or more named locks, you have two ways of injecting
+them in any service or controller:
 
-For instance, the ``invoice`` lock can be injected by naming the argument
-``$invoiceLockFactory`` and type-hinting it with
-:class:`Symfony\\Component\\Lock\\LockFactory`::
+**(1) Use a specific argument name**
 
-    // src/Controller/PdfController.php
-    namespace App\Controller;
+Type-hint your construtor/method argument with ``LockFactory`` and name the
+argument using this pattern: "lock name in camelCase" + ``LockFactory`` suffix.
+For example, to inject the ``invoice`` package defined earlier::
 
-    use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
-    use Symfony\Component\HttpFoundation\Response;
     use Symfony\Component\Lock\LockFactory;
 
-    class PdfController extends AbstractController
+    class SomeService
     {
-        #[Route('/download/terms-of-use.pdf')]
-        public function downloadPdf(LockFactory $invoiceLockFactory, MyPdfGeneratorService $pdf): Response
-        {
+        public function __construct(
+            private LockFactory $invoiceLockFactory
+        ): void {
+            // ...
+        }
+    }
+
+**(2) Use the ``#[Target]`` attribute**
+
+When :ref:`dealing with multiple implementations of the same type <autowiring-multiple-implementations-same-type>`
+the ``#[Target]`` attribute helps you select which one to inject. Symfony creates
+a target called "asset package name" + ``.lock.factory`` suffix.
+
+For example, to select the ``invoice`` lock defined earlier::
+
+    // ...
+    use Symfony\Component\DependencyInjection\Attribute\Target;
+
+    class SomeService
+    {
+        public function __construct(
+            #[Target('invoice.lock.factory')] private LockFactory $lockFactory
+        ): void {
             // ...
         }
     }

rate_limiter.rst

@@ -225,10 +225,63 @@ prevents that number from being higher than 5,000).
 Rate Limiting in Action
 -----------------------
 
-After having installed and configured the rate limiter, inject it in any service
-or controller and call the ``consume()`` method to try to consume a given number
-of tokens. For example, this controller uses the previous rate limiter to control
-the number of requests to the API::
+Injecting the Rate Limiter Service
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+After having configured one or more rate limiters, you have two ways of injecting
+them in any service or controller:
+
+**(1) Use a specific argument name**
+
+Type-hint your construtor/method argument with ``RateLimiterFactoryInterface`` and name
+the argument using this pattern: "rate limiter name in camelCase" + ``Limiter`` suffix.
+For example, to inject the ``anonymous_api`` limiter defined earlier, use an
+argument named ``$anonymousApiLimiter``::
+
+    // src/Controller/ApiController.php
+    namespace App\Controller;
+
+    use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
+    use Symfony\Component\HttpFoundation\Response;
+    use Symfony\Component\RateLimiter\RateLimiterFactoryInterface;
+
+    class ApiController extends AbstractController
+    {
+        public function index(RateLimiterFactoryInterface $anonymousApiLimiter): Response
+        {
+            // ...
+        }
+    }
+
+**(2) Use the ``#[Target]`` attribute**
+
+When :ref:`dealing with multiple implementations of the same type <autowiring-multiple-implementations-same-type>`
+the ``#[Target]`` attribute helps you select which one to inject. Symfony creates
+a target called "rate limiter name" + ``.limiter`` suffix.
+
+For example, to select the ``anonymous_api`` limiter defined earlier, use
+``anonymous_api.limiter`` as the target::
+
+    // ...
+    use Symfony\Component\DependencyInjection\Attribute\Target;
+
+    class ApiController extends AbstractController
+    {
+        public function index(
+            #[Target('anonymous_api.limiter')] RateLimiterFactoryInterface $rateLimiter
+        ): Response
+        {
+            // ...
+        }
+    }
+
+Using the Rate Limiter Service
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+After having injected the rate limiter in any service or controller, call the
+``consume()`` method to try to consume a given number of tokens. For example,
+this controller uses the previous rate limiter to control the number of requests
+to the API::
 
     // src/Controller/ApiController.php
     namespace App\Controller;
@@ -241,8 +294,8 @@ the number of requests to the API::
 
     class ApiController extends AbstractController
     {
-        // if you're using service autowiring, the variable name must be:
-        // "rate limiter name" (in camelCase) + "Limiter" suffix
+        // the argument name here is important; read the previous section about
+        // how to inject a specific rate limiter service
         public function index(Request $request, RateLimiterFactoryInterface $anonymousApiLimiter): Response
         {
             // create a limiter based on a unique identifier of the client

reference/configuration/framework.rst

@@ -239,6 +239,46 @@ package:
 
     If a URL is set, the JSON manifest is downloaded on each request using the `http_client`_.
 
+After having configured one or more asset packages, you have two ways of injecting
+them in any service or controller:
+
+**(1) Use a specific argument name**
+
+Type-hint your construtor/method argument with ``PackageInterface`` and name
+the argument using this pattern: "asset package name in camelCase". For example,
+to inject the ``foo_package`` package defined earlier::
+
+    use Symfony\Component\Asset\PackageInterface;
+
+    class SomeService
+    {
+        public function __construct(
+            private PackageInterface $fooPackage
+        ): void {
+            // ...
+        }
+    }
+
+**(2) Use the ``#[Target]`` attribute**
+
+When :ref:`dealing with multiple implementations of the same type <autowiring-multiple-implementations-same-type>`
+the ``#[Target]`` attribute helps you select which one to inject. Symfony creates
+a target called "asset package name" + ``.package`` suffix.
+
+For example, to select the ``foo_package`` package defined earlier::
+
+    // ...
+    use Symfony\Component\DependencyInjection\Attribute\Target;
+
+    class SomeService
+    {
+        public function __construct(
+            #[Target('foo_package.package')] private PackageInterface $package
+        ): void {
+            // ...
+        }
+    }
+
 .. _reference-framework-assets-packages:
 
 packages