minor symfony#21382 [Asset][Lock][RateLimiter] Use the #[Target] attribute in some examples (javiereguiluz)

This PR was squashed before being merged into the 6.4 branch.

Discussion
----------

[Asset][Lock][RateLimiter] Use the `#[Target]` attribute in some examples

In symfony#21134 we need to document how much easier is in 7.4 to pick the implementation using the `#[Target]` attribute. But, we don't have many examples of using that attribute in the first place. So, let's add it now and we'll later improve this in 7.4 branch and up.

Still WIP because we need to show the same for Lock and Semaphore.

Commits
-------

5d24590 [Asset][Lock][RateLimiter] Use the `#[Target]` attribute in some examples

Author: javiereguiluz

lock.rst

@@ -284,25 +284,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

@@ -219,10 +219,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 ``RateLimiterFactory`` 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\RateLimiterFactory;
+
+    class ApiController extends AbstractController
+    {
+        public function index(RateLimiterFactory $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')] RateLimiterFactory $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;
@@ -235,8 +288,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, RateLimiterFactory $anonymousApiLimiter): Response
         {
             // create a limiter based on a unique identifier of the client

reference/configuration/framework.rst

@@ -2546,6 +2546,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-assets-strict-mode:
 
 strict_mode