feature symfony#59704 [DependencyInjection] Add Definition::addExcludedTag() and ContainerBuilder::findExcludedServiceIds() for auto-discovering value-objects (GromNaN)

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

Discussion
----------

[DependencyInjection] Add `Definition::addExcludedTag()` and `ContainerBuilder::findExcludedServiceIds()` for auto-discovering value-objects

| Q             | A
| ------------- | ---
| Branch?       | 7.3
| Bug fix?      | no
| New feature?  | yes
| Deprecations? | no
| Issues        | -
| License       | MIT

We could **not** use the method `findTaggedServiceIds` in symfony#59401 (comment), same for api-platform/core#6943.

As "using the container loading tools to do resource discovery quite seamlessly" [seems to be a good idea](symfony#59401 (review)), this changes make it easier.

I'm not closed to alternative ideas if we want to go further with this use-case.

### Usage

Let's create a `AppModel` attribute class and use it on any class of the project.

In the extension class:
```php
$this->registerAttributeForAutoconfiguration(AppModel::class, static function (ChildDefinition $definition) {
    $definition->addExcludedTag('app.model');
});
```

In a compiler pass:
```php
$classes = [];
foreach($containerBuilder->findExcludedServiceIds('app.model') as $id => $tags) {
    $classes[] = $containerBuilder->getDefinition($id)->getClass();
}

$containerBuilder->setParameter('.app.model_classes', $classes);
```

And this parameter can be injected into a service, or directly update a service definition to inject this list of classes. The attribute parameters can be injected into the tag, and retrieved in the compiler pass, for more advanced configuration.

Commits
-------

7a0443b [DependencyInjection] Add `Definition::addExcludedTag()` and `ContainerBuilder::findExcludedServiceIds()` for auto-discovering value-objects

Author: nicolas-grekas

src/Symfony/Component/DependencyInjection/CHANGELOG.md

@@ -7,6 +7,8 @@ CHANGELOG
  * Make `#[AsTaggedItem]` repeatable
  * Support `@>` as a shorthand for `!service_closure` in yaml files
  * Don't skip classes with private constructor when autodiscovering
+ * Add `Definition::addExcludeTag()` and `ContainerBuilder::findExcludedServiceIds()`
+   for auto-configuration of classes excluded from the service container
 
 7.2
 ---

src/Symfony/Component/DependencyInjection/ContainerBuilder.php

@@ -1351,6 +1351,38 @@ public function findTaggedServiceIds(string $name, bool $throwOnAbstract = false
         return $tags;
     }
 
+    /**
+     * Returns service ids for a given tag, asserting they have the "container.excluded" tag.
+     *
+     *  Example:
+     *
+     *      $container->register('foo')->addExcludeTag('my.tag', ['hello' => 'world'])
+     *
+     *      $serviceIds = $container->findExcludedServiceIds('my.tag');
+     *      foreach ($serviceIds as $serviceId => $tags) {
+     *          foreach ($tags as $tag) {
+     *              echo $tag['hello'];
+     *          }
+     *      }
+     *
+     * @return array<string, array> An array of tags with the tagged service as key, holding a list of attribute arrays
+     */
+    public function findExcludedServiceIds(string $tagName): array
+    {
+        $this->usedTags[] = $tagName;
+        $tags = [];
+        foreach ($this->getDefinitions() as $id => $definition) {
+            if ($definition->hasTag($tagName)) {
+                if (!$definition->hasTag('container.excluded')) {
+                    throw new InvalidArgumentException(\sprintf('The service "%s" tagged "%s" is missing the "container.excluded" tag.', $id, $tagName));
+                }
+                $tags[$id] = $definition->getTag($tagName);
+            }
+        }
+
+        return $tags;
+    }
+
     /**
      * Returns all tags the defined services use.
      *

src/Symfony/Component/DependencyInjection/Definition.php

@@ -455,6 +455,20 @@ public function addTag(string $name, array $attributes = []): static
         return $this;
     }
 
+    /**
+     * Adds a tag to the definition and marks it as excluded.
+     *
+     * These definitions should be processed using {@see ContainerBuilder::findExcludedServiceIds()}
+     *
+     * @return $this
+     */
+    public function addExcludeTag(string $name, array $attributes = []): static
+    {
+        return $this->addTag($name, $attributes)
+            ->addTag('container.excluded', ['source' => \sprintf('by tag "%s"', $name)])
+            ->setAbstract(true);
+    }
+
     /**
      * Whether this definition has a tag with the given name.
      */

src/Symfony/Component/DependencyInjection/Tests/ContainerBuilderTest.php

@@ -1062,20 +1062,18 @@ public function testMergeLogicException()
         $container->merge(new ContainerBuilder());
     }
 
-    public function testfindTaggedServiceIds()
+    public function testFindTaggedServiceIds()
     {
         $builder = new ContainerBuilder();
-        $builder
-            ->register('foo', 'Bar\FooClass')
+        $builder->register('foo', 'Bar\FooClass')
+            ->setAbstract(true)
             ->addTag('foo', ['foo' => 'foo'])
             ->addTag('bar', ['bar' => 'bar'])
-            ->addTag('foo', ['foofoo' => 'foofoo'])
-        ;
-        $builder
-            ->register('bar', 'Bar\FooClass')
+            ->addTag('foo', ['foofoo' => 'foofoo']);
+        $builder->register('bar', 'Bar\FooClass')
             ->addTag('foo')
-            ->addTag('container.excluded')
-        ;
+            ->addTag('container.excluded');
+
         $this->assertEquals([
             'foo' => [
                 ['foo' => 'foo'],
@@ -1085,6 +1083,45 @@ public function testfindTaggedServiceIds()
         $this->assertEquals([], $builder->findTaggedServiceIds('foobar'), '->findTaggedServiceIds() returns an empty array if there is annotated services');
     }
 
+    public function testFindTaggedServiceIdsThrowsWhenAbstract()
+    {
+        $builder = new ContainerBuilder();
+        $builder->register('foo', 'Bar\FooClass')
+            ->setAbstract(true)
+            ->addTag('foo', ['foo' => 'foo']);
+
+        $this->expectException(InvalidArgumentException::class);
+        $this->expectExceptionMessage('The service "foo" tagged "foo" must not be abstract.');
+        $builder->findTaggedServiceIds('foo', true);
+    }
+
+    public function testFindExcludedServiceIds()
+    {
+        $builder = new ContainerBuilder();
+        $builder->register('myservice', 'Bar\FooClass')
+            ->addTag('foo', ['foo' => 'foo'])
+            ->addTag('bar', ['bar' => 'bar'])
+            ->addTag('foo', ['foofoo' => 'foofoo'])
+            ->addExcludeTag('container.excluded');
+
+        $expected = ['myservice' => [['foo' => 'foo'], ['foofoo' => 'foofoo']]];
+        $this->assertSame($expected, $builder->findExcludedServiceIds('foo'));
+        $this->assertSame([], $builder->findExcludedServiceIds('foofoo'));
+    }
+
+    public function testFindExcludedServiceIdsThrowsWhenNotExcluded()
+    {
+        $builder = new ContainerBuilder();
+        $builder->register('myservice', 'Bar\FooClass')
+            ->addTag('foo', ['foo' => 'foo'])
+            ->addTag('bar', ['bar' => 'bar'])
+            ->addTag('foo', ['foofoo' => 'foofoo']);
+
+        $this->expectException(InvalidArgumentException::class);
+        $this->expectExceptionMessage('The service "myservice" tagged "foo" is missing the "container.excluded" tag.');
+        $builder->findExcludedServiceIds('foo', true);
+    }
+
     public function testFindUnusedTags()
     {
         $builder = new ContainerBuilder();

src/Symfony/Component/DependencyInjection/Tests/DefinitionTest.php

@@ -258,6 +258,16 @@ public function testTags()
         ], $def->getTags(), '->getTags() returns all tags');
     }
 
+    public function testAddExcludeTag()
+    {
+        $def = new Definition('stdClass');
+        $def->addExcludeTag('foo', ['bar' => true]);
+
+        $this->assertSame([['bar' => true]], $def->getTag('foo'));
+        $this->assertTrue($def->isAbstract());
+        $this->assertSame([['source' => 'by tag "foo"']], $def->getTag('container.excluded'));
+    }
+
     public function testSetArgument()
     {
         $def = new Definition('stdClass');