feature #30348 [DependencyInjection] Add ability to define an index f…

…or service in an injected service locator argument (XuruDragon, nicolas-grekas)

This PR was merged into the 4.3-dev branch.

Discussion
----------

[DependencyInjection] Add ability to define an index for service in an injected service locator argument

| Q             | A
| ------------- | ---
| Branch?       | master
| Bug fix?      | no
| New feature?  | yes
| BC breaks?    | no
| Deprecations? | no
| Tests pass?   | yes
| Fixed tickets | n/a
| License       | MIT
| Doc PR        | in progress /  symfony/symfony-docs#...

It's more or less the same thing then the PR #30257 but for a service locator argument

Add a simple way to specify an index based on a tag attribute to simplify retrieving a specific service when injecting a service locator as argument into services, but also a way to fallback to a static method on the service class.

Yaml:
```yaml
services:
  foo_service:
    class: Foo
    tags:
      - {name: foo_tag, key: foo_service}
  foo_service_tagged:
    class: Bar
    arguments:
      - !tagged_locator
          tag: 'foo_tag'
          index_by: 'key'
          default_index_method: 'static_method'
```
XML:
```xml
<?xml version="1.0" ?>

<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
    http://symfony.com/schema/dic/services/services-1.0.xsd">
  <services>
    <service id="foo" class="Foo">
        <tag name="foo_tag" key="foo_service" />
    </service>
    <service id="foo_tagged_iterator" class="Bar" public="true">
      <argument type="tagged_locator" tag="foo_tag" index-by="key" default-index-method="static_method" />
    </service>
  </services>
</container>
```
PHP:
```php
// config/services.php
use Symfony\Component\DependencyInjection\Argument\TaggedIteratorArgument;
use Symfony\Component\DependencyInjection\Argument\ServiceLocatorArgument;

$container->register(Foo::class)
        ->addTag('foo_tag', ['key' => 'foo_service']);

$container->register(App\Handler\HandlerCollection::class)
         // inject all services tagged with app.handler as first argument
         ->addArgument(new ServiceLocatorArgument(new TaggedIteratorArgument('app.handler', 'key')));
```

Usage:
```php
// src/Handler/HandlerCollection.php
namespace App\Handler;

use Symfony\Component\DependencyInjection\ServiceLocator;

class HandlerCollection
{
     public function __construct(ServiceLocator $serviceLocator)
     {
           $foo = $serviceLocator->get('foo_service'):
     }
}
```

Tasks

* [x]  Support PHP loader/dumper
* [x]  Support YAML loader/dumper
* [x]  Support XML loader/dumper (and update XSD too)
* [x]  Add tests
* [x]  Documentation

Commits
-------

cb3c56b Support indexing tagged locators by FQCN as fallback
250a2c8 [DI] Allow tagged_locator tag to be used as an argument

src/Symfony/Component/DependencyInjection/Argument/ServiceLocatorArgument.php

@@ -11,6 +11,8 @@
 
 namespace Symfony\Component\DependencyInjection\Argument;
 
+use Symfony\Component\DependencyInjection\Reference;
+
 /**
  * Represents a closure acting as a service locator.
  *
@@ -19,4 +21,24 @@
 class ServiceLocatorArgument implements ArgumentInterface
 {
     use ReferenceSetArgumentTrait;
+
+    private $taggedIteratorArgument;
+
+    /**
+     * @param Reference[]|TaggedIteratorArgument $values
+     */
+    public function __construct($values = [])
+    {
+        if ($values instanceof TaggedIteratorArgument) {
+            $this->taggedIteratorArgument = $values;
+            $this->values = [];
+        } else {
+            $this->setValues($values);
+        }
+    }
+
+    public function getTaggedIteratorArgument(): ?TaggedIteratorArgument
+    {
+        return $this->taggedIteratorArgument;
+    }
 }

src/Symfony/Component/DependencyInjection/Argument/TaggedIteratorArgument.php

@@ -21,24 +21,22 @@ class TaggedIteratorArgument extends IteratorArgument
     private $tag;
     private $indexAttribute;
     private $defaultIndexMethod;
+    private $useFqcnAsFallback = false;
 
     /**
-     * TaggedIteratorArgument constructor.
-     *
      * @param string      $tag                The name of the tag identifying the target services
      * @param string|null $indexAttribute     The name of the attribute that defines the key referencing each service in the tagged collection
      * @param string|null $defaultIndexMethod The static method that should be called to get each service's key when their tag doesn't define the previous attribute
+     * @param bool        $useFqcnAsFallback  Whether the FQCN of the service should be used as index when neither the attribute nor the method are defined
      */
-    public function __construct(string $tag, string $indexAttribute = null, string $defaultIndexMethod = null)
+    public function __construct(string $tag, string $indexAttribute = null, string $defaultIndexMethod = null, bool $useFqcnAsFallback = false)
     {
         parent::__construct([]);
 
         $this->tag = $tag;
-
-        if ($indexAttribute) {
-            $this->indexAttribute = $indexAttribute;
-            $this->defaultIndexMethod = $defaultIndexMethod ?: ('getDefault'.str_replace(' ', '', ucwords(preg_replace('/[^a-zA-Z0-9\x7f-\xff]++/', ' ', $indexAttribute))).'Name');
-        }
+        $this->indexAttribute = $indexAttribute;
+        $this->defaultIndexMethod = $defaultIndexMethod ?: ('getDefault'.str_replace(' ', '', ucwords(preg_replace('/[^a-zA-Z0-9\x7f-\xff]++/', ' ', $indexAttribute ?? ''))).'Name');
+        $this->useFqcnAsFallback = $useFqcnAsFallback;
     }
 
     public function getTag()
@@ -55,4 +53,9 @@ public function getDefaultIndexMethod(): ?string
     {
         return $this->defaultIndexMethod;
     }
+
+    public function useFqcnAsFallback(): bool
+    {
+        return $this->useFqcnAsFallback;
+    }
 }

src/Symfony/Component/DependencyInjection/CHANGELOG.md

@@ -10,6 +10,7 @@ CHANGELOG
  * made `ContainerParametersResource` final and not implement `Serializable` anymore
  * added `ReverseContainer`: a container that turns services back to their ids
  * added ability to define an index for a tagged collection
+ * added ability to define an index for services in an injected service locator argument
 
 4.2.0
 -----

src/Symfony/Component/DependencyInjection/Compiler/PriorityTaggedServiceTrait.php

@@ -15,6 +15,7 @@
 use Symfony\Component\DependencyInjection\ContainerBuilder;
 use Symfony\Component\DependencyInjection\Exception\InvalidArgumentException;
 use Symfony\Component\DependencyInjection\Reference;
+use Symfony\Component\DependencyInjection\TypedReference;
 
 /**
  * Trait that allows a generic method to find and sort service by priority option in the tag.
@@ -40,34 +41,48 @@ trait PriorityTaggedServiceTrait
      */
     private function findAndSortTaggedServices($tagName, ContainerBuilder $container)
     {
-        $indexAttribute = $defaultIndexMethod = null;
+        $indexAttribute = $defaultIndexMethod = $useFqcnAsFallback = null;
+
         if ($tagName instanceof TaggedIteratorArgument) {
             $indexAttribute = $tagName->getIndexAttribute();
             $defaultIndexMethod = $tagName->getDefaultIndexMethod();
+            $useFqcnAsFallback = $tagName->useFqcnAsFallback();
             $tagName = $tagName->getTag();
         }
+
         $services = [];
 
         foreach ($container->findTaggedServiceIds($tagName, true) as $serviceId => $attributes) {
             $priority = isset($attributes[0]['priority']) ? $attributes[0]['priority'] : 0;
 
-            if (null === $indexAttribute) {
+            if (null === $indexAttribute && !$useFqcnAsFallback) {
                 $services[$priority][] = new Reference($serviceId);
 
                 continue;
             }
 
-            if (isset($attributes[0][$indexAttribute])) {
-                $services[$priority][$attributes[0][$indexAttribute]] = new Reference($serviceId);
+            $class = $container->getDefinition($serviceId)->getClass();
+            $class = $container->getParameterBag()->resolveValue($class) ?: null;
+
+            if (null !== $indexAttribute && isset($attributes[0][$indexAttribute])) {
+                $services[$priority][$attributes[0][$indexAttribute]] = new TypedReference($serviceId, $class, ContainerBuilder::EXCEPTION_ON_INVALID_REFERENCE, $attributes[0][$indexAttribute]);
 
                 continue;
             }
 
-            if (!$r = $container->getReflectionClass($class = $container->getDefinition($serviceId)->getClass())) {
+            if (!$r = $container->getReflectionClass($class)) {
                 throw new InvalidArgumentException(sprintf('Class "%s" used for service "%s" cannot be found.', $class, $serviceId));
             }
 
+            $class = $r->name;
+
             if (!$r->hasMethod($defaultIndexMethod)) {
+                if ($useFqcnAsFallback) {
+                    $services[$priority][$class] = new TypedReference($serviceId, $class);
+
+                    continue;
+                }
+
                 throw new InvalidArgumentException(sprintf('Method "%s::%s()" not found: tag "%s" on service "%s" is missing "%s" attribute.', $class, $defaultIndexMethod, $tagName, $serviceId, $indexAttribute));
             }
 
@@ -85,7 +100,7 @@ private function findAndSortTaggedServices($tagName, ContainerBuilder $container
                 throw new InvalidArgumentException(sprintf('Method "%s::%s()" should return a string, got %s: tag "%s" on service "%s" is missing "%s" attribute.', $class, $defaultIndexMethod, \gettype($key), $tagName, $serviceId, $indexAttribute));
             }
 
-            $services[$priority][$key] = new Reference($serviceId);
+            $services[$priority][$key] = new TypedReference($serviceId, $class, ContainerBuilder::EXCEPTION_ON_INVALID_REFERENCE, $key);
         }
 
         if ($services) {

src/Symfony/Component/DependencyInjection/Compiler/ServiceLocatorTagPass.php

@@ -27,11 +27,18 @@
  */
 final class ServiceLocatorTagPass extends AbstractRecursivePass
 {
+    use PriorityTaggedServiceTrait;
+
     protected function processValue($value, $isRoot = false)
     {
         if ($value instanceof ServiceLocatorArgument) {
+            if ($value->getTaggedIteratorArgument()) {
+                $value->setValues($this->findAndSortTaggedServices($value->getTaggedIteratorArgument(), $this->container));
+            }
+
             return self::register($this->container, $value->getValues());
         }
+
         if (!$value instanceof Definition || !$value->hasTag('container.service_locator')) {
             return parent::processValue($value, $isRoot);
         }

src/Symfony/Component/DependencyInjection/Dumper/XmlDumper.php

@@ -280,19 +280,19 @@ private function convertParameters(array $parameters, $type, \DOMElement $parent
             if ($value instanceof ServiceClosureArgument) {
                 $value = $value->getValues()[0];
             }
-            if (\is_array($value)) {
+            if (\is_array($tag = $value)) {
                 $element->setAttribute('type', 'collection');
                 $this->convertParameters($value, $type, $element, 'key');
-            } elseif ($value instanceof TaggedIteratorArgument) {
-                $element->setAttribute('type', 'tagged');
-                $element->setAttribute('tag', $value->getTag());
+            } elseif ($value instanceof TaggedIteratorArgument || ($value instanceof ServiceLocatorArgument && $tag = $value->getTaggedIteratorArgument())) {
+                $element->setAttribute('type', $value instanceof TaggedIteratorArgument ? 'tagged' : 'tagged_locator');
+                $element->setAttribute('tag', $tag->getTag());
 
-                if (null !== $value->getIndexAttribute()) {
-                    $element->setAttribute('index-by', $value->getIndexAttribute());
-                }
+                if (null !== $tag->getIndexAttribute()) {
+                    $element->setAttribute('index-by', $tag->getIndexAttribute());
 
-                if (null !== $value->getDefaultIndexMethod()) {
-                    $element->setAttribute('default-index-method', $value->getDefaultIndexMethod());
+                    if (null !== $tag->getDefaultIndexMethod()) {
+                        $element->setAttribute('default-index-method', $tag->getDefaultIndexMethod());
+                    }
                 }
             } elseif ($value instanceof IteratorArgument) {
                 $element->setAttribute('type', 'iterator');

src/Symfony/Component/DependencyInjection/Dumper/YamlDumper.php

@@ -232,22 +232,25 @@ private function dumpValue($value)
             $value = $value->getValues()[0];
         }
         if ($value instanceof ArgumentInterface) {
-            if ($value instanceof TaggedIteratorArgument) {
-                if (null !== $value->getIndexAttribute()) {
-                    $taggedValueContent = [
-                        'tag' => $value->getTag(),
-                        'index_by' => $value->getIndexAttribute(),
+            $tag = $value;
+
+            if ($value instanceof TaggedIteratorArgument || ($value instanceof ServiceLocatorArgument && $tag = $value->getTaggedIteratorArgument())) {
+                if (null === $tag->getIndexAttribute()) {
+                    $content = $tag->getTag();
+                } else {
+                    $content = [
+                        'tag' => $tag->getTag(),
+                        'index_by' => $tag->getIndexAttribute(),
                     ];
 
-                    if (null !== $value->getDefaultIndexMethod()) {
-                        $taggedValueContent['default_index_method'] = $value->getDefaultIndexMethod();
+                    if (null !== $tag->getDefaultIndexMethod()) {
+                        $content['default_index_method'] = $tag->getDefaultIndexMethod();
                     }
-
-                    return new TaggedValue('tagged', $taggedValueContent);
                 }
 
-                return new TaggedValue('tagged', $value->getTag());
+                return new TaggedValue($value instanceof TaggedIteratorArgument ? 'tagged' : 'tagged_locator', $content);
             }
+
             if ($value instanceof IteratorArgument) {
                 $tag = 'iterator';
             } elseif ($value instanceof ServiceLocatorArgument) {

src/Symfony/Component/DependencyInjection/Loader/Configurator/ContainerConfigurator.php

@@ -121,6 +121,14 @@ function tagged(string $tag, string $indexAttribute = null, string $defaultIndex
     return new TaggedIteratorArgument($tag, $indexAttribute, $defaultIndexMethod);
 }
 
+/**
+ * Creates a service locator by tag name.
+ */
+function tagged_locator(string $tag, string $indexAttribute, string $defaultIndexMethod = null): ServiceLocatorArgument
+{
+    return new ServiceLocatorArgument(new TaggedIteratorArgument($tag, $indexAttribute, $defaultIndexMethod, true));
+}
+
 /**
  * Creates an expression.
  */

src/Symfony/Component/DependencyInjection/Loader/XmlFileLoader.php

@@ -534,11 +534,19 @@ private function getArgumentsAsPhp(\DOMElement $node, $name, $file, $lowercase =
                     }
                     break;
                 case 'tagged':
+                case 'tagged_locator':
+                    $type = $arg->getAttribute('type');
+                    $forLocator = 'tagged_locator' === $type;
+
                     if (!$arg->getAttribute('tag')) {
-                        throw new InvalidArgumentException(sprintf('Tag "<%s>" with type="tagged" has no or empty "tag" attribute in "%s".', $name, $file));
+                        throw new InvalidArgumentException(sprintf('Tag "<%s>" with type="%s" has no or empty "tag" attribute in "%s".', $name, $type, $file));
                     }
 
-                    $arguments[$key] = new TaggedIteratorArgument($arg->getAttribute('tag'), $arg->getAttribute('index-by') ?: null, $arg->getAttribute('default-index-method') ?: null);
+                    $arguments[$key] = new TaggedIteratorArgument($arg->getAttribute('tag'), $arg->getAttribute('index-by') ?: null, $arg->getAttribute('default-index-method') ?: null, $forLocator);
+
+                    if ($forLocator) {
+                        $arguments[$key] = new ServiceLocatorArgument($arguments[$key]);
+                    }
                     break;
                 case 'binary':
                     if (false === $value = base64_decode($arg->nodeValue)) {

src/Symfony/Component/DependencyInjection/Loader/YamlFileLoader.php

@@ -702,27 +702,37 @@ private function resolveServices($value, $file, $isParameter = false)
                 if (!\is_array($argument)) {
                     throw new InvalidArgumentException(sprintf('"!service_locator" tag only accepts maps in "%s".', $file));
                 }
+
                 $argument = $this->resolveServices($argument, $file, $isParameter);
+
                 try {
                     return new ServiceLocatorArgument($argument);
                 } catch (InvalidArgumentException $e) {
                     throw new InvalidArgumentException(sprintf('"!service_locator" tag only accepts maps of "@service" references in "%s".', $file));
                 }
             }
-            if ('tagged' === $value->getTag()) {
+            if (\in_array($value->getTag(), ['tagged', 'tagged_locator'], true)) {
+                $forLocator = 'tagged_locator' === $value->getTag();
+
                 if (\is_string($argument) && $argument) {
-                    return new TaggedIteratorArgument($argument);
+                    return new TaggedIteratorArgument($argument, null, null, $forLocator);
                 }
 
                 if (\is_array($argument) && isset($argument['tag']) && $argument['tag']) {
                     if ($diff = array_diff(array_keys($argument), ['tag', 'index_by', 'default_index_method'])) {
-                        throw new InvalidArgumentException(sprintf('"!tagged" tag contains unsupported key "%s"; supported ones are "tag", "index_by" and "default_index_method".', implode('"", "', $diff)));
+                        throw new InvalidArgumentException(sprintf('"!%s" tag contains unsupported key "%s"; supported ones are "tag", "index_by" and "default_index_method".', $value->getTag(), implode('"", "', $diff)));
+                    }
+
+                    $argument = new TaggedIteratorArgument($argument['tag'], $argument['index_by'], $argument['default_index_method'] ?? null, $forLocator);
+
+                    if ($forLocator) {
+                        $argument = new ServiceLocatorArgument($argument);
                     }
 
-                    return new TaggedIteratorArgument($argument['tag'], $argument['index_by'] ?? null, $argument['default_index_method'] ?? null);
+                    return $argument;
                 }
 
-                throw new InvalidArgumentException(sprintf('"!tagged" tags only accept a non empty string or an array with a key "tag" in "%s".', $file));
+                throw new InvalidArgumentException(sprintf('"!%s" tags only accept a non empty string or an array with a key "tag" in "%s".', $value->getTag(), $file));
             }
             if ('service' === $value->getTag()) {
                 if ($isParameter) {

src/Symfony/Component/DependencyInjection/Loader/schema/dic/services/services-1.0.xsd

@@ -264,6 +264,7 @@
       <xsd:enumeration value="iterator" />
       <xsd:enumeration value="service_locator" />
       <xsd:enumeration value="tagged" />
+      <xsd:enumeration value="tagged_locator" />
     </xsd:restriction>
   </xsd:simpleType>