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

nicolas-grekas · nicolas-grekas · commit 09ba2740bf82 · 2025-02-11T14:18:45.000+01:00
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 #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](#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
diff --git a/src/Symfony/Component/DependencyInjection/CHANGELOG.md b/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
 ---
diff --git a/src/Symfony/Component/DependencyInjection/ContainerBuilder.php b/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.
      *
diff --git a/src/Symfony/Component/DependencyInjection/Definition.php b/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.
      */
diff --git a/src/Symfony/Component/DependencyInjection/Tests/ContainerBuilderTest.php b/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();
diff --git a/src/Symfony/Component/DependencyInjection/Tests/DefinitionTest.php b/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');
