feature #57379 [DependencyInjection] Add #[WhenNot] attribute (alexandre-daubois)

fabpot · fabpot · commit 0455a849d02b · 2024-06-25T21:44:12.000+02:00
This PR was merged into the 7.2 branch. Discussion ---------- [DependencyInjection] Add `#[WhenNot]` attribute | Q | A | ------------- | --- | Branch? | 7.2 | Bug fix? | no | New feature? | yes | Deprecations? | no | Issues | - | License | MIT When dealing with many environment and concrete+test implementations of many services, it can be tricky/verbose to repeat `#[When]` for each and every existing env. By using `#[NotWhen]`, it becomes handy to deal with different implementations of a service across different env: ```php // ConcreteService.php #[WhenNot(env: 'test')] class ConcreteService implements MyServiceInterface { public function call() { dump("I'm a concrete service!"); } } // TestService.php #[When(env: 'test')] class TestService implements MyServiceInterface { public function call() { dump("I'm a test service!"); } } // MyCommand.php class MyCommand extends Command { public function __construct(private MyServiceInterface $service) { parent::__construct(); } // ... } ``` It also eases the creation of a new env: no more need to go across all `#[When]` occurrences to update service definitions. You cannot use When and NotWhen at the same time: ```php #[WhenNot(env: 'dev')] #[When(env: 'test')] class TestService implements MyServiceInterface { public function call() { dump("I'm a test service!"); } } // Throws a LogicException: The "App\Service\TestService" class cannot have both #[When] and #[NotWhen] attributes. ``` Commits ------- 7349e3f [DependencyInjection] Add `#[WhenNot]` attribute
diff --git a/src/Symfony/Component/Config/CHANGELOG.md b/src/Symfony/Component/Config/CHANGELOG.md
@@ -1,6 +1,11 @@
 CHANGELOG
 =========
 
+7.2
+---
+
+ * Add `#[WhenNot]` attribute to prevent service from being registered in a specific environment
+
 7.1
 ---
 
diff --git a/src/Symfony/Component/DependencyInjection/Attribute/WhenNot.php b/src/Symfony/Component/DependencyInjection/Attribute/WhenNot.php
@@ -0,0 +1,26 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <fabien@symfony.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Component\DependencyInjection\Attribute;
+
+/**
+ * An attribute to tell under which environment this class should NOT be registered as a service.
+ *
+ * @author Alexandre Daubois <alex.daubois@gmail.com>
+ */
+#[\Attribute(\Attribute::TARGET_CLASS | \Attribute::TARGET_METHOD | \Attribute::TARGET_FUNCTION | \Attribute::IS_REPEATABLE)]
+class WhenNot
+{
+    public function __construct(
+        public string $env,
+    ) {
+    }
+}
diff --git a/src/Symfony/Component/DependencyInjection/Loader/FileLoader.php b/src/Symfony/Component/DependencyInjection/Loader/FileLoader.php
@@ -21,6 +21,7 @@
 use Symfony\Component\DependencyInjection\Attribute\AsAlias;
 use Symfony\Component\DependencyInjection\Attribute\Exclude;
 use Symfony\Component\DependencyInjection\Attribute\When;
+use Symfony\Component\DependencyInjection\Attribute\WhenNot;
 use Symfony\Component\DependencyInjection\ChildDefinition;
 use Symfony\Component\DependencyInjection\Compiler\RegisterAutoconfigureAttributesPass;
 use Symfony\Component\DependencyInjection\ContainerBuilder;
@@ -154,14 +155,32 @@ public function registerClasses(Definition $prototype, string $namespace, string
                     continue;
                 }
                 if ($this->env) {
-                    $attribute = null;
-                    foreach ($r->getAttributes(When::class, \ReflectionAttribute::IS_INSTANCEOF) as $attribute) {
+                    $excluded = true;
+                    $whenAttributes = $r->getAttributes(When::class, \ReflectionAttribute::IS_INSTANCEOF);
+                    $notWhenAttributes = $r->getAttributes(WhenNot::class, \ReflectionAttribute::IS_INSTANCEOF);
+
+                    if ($whenAttributes && $notWhenAttributes) {
+                        throw new LogicException(sprintf('The "%s" class cannot have both #[When] and #[WhenNot] attributes.', $class));
+                    }
+
+                    if (!$whenAttributes && !$notWhenAttributes) {
+                        $excluded = false;
+                    }
+
+                    foreach ($whenAttributes as $attribute) {
                         if ($this->env === $attribute->newInstance()->env) {
-                            $attribute = null;
+                            $excluded = false;
                             break;
                         }
                     }
-                    if (null !== $attribute) {
+
+                    foreach ($notWhenAttributes as $attribute) {
+                        if ($excluded = $this->env === $attribute->newInstance()->env) {
+                            break;
+                        }
+                    }
+
+                    if ($excluded) {
                         $this->addContainerExcludedTag($class, $source);
                         continue;
                     }
diff --git a/src/Symfony/Component/DependencyInjection/Loader/PhpFileLoader.php b/src/Symfony/Component/DependencyInjection/Loader/PhpFileLoader.php
@@ -16,9 +16,11 @@
 use Symfony\Component\Config\Builder\ConfigBuilderInterface;
 use Symfony\Component\Config\FileLocatorInterface;
 use Symfony\Component\DependencyInjection\Attribute\When;
+use Symfony\Component\DependencyInjection\Attribute\WhenNot;
 use Symfony\Component\DependencyInjection\Container;
 use Symfony\Component\DependencyInjection\ContainerBuilder;
 use Symfony\Component\DependencyInjection\Exception\InvalidArgumentException;
+use Symfony\Component\DependencyInjection\Exception\LogicException;
 use Symfony\Component\DependencyInjection\Extension\ConfigurationExtensionInterface;
 use Symfony\Component\DependencyInjection\Extension\ExtensionInterface;
 use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;
@@ -97,14 +99,32 @@ private function executeCallback(callable $callback, ContainerConfigurator $cont
         $configBuilders = [];
         $r = new \ReflectionFunction($callback);
 
-        $attribute = null;
-        foreach ($r->getAttributes(When::class, \ReflectionAttribute::IS_INSTANCEOF) as $attribute) {
+        $excluded = true;
+        $whenAttributes = $r->getAttributes(When::class, \ReflectionAttribute::IS_INSTANCEOF);
+        $notWhenAttributes = $r->getAttributes(WhenNot::class, \ReflectionAttribute::IS_INSTANCEOF);
+
+        if ($whenAttributes && $notWhenAttributes) {
+            throw new LogicException('Using both #[When] and #[WhenNot] attributes on the same target is not allowed.');
+        }
+
+        if (!$whenAttributes && !$notWhenAttributes) {
+            $excluded = false;
+        }
+
+        foreach ($whenAttributes as $attribute) {
             if ($this->env === $attribute->newInstance()->env) {
-                $attribute = null;
+                $excluded = false;
                 break;
             }
         }
-        if (null !== $attribute) {
+
+        foreach ($notWhenAttributes as $attribute) {
+            if ($excluded = $this->env === $attribute->newInstance()->env) {
+                break;
+            }
+        }
+
+        if ($excluded) {
             return;
         }
 
diff --git a/src/Symfony/Component/DependencyInjection/Tests/Fixtures/Prototype/BadAttributes/WhenNotWhenFoo.php b/src/Symfony/Component/DependencyInjection/Tests/Fixtures/Prototype/BadAttributes/WhenNotWhenFoo.php
@@ -0,0 +1,12 @@
+<?php
+
+namespace Symfony\Component\DependencyInjection\Tests\Fixtures\Prototype\BadAttributes;
+
+use Symfony\Component\DependencyInjection\Attribute\WhenNot;
+use Symfony\Component\DependencyInjection\Attribute\When;
+
+#[When(env: 'dev')]
+#[WhenNot(env: 'test')]
+class WhenNotWhenFoo
+{
+}
diff --git a/src/Symfony/Component/DependencyInjection/Tests/Fixtures/Prototype/NotFoo.php b/src/Symfony/Component/DependencyInjection/Tests/Fixtures/Prototype/NotFoo.php
@@ -0,0 +1,27 @@
+<?php
+
+namespace Symfony\Component\DependencyInjection\Tests\Fixtures\Prototype;
+
+use Symfony\Component\DependencyInjection\Attribute\WhenNot;
+
+#[NeverInProduction]
+#[WhenNot(env: 'dev')]
+class NotFoo
+{
+    public function __construct($bar = null, ?iterable $foo = null, ?object $baz = null)
+    {
+    }
+
+    public function setFoo(self $foo)
+    {
+    }
+}
+
+#[\Attribute(\Attribute::TARGET_CLASS | \Attribute::TARGET_METHOD | \Attribute::TARGET_FUNCTION | \Attribute::IS_REPEATABLE)]
+class NeverInProduction extends WhenNot
+{
+    public function __construct()
+    {
+        parent::__construct('prod');
+    }
+}
diff --git a/src/Symfony/Component/DependencyInjection/Tests/Fixtures/config/instanceof.expected.yml b/src/Symfony/Component/DependencyInjection/Tests/Fixtures/config/instanceof.expected.yml
@@ -16,6 +16,9 @@ services:
 
         shared: false
         configurator: c
+    Symfony\Component\DependencyInjection\Tests\Fixtures\Prototype\NotFoo:
+        class: Symfony\Component\DependencyInjection\Tests\Fixtures\Prototype\NotFoo
+        public: true
     foo:
         class: App\FooService
         public: true
diff --git a/src/Symfony/Component/DependencyInjection/Tests/Fixtures/config/not_when_env.php b/src/Symfony/Component/DependencyInjection/Tests/Fixtures/config/not_when_env.php
@@ -0,0 +1,7 @@
+<?php
+
+use Symfony\Component\DependencyInjection\Attribute\WhenNot;
+
+return #[WhenNot(env: 'prod')] function () {
+    throw new RuntimeException('This code should not be run.');
+};
diff --git a/src/Symfony/Component/DependencyInjection/Tests/Fixtures/config/prototype.expected.yml b/src/Symfony/Component/DependencyInjection/Tests/Fixtures/config/prototype.expected.yml
@@ -16,6 +16,19 @@ services:
             message: '%service_id%'
         arguments: [1]
         factory: f
+    Symfony\Component\DependencyInjection\Tests\Fixtures\Prototype\NotFoo:
+        class: Symfony\Component\DependencyInjection\Tests\Fixtures\Prototype\NotFoo
+        public: true
+        tags:
+            - foo
+            - baz
+        deprecated:
+            package: vendor/package
+            version: '1.1'
+            message: '%service_id%'
+        lazy: true
+        arguments: [1]
+        factory: f
     Symfony\Component\DependencyInjection\Tests\Fixtures\Prototype\Sub\Bar:
         class: Symfony\Component\DependencyInjection\Tests\Fixtures\Prototype\Sub\Bar
         public: true
diff --git a/src/Symfony/Component/DependencyInjection/Tests/Fixtures/config/prototype.php b/src/Symfony/Component/DependencyInjection/Tests/Fixtures/config/prototype.php
@@ -10,7 +10,7 @@
     $di->load(Prototype::class.'\\', '../Prototype')
         ->public()
         ->autoconfigure()
-        ->exclude('../Prototype/{OtherDir,BadClasses,SinglyImplementedInterface,StaticConstructor}')
+        ->exclude('../Prototype/{OtherDir,BadClasses,BadAttributes,SinglyImplementedInterface,StaticConstructor}')
         ->factory('f')
         ->deprecate('vendor/package', '1.1', '%service_id%')
         ->args([0])
diff --git a/src/Symfony/Component/DependencyInjection/Tests/Fixtures/config/prototype_array.expected.yml b/src/Symfony/Component/DependencyInjection/Tests/Fixtures/config/prototype_array.expected.yml
@@ -16,6 +16,19 @@ services:
             message: '%service_id%'
         arguments: [1]
         factory: f
+    Symfony\Component\DependencyInjection\Tests\Fixtures\Prototype\NotFoo:
+        class: Symfony\Component\DependencyInjection\Tests\Fixtures\Prototype\NotFoo
+        public: true
+        tags:
+            - foo
+            - baz
+        deprecated:
+            package: vendor/package
+            version: '1.1'
+            message: '%service_id%'
+        lazy: true
+        arguments: [1]
+        factory: f
     Symfony\Component\DependencyInjection\Tests\Fixtures\Prototype\Sub\Bar:
         class: Symfony\Component\DependencyInjection\Tests\Fixtures\Prototype\Sub\Bar
         public: true
diff --git a/src/Symfony/Component/DependencyInjection/Tests/Fixtures/config/prototype_array.php b/src/Symfony/Component/DependencyInjection/Tests/Fixtures/config/prototype_array.php
@@ -10,7 +10,7 @@
     $di->load(Prototype::class.'\\', '../Prototype')
         ->public()
         ->autoconfigure()
-        ->exclude(['../Prototype/OtherDir', '../Prototype/BadClasses', '../Prototype/SinglyImplementedInterface', '../Prototype/StaticConstructor'])
+        ->exclude(['../Prototype/OtherDir', '../Prototype/BadClasses', '../Prototype/BadAttributes', '../Prototype/SinglyImplementedInterface', '../Prototype/StaticConstructor'])
         ->factory('f')
         ->deprecate('vendor/package', '1.1', '%service_id%')
         ->args([0])
diff --git a/src/Symfony/Component/DependencyInjection/Tests/Fixtures/config/when_not_when_env.php b/src/Symfony/Component/DependencyInjection/Tests/Fixtures/config/when_not_when_env.php
@@ -0,0 +1,8 @@
+<?php
+
+use Symfony\Component\DependencyInjection\Attribute\WhenNot;
+use Symfony\Component\DependencyInjection\Attribute\When;
+
+return #[When(env: 'dev')] #[WhenNot(env: 'prod')] function () {
+    throw new RuntimeException('This code should not be run.');
+};
diff --git a/src/Symfony/Component/DependencyInjection/Tests/Fixtures/xml/services_prototype.xml b/src/Symfony/Component/DependencyInjection/Tests/Fixtures/xml/services_prototype.xml
@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="utf-8"?>
 <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 https://symfony.com/schema/dic/services/services-1.0.xsd">
   <services>
-      <prototype namespace="Symfony\Component\DependencyInjection\Tests\Fixtures\Prototype\" resource="../Prototype/*" exclude="../Prototype/{OtherDir,BadClasses,SinglyImplementedInterface,StaticConstructor}" />
+      <prototype namespace="Symfony\Component\DependencyInjection\Tests\Fixtures\Prototype\" resource="../Prototype/*" exclude="../Prototype/{OtherDir,BadClasses,BadAttributes,SinglyImplementedInterface,StaticConstructor}" />
   </services>
 </container>
diff --git a/src/Symfony/Component/DependencyInjection/Tests/Fixtures/xml/services_prototype_array.xml b/src/Symfony/Component/DependencyInjection/Tests/Fixtures/xml/services_prototype_array.xml
@@ -4,6 +4,7 @@
       <prototype namespace="Symfony\Component\DependencyInjection\Tests\Fixtures\Prototype\" resource="../Prototype/*">
           <exclude>../Prototype/OtherDir</exclude>
           <exclude>../Prototype/BadClasses</exclude>
+          <exclude>../Prototype/BadAttributes</exclude>
           <exclude>../Prototype/SinglyImplementedInterface</exclude>
           <exclude>../Prototype/StaticConstructor</exclude>
       </prototype>
diff --git a/src/Symfony/Component/DependencyInjection/Tests/Fixtures/xml/services_prototype_array_with_space_node.xml b/src/Symfony/Component/DependencyInjection/Tests/Fixtures/xml/services_prototype_array_with_space_node.xml
@@ -4,6 +4,7 @@
       <prototype namespace="Symfony\Component\DependencyInjection\Tests\Fixtures\Prototype\" resource="../Prototype/*">
           <exclude>../Prototype/OtherDir</exclude>
           <exclude>../Prototype/BadClasses</exclude>
+          <exclude>../Prototype/BadAttributes</exclude>
           <exclude>../Prototype/SinglyImplementedInterface</exclude>
           <exclude>../Prototype/StaticConstructor</exclude>
           <exclude> </exclude>
diff --git a/src/Symfony/Component/DependencyInjection/Tests/Fixtures/yaml/services_prototype.yml b/src/Symfony/Component/DependencyInjection/Tests/Fixtures/yaml/services_prototype.yml
@@ -1,4 +1,4 @@
 services:
     Symfony\Component\DependencyInjection\Tests\Fixtures\Prototype\:
         resource: ../Prototype
-        exclude: '../Prototype/{OtherDir,BadClasses,SinglyImplementedInterface,StaticConstructor}'
+        exclude: '../Prototype/{OtherDir,BadClasses,BadAttributes,SinglyImplementedInterface,StaticConstructor}'
diff --git a/src/Symfony/Component/DependencyInjection/Tests/Loader/FileLoaderTest.php b/src/Symfony/Component/DependencyInjection/Tests/Loader/FileLoaderTest.php
@@ -29,6 +29,7 @@
 use Symfony\Component\DependencyInjection\Tests\Fixtures\Prototype\BadClasses\MissingParent;
 use Symfony\Component\DependencyInjection\Tests\Fixtures\Prototype\Foo;
 use Symfony\Component\DependencyInjection\Tests\Fixtures\Prototype\FooInterface;
+use Symfony\Component\DependencyInjection\Tests\Fixtures\Prototype\NotFoo;
 use Symfony\Component\DependencyInjection\Tests\Fixtures\Prototype\OtherDir\AnotherSub;
 use Symfony\Component\DependencyInjection\Tests\Fixtures\Prototype\OtherDir\AnotherSub\DeeperBaz;
 use Symfony\Component\DependencyInjection\Tests\Fixtures\Prototype\OtherDir\Baz;
@@ -196,6 +197,7 @@ public function testNestedRegisterClasses()
         $this->assertTrue($container->has(Bar::class));
         $this->assertTrue($container->has(Baz::class));
         $this->assertTrue($container->has(Foo::class));
+        $this->assertTrue($container->has(NotFoo::class));
 
         $this->assertEquals([FooInterface::class], array_keys($container->getAliases()));
 
@@ -302,6 +304,47 @@ public function testRegisterClassesWithWhenEnv(?string $env, bool $expected)
         $this->assertSame($expected, $container->getDefinition(Foo::class)->hasTag('container.excluded'));
     }
 
+    /**
+     * @dataProvider provideEnvAndExpectedExclusions
+     */
+    public function testRegisterWithNotWhenAttributes(string $env, bool $expectedNotFooExclusion)
+    {
+        $container = new ContainerBuilder();
+        $loader = new TestFileLoader($container, new FileLocator(self::$fixturesPath.'/Fixtures'), $env);
+
+        $loader->registerClasses(
+            (new Definition())->setAutoconfigured(true),
+            'Symfony\Component\DependencyInjection\Tests\Fixtures\Prototype\\',
+            'Prototype/*',
+            'Prototype/BadAttributes/*'
+        );
+
+        $this->assertTrue($container->has(NotFoo::class));
+        $this->assertSame($expectedNotFooExclusion, $container->getDefinition(NotFoo::class)->hasTag('container.excluded'));
+    }
+
+    public static function provideEnvAndExpectedExclusions(): iterable
+    {
+        yield ['dev', true];
+        yield ['prod', true];
+        yield ['test', false];
+    }
+
+    public function testRegisterThrowsWithBothWhenAndNotWhenAttribute()
+    {
+        $container = new ContainerBuilder();
+        $loader = new TestFileLoader($container, new FileLocator(self::$fixturesPath.'/Fixtures'), 'dev');
+
+        $this->expectException(LogicException::class);
+        $this->expectExceptionMessage('The "Symfony\Component\DependencyInjection\Tests\Fixtures\Prototype\BadAttributes\WhenNotWhenFoo" class cannot have both #[When] and #[WhenNot] attributes.');
+
+        $loader->registerClasses(
+            (new Definition())->setAutoconfigured(true),
+            'Symfony\Component\DependencyInjection\Tests\Fixtures\Prototype\BadAttributes\\',
+            'Prototype/BadAttributes/*',
+        );
+    }
+
     /**
      * @dataProvider provideResourcesWithAsAliasAttributes
      */
diff --git a/src/Symfony/Component/DependencyInjection/Tests/Loader/PhpFileLoaderTest.php b/src/Symfony/Component/DependencyInjection/Tests/Loader/PhpFileLoaderTest.php
@@ -22,6 +22,7 @@
 use Symfony\Component\DependencyInjection\Dumper\PhpDumper;
 use Symfony\Component\DependencyInjection\Dumper\YamlDumper;
 use Symfony\Component\DependencyInjection\Exception\InvalidArgumentException;
+use Symfony\Component\DependencyInjection\Exception\LogicException;
 use Symfony\Component\DependencyInjection\Loader\PhpFileLoader;
 use Symfony\Component\DependencyInjection\Reference;
 use Symfony\Component\DependencyInjection\Tests\Fixtures\FooClassWithEnumAttribute;
@@ -226,6 +227,29 @@ public function testWhenEnv()
         $loader->load($fixtures.'/config/when_env.php');
     }
 
+    public function testNotWhenEnv()
+    {
+        $this->expectNotToPerformAssertions();
+
+        $fixtures = realpath(__DIR__.'/../Fixtures');
+        $container = new ContainerBuilder();
+        $loader = new PhpFileLoader($container, new FileLocator(), 'prod', new ConfigBuilderGenerator(sys_get_temp_dir()));
+
+        $loader->load($fixtures.'/config/not_when_env.php');
+    }
+
+    public function testUsingBothWhenAndNotWhenEnv()
+    {
+        $fixtures = realpath(__DIR__.'/../Fixtures');
+        $container = new ContainerBuilder();
+        $loader = new PhpFileLoader($container, new FileLocator(), 'prod', new ConfigBuilderGenerator(sys_get_temp_dir()));
+
+        $this->expectException(LogicException::class);
+        $this->expectExceptionMessage('Using both #[When] and #[WhenNot] attributes on the same target is not allowed.');
+
+        $loader->load($fixtures.'/config/when_not_when_env.php');
+    }
+
     public function testServiceWithServiceLocatorArgument()
     {
         $fixtures = realpath(__DIR__.'/../Fixtures');
diff --git a/src/Symfony/Component/DependencyInjection/Tests/Loader/XmlFileLoaderTest.php b/src/Symfony/Component/DependencyInjection/Tests/Loader/XmlFileLoaderTest.php
diff --git a/src/Symfony/Component/DependencyInjection/Tests/Loader/YamlFileLoaderTest.php b/src/Symfony/Component/DependencyInjection/Tests/Loader/YamlFileLoaderTest.php
