Merge branch '5.4' into 6.4

javiereguiluz · javiereguiluz · commit ad1e3b25f027 · 2024-06-24T10:59:31.000+02:00
* 5.4:
  Minor reword
  [DependencyInjection] Clarify the `#[Target]` attribute
diff --git a/service_container/autowiring.rst b/service_container/autowiring.rst
@@ -317,8 +317,8 @@ To fix that, add an :ref:`alias <service-autowiring-alias>`:
 
             App\Util\Rot13Transformer: ~
 
-            # the ``App\Util\Rot13Transformer`` service will be injected when
-            # an ``App\Util\TransformerInterface`` type-hint is detected
+            # the App\Util\Rot13Transformer service will be injected when
+            # an App\Util\TransformerInterface type-hint is detected
             App\Util\TransformerInterface: '@App\Util\Rot13Transformer'
 
     .. code-block:: xml
@@ -422,7 +422,7 @@ type hinted, but use the ``UppercaseTransformer`` implementation in some
 specific cases. To do so, you can create a normal alias from the
 ``TransformerInterface`` interface to ``Rot13Transformer``, and then
 create a *named autowiring alias* from a special string containing the
-interface followed by a variable name matching the one you use when doing
+interface followed by an argument name matching the one you use when doing
 the injection::
 
     // src/Service/MastodonClient.php
@@ -456,13 +456,13 @@ the injection::
             App\Util\Rot13Transformer: ~
             App\Util\UppercaseTransformer: ~
 
-            # the ``App\Util\UppercaseTransformer`` service will be
-            # injected when an ``App\Util\TransformerInterface``
-            # type-hint for a ``$shoutyTransformer`` argument is detected.
+            # the App\Util\UppercaseTransformer service will be
+            # injected when an App\Util\TransformerInterface
+            # type-hint for a $shoutyTransformer argument is detected
             App\Util\TransformerInterface $shoutyTransformer: '@App\Util\UppercaseTransformer'
 
             # If the argument used for injection does not match, but the
-            # type-hint still matches, the ``App\Util\Rot13Transformer``
+            # type-hint still matches, the App\Util\Rot13Transformer
             # service will be injected.
             App\Util\TransformerInterface: '@App\Util\Rot13Transformer'
 
@@ -519,7 +519,7 @@ the injection::
 
             // the App\Util\UppercaseTransformer service will be
             // injected when an App\Util\TransformerInterface
-            // type-hint for a $shoutyTransformer argument is detected.
+            // type-hint for a $shoutyTransformer argument is detected
             $services->alias(TransformerInterface::class.' $shoutyTransformer', UppercaseTransformer::class);
 
             // If the argument used for injection does not match, but the
@@ -545,15 +545,19 @@ If the argument is named ``$shoutyTransformer``,
 But, you can also manually wire any *other* service by specifying the argument
 under the arguments key.
 
-Another possibility is to use the ``#[Target]`` attribute. By using this attribute
-on the argument you want to autowire, you can define exactly which service to inject
-by using its alias. Thanks to this, you're able to have multiple services implementing
-the same interface and keep the argument name decorrelated of any implementation name
-(like shown in the example above).
+Another option is to use the ``#[Target]`` attribute. By adding this attribute
+to the argument you want to autowire, you can specify which service to inject by
+passing the name of the argument used in the named alias. This way, you can have
+multiple services implementing the same interface and keep the argument name
+separate from any implementation name (like shown in the example above).
 
-Let's say you defined the ``app.uppercase_transformer`` alias for the
-``App\Util\UppercaseTransformer`` service. You would be able to use the ``#[Target]``
-attribute like this::
+.. warning::
+
+    The ``#[Target]`` attribute only accepts the name of the argument used in the
+    named alias; it **does not** accept service ids or service aliases.
+
+Suppose you want to inject the ``App\Util\UppercaseTransformer`` service. You would use
+the ``#[Target]`` attribute by passing the name of the ``$shoutyTransformer`` argument::
 
     // src/Service/MastodonClient.php
     namespace App\Service;
@@ -564,12 +568,17 @@ attribute like this::
     class MastodonClient
     {
         public function __construct(
-            #[Target('app.uppercase_transformer')]
+            #[Target('shoutyTransformer')]
             private TransformerInterface $transformer,
-        ){
+        ) {
         }
     }
 
+.. tip::
+
+    Since the ``#[Target]`` attribute normalizes the string passed to it to its
+    camelCased form, name variations (e.g. ``shouty.transformer``) also work.
+
 .. note::
 
     Some IDEs will show an error when using ``#[Target]`` as in the previous example:
