symfony · nicolas-grekas · Mar 10, 2023 · Jan 16, 2023
diff --git a/src/Symfony/Component/DependencyInjection/CHANGELOG.md b/src/Symfony/Component/DependencyInjection/CHANGELOG.md
@@ -17,6 +17,7 @@ CHANGELOG
 * Add `#[Exclude]` to skip autoregistering a class
 * Add support for autowiring services as closures using `#[AutowireCallable]` or `#[AutowireServiceClosure]`
 * Deprecate `#[MapDecorated]`, use `#[AutowireDecorated]` instead
+ * Deprecate the `@required` annotation, use the `Symfony\Contracts\Service\Attribute\Required` attribute instead

 6.2
 ---

diff --git a/src/Symfony/Component/DependencyInjection/Compiler/AutowireRequiredMethodsPass.php b/src/Symfony/Component/DependencyInjection/Compiler/AutowireRequiredMethodsPass.php
@@ -15,7 +15,7 @@
 use Symfony\Contracts\Service\Attribute\Required;

 /**
- * Looks for definitions with autowiring enabled and registers their corresponding "@required" methods as setters.
+ * Looks for definitions with autowiring enabled and registers their corresponding "#[Required]" methods as setters.
 *
 * @author Nicolas Grekas <p@tchwork.com>
 */
@@ -57,6 +57,8 @@ protected function processValue(mixed $value, bool $isRoot = false): mixed
                }
                if (false !== $doc = $r->getDocComment()) {
                    if (false !== stripos($doc, '@required') && preg_match('#(?:^/\*\*|\n\s*+\*)\s*+@required(?:\s|\*/$)#i', $doc)) {
+                        trigger_deprecation('symfony/dependency-injection', '6.3', 'Relying on the "@required" annotation on method "%s::%s()" is deprecated, use the "Symfony\Contracts\Service\Attribute\Required" attribute instead.', $reflectionMethod->class, $reflectionMethod->name);
+
                        if ($this->isWither($reflectionMethod, $doc)) {
                            $withers[] = [$reflectionMethod->name, [], true];
                        } else {

diff --git a/src/Symfony/Component/DependencyInjection/Compiler/AutowireRequiredPropertiesPass.php b/src/Symfony/Component/DependencyInjection/Compiler/AutowireRequiredPropertiesPass.php
@@ -17,7 +17,7 @@
 use Symfony\Contracts\Service\Attribute\Required;

 /**
- * Looks for definitions with autowiring enabled and registers their corresponding "@required" properties.
+ * Looks for definitions with autowiring enabled and registers their corresponding "#[Required]" properties.
 *
 * @author Sebastien Morel (Plopix) <morel.seb@gmail.com>
 * @author Nicolas Grekas <p@tchwork.com>
@@ -40,11 +40,15 @@ protected function processValue(mixed $value, bool $isRoot = false): mixed
            if (!($type = $reflectionProperty->getType()) instanceof \ReflectionNamedType) {
                continue;
            }
+            $doc = false;
            if (!$reflectionProperty->getAttributes(Required::class)
                && ((false === $doc = $reflectionProperty->getDocComment()) || false === stripos($doc, '@required') || !preg_match('#(?:^/\*\*|\n\s*+\*)\s*+@required(?:\s|\*/$)#i', $doc))
            ) {
                continue;
            }
+            if ($doc) {
+                trigger_deprecation('symfony/dependency-injection', '6.3', 'Using the "@required" annotation on property "%s::$%s" is deprecated, use the "Symfony\Contracts\Service\Attribute\Required" attribute instead.', $reflectionProperty->class, $reflectionProperty->name);
+            }
            if (\array_key_exists($name = $reflectionProperty->getName(), $properties)) {
                continue;
            }

diff --git a/src/Symfony/Component/DependencyInjection/Tests/Compiler/AutowirePassTest.php b/src/Symfony/Component/DependencyInjection/Tests/Compiler/AutowirePassTest.php
@@ -15,6 +15,7 @@
 use Psr\Log\LoggerInterface;
 use Psr\Log\NullLogger;
 use Symfony\Bridge\PhpUnit\ClassExistsMock;
+use Symfony\Bridge\PhpUnit\ExpectDeprecationTrait;
 use Symfony\Component\Config\FileLocator;
 use Symfony\Component\Config\Resource\ClassExistenceResource;
 use Symfony\Component\DependencyInjection\Argument\ServiceLocatorArgument;
@@ -41,6 +42,8 @@

 class AutowirePassTest extends TestCase
 {
+    use ExpectDeprecationTrait;
+
    public static function setUpBeforeClass(): void
    {
        ClassExistsMock::register(AutowirePass::class);
@@ -695,8 +698,15 @@ public function testOptionalArgsNoRequiredForCoreClasses()
        );
    }

-    public function testSetterInjection()
+    /**
+     * @group legacy
+     */
+    public function testSetterInjectionAnnotation()
    {
+        $this->expectDeprecation('Since symfony/dependency-injection 6.3: Relying on the "@required" annotation on method "Symfony\Component\DependencyInjection\Tests\Compiler\SetterInjectionAnnotation::setFoo()" is deprecated, use the "Symfony\Contracts\Service\Attribute\Required" attribute instead.');
+        $this->expectDeprecation('Since symfony/dependency-injection 6.3: Relying on the "@required" annotation on method "Symfony\Component\DependencyInjection\Tests\Compiler\SetterInjectionAnnotation::setChildMethodWithoutDocBlock()" is deprecated, use the "Symfony\Contracts\Service\Attribute\Required" attribute instead.');
+        $this->expectDeprecation('Since symfony/dependency-injection 6.3: Relying on the "@required" annotation on method "Symfony\Component\DependencyInjection\Tests\Compiler\SetterInjectionParentAnnotation::setDependencies()" is deprecated, use the "Symfony\Contracts\Service\Attribute\Required" attribute instead.');
+
        $container = new ContainerBuilder();
        $container->register(Foo::class);
        $container->register(A::class);
@@ -705,7 +715,7 @@ public function testSetterInjection()

        // manually configure *one* call, to override autowiring
        $container
-            ->register('setter_injection', SetterInjection::class)
+            ->register('setter_injection', SetterInjectionAnnotation::class)
            ->setAutowired(true)
            ->addMethodCall('setWithCallsConfigured', ['manual_arg1', 'manual_arg2'])
        ;
@@ -717,7 +727,7 @@ public function testSetterInjection()
        $methodCalls = $container->getDefinition('setter_injection')->getMethodCalls();

        $this->assertEquals(
-            ['setWithCallsConfigured', 'setFoo', 'setDependencies', 'setChildMethodWithoutDocBlock'],
+            ['setWithCallsConfigured', 'setFoo', 'setChildMethodWithoutDocBlock', 'setDependencies'],
            array_column($methodCalls, 0)
        );

@@ -766,7 +776,7 @@ public function testWithNonExistingSetterAndAutowiring()
        (new AutowirePass())->process($container);
    }

-    public function testExplicitMethodInjection()
+    public function testExplicitMethodInjectionAttribute()
    {
        $container = new ContainerBuilder();
        $container->register(Foo::class);
@@ -821,7 +831,33 @@ public function testIgnoreServiceWithClassNotExisting()
        $this->assertTrue($container->hasDefinition('bar'));
    }

-    public function testSetterInjectionCollisionThrowsException()
+    /**
+     * @group legacy
+     */
+    public function testSetterInjectionFromAnnotationCollisionThrowsException()
+    {
+        $this->expectDeprecation('Since symfony/dependency-injection 6.3: Relying on the "@required" annotation on method "Symfony\Component\DependencyInjection\Tests\Compiler\SetterInjectionCollisionAnnotation::setMultipleInstancesForOneArg()" is deprecated, use the "Symfony\Contracts\Service\Attribute\Required" attribute instead.');
+
+        $container = new ContainerBuilder();
+
+        $container->register('c1', CollisionA::class);
+        $container->register('c2', CollisionB::class);
+        $aDefinition = $container->register('setter_injection_collision', SetterInjectionCollisionAnnotation::class);
+        $aDefinition->setAutowired(true);
+
+        (new AutowireRequiredMethodsPass())->process($container);
+
+        $pass = new AutowirePass();
+
+        try {
+            $pass->process($container);
+            $this->fail('AutowirePass should have thrown an exception');
+        } catch (AutowiringFailedException $e) {
+            $this->assertSame('Cannot autowire service "setter_injection_collision": argument "$collision" of method "Symfony\Component\DependencyInjection\Tests\Compiler\SetterInjectionCollisionAnnotation::setMultipleInstancesForOneArg()" references interface "Symfony\Component\DependencyInjection\Tests\Compiler\CollisionInterface" but no such service exists. You should maybe alias this interface to one of these existing services: "c1", "c2".', (string) $e->getMessage());
+        }
+    }
+
+    public function testSetterInjectionFromAttributeCollisionThrowsException()
    {
        $container = new ContainerBuilder();

@@ -1129,6 +1165,36 @@ public function testErroredServiceLocator()
        $this->assertSame(['Cannot autowire service "some_locator": it has type "Symfony\Component\DependencyInjection\Tests\Compiler\MissingClass" but this class was not found.'], $container->getDefinition('.errored.some_locator.'.MissingClass::class)->getErrors());
    }

+    /**
+     * @group legacy
+     */
+    public function testNamedArgumentAliasResolveCollisionsAnnotation()
+    {
+        $this->expectDeprecation('Since symfony/dependency-injection 6.3: Relying on the "@required" annotation on method "Symfony\Component\DependencyInjection\Tests\Compiler\SetterInjectionCollisionAnnotation::setMultipleInstancesForOneArg()" is deprecated, use the "Symfony\Contracts\Service\Attribute\Required" attribute instead.');
+
+        $container = new ContainerBuilder();
+
+        $container->register('c1', CollisionA::class);
+        $container->register('c2', CollisionB::class);
+        $container->setAlias(CollisionInterface::class.' $collision', 'c2');
+        $aDefinition = $container->register('setter_injection_collision', SetterInjectionCollisionAnnotation::class);
+        $aDefinition->setAutowired(true);
+
+        (new AutowireRequiredMethodsPass())->process($container);
+
+        $pass = new AutowirePass();
+
+        $pass->process($container);
+
+        $expected = [
+            [
+                'setMultipleInstancesForOneArg',
+                [new TypedReference(CollisionInterface::class.' $collision', CollisionInterface::class)],
+            ],
+        ];
+        $this->assertEquals($expected, $container->getDefinition('setter_injection_collision')->getMethodCalls());
+    }
+
    public function testNamedArgumentAliasResolveCollisions()
    {
        $container = new ContainerBuilder();

diff --git a/src/Symfony/Component/DependencyInjection/Tests/Compiler/AutowireRequiredMethodsPassTest.php b/src/Symfony/Component/DependencyInjection/Tests/Compiler/AutowireRequiredMethodsPassTest.php
@@ -12,26 +12,37 @@
 namespace Symfony\Component\DependencyInjection\Tests\Compiler;

 use PHPUnit\Framework\TestCase;
+use Symfony\Bridge\PhpUnit\ExpectDeprecationTrait;
 use Symfony\Component\DependencyInjection\Compiler\AutowireRequiredMethodsPass;
 use Symfony\Component\DependencyInjection\Compiler\ResolveClassPass;
 use Symfony\Component\DependencyInjection\ContainerBuilder;
+use Symfony\Component\DependencyInjection\Tests\Fixtures\WitherAnnotationStaticReturnType;
 use Symfony\Component\DependencyInjection\Tests\Fixtures\WitherStaticReturnType;

 require_once __DIR__.'/../Fixtures/includes/autowiring_classes.php';

 class AutowireRequiredMethodsPassTest extends TestCase
 {
-    public function testSetterInjection()
+    use ExpectDeprecationTrait;
+
+    /**
+     * @group legacy
+     */
+    public function testSetterInjectionAnnotation()
    {
+        $this->expectDeprecation('Since symfony/dependency-injection 6.3: Relying on the "@required" annotation on method "Symfony\Component\DependencyInjection\Tests\Compiler\SetterInjectionAnnotation::setFoo()" is deprecated, use the "Symfony\Contracts\Service\Attribute\Required" attribute instead.');
+        $this->expectDeprecation('Since symfony/dependency-injection 6.3: Relying on the "@required" annotation on method "Symfony\Component\DependencyInjection\Tests\Compiler\SetterInjectionAnnotation::setChildMethodWithoutDocBlock()" is deprecated, use the "Symfony\Contracts\Service\Attribute\Required" attribute instead.');
+        $this->expectDeprecation('Since symfony/dependency-injection 6.3: Relying on the "@required" annotation on method "Symfony\Component\DependencyInjection\Tests\Compiler\SetterInjectionParentAnnotation::setDependencies()" is deprecated, use the "Symfony\Contracts\Service\Attribute\Required" attribute instead.');
+
        $container = new ContainerBuilder();
-        $container->register(Foo::class);
+        $container->register(FooAnnotation::class);
        $container->register(A::class);
        $container->register(CollisionA::class);
        $container->register(CollisionB::class);

        // manually configure *one* call, to override autowiring
        $container
-            ->register('setter_injection', SetterInjection::class)
+            ->register('setter_injection', SetterInjectionAnnotation::class)
            ->setAutowired(true)
            ->addMethodCall('setWithCallsConfigured', ['manual_arg1', 'manual_arg2']);

@@ -41,7 +52,7 @@ public function testSetterInjection()
        $methodCalls = $container->getDefinition('setter_injection')->getMethodCalls();

        $this->assertEquals(
-            ['setWithCallsConfigured', 'setFoo', 'setDependencies', 'setChildMethodWithoutDocBlock'],
+            ['setWithCallsConfigured', 'setFoo', 'setChildMethodWithoutDocBlock', 'setDependencies'],
            array_column($methodCalls, 0)
        );

@@ -70,7 +81,41 @@ public function testSetterInjectionWithAttribute()
        $this->assertSame([['setFoo', []]], $methodCalls);
    }

-    public function testExplicitMethodInjection()
+    /**
+     * @group legacy
+     */
+    // @deprecated since Symfony 6.3, to be removed in 7.0
+    public function testExplicitMethodInjectionAnnotation()
+    {
+        $this->expectDeprecation('Since symfony/dependency-injection 6.3: Relying on the "@required" annotation on method "Symfony\Component\DependencyInjection\Tests\Compiler\SetterInjectionAnnotation::setFoo()" is deprecated, use the "Symfony\Contracts\Service\Attribute\Required" attribute instead.');
+        $this->expectDeprecation('Since symfony/dependency-injection 6.3: Relying on the "@required" annotation on method "Symfony\Component\DependencyInjection\Tests\Compiler\SetterInjectionAnnotation::setChildMethodWithoutDocBlock()" is deprecated, use the "Symfony\Contracts\Service\Attribute\Required" attribute instead.');
+        $this->expectDeprecation('Since symfony/dependency-injection 6.3: Relying on the "@required" annotation on method "Symfony\Component\DependencyInjection\Tests\Compiler\SetterInjectionParentAnnotation::setDependencies()" is deprecated, use the "Symfony\Contracts\Service\Attribute\Required" attribute instead.');
+        $this->expectDeprecation('Since symfony/dependency-injection 6.3: Relying on the "@required" annotation on method "Symfony\Component\DependencyInjection\Tests\Compiler\SetterInjectionParentAnnotation::setWithCallsConfigured()" is deprecated, use the "Symfony\Contracts\Service\Attribute\Required" attribute instead.');
+
+        $container = new ContainerBuilder();
+        $container->register(FooAnnotation::class);
+        $container->register(A::class);
+        $container->register(CollisionA::class);
+        $container->register(CollisionB::class);
+
+        $container
+            ->register('setter_injection', SetterInjectionAnnotation::class)
+            ->setAutowired(true)
+            ->addMethodCall('notASetter', []);
+
+        (new ResolveClassPass())->process($container);
+        (new AutowireRequiredMethodsPass())->process($container);
+
+        $methodCalls = $container->getDefinition('setter_injection')->getMethodCalls();
+
+        $this->assertEquals(
+            ['notASetter', 'setFoo', 'setChildMethodWithoutDocBlock', 'setDependencies', 'setWithCallsConfigured'],
+            array_column($methodCalls, 0)
+        );
+        $this->assertEquals([], $methodCalls[0][1]);
+    }
+
+    public function testExplicitMethodInjectionAttribute()
    {
        $container = new ContainerBuilder();
        $container->register(Foo::class);
@@ -95,13 +140,19 @@ public function testExplicitMethodInjection()
        $this->assertEquals([], $methodCalls[0][1]);
    }

+    /**
+     * @group legacy
+     */
    public function testWitherInjection()
    {
+        $this->expectDeprecation('Since symfony/dependency-injection 6.3: Relying on the "@required" annotation on method "Symfony\Component\DependencyInjection\Tests\Compiler\WitherAnnotation::withFoo1()" is deprecated, use the "Symfony\Contracts\Service\Attribute\Required" attribute instead.');
+        $this->expectDeprecation('Since symfony/dependency-injection 6.3: Relying on the "@required" annotation on method "Symfony\Component\DependencyInjection\Tests\Compiler\WitherAnnotation::withFoo2()" is deprecated, use the "Symfony\Contracts\Service\Attribute\Required" attribute instead.');
+
        $container = new ContainerBuilder();
-        $container->register(Foo::class);
+        $container->register(FooAnnotation::class);

        $container
-            ->register('wither', Wither::class)
+            ->register('wither', WitherAnnotation::class)
            ->setAutowired(true);

        (new ResolveClassPass())->process($container);
@@ -117,6 +168,33 @@ public function testWitherInjection()
        $this->assertSame($expected, $methodCalls);
    }

+    /**
+     * @group legacy
+     */
+    public function testWitherAnnotationWithStaticReturnTypeInjection()
+    {
+        $this->expectDeprecation('Since symfony/dependency-injection 6.3: Relying on the "@required" annotation on method "Symfony\Component\DependencyInjection\Tests\Fixtures\WitherAnnotationStaticReturnType::withFoo()" is deprecated, use the "Symfony\Contracts\Service\Attribute\Required" attribute instead.');
+        $this->expectDeprecation('Since symfony/dependency-injection 6.3: Relying on the "@required" annotation on method "Symfony\Component\DependencyInjection\Tests\Fixtures\WitherAnnotationStaticReturnType::setFoo()" is deprecated, use the "Symfony\Contracts\Service\Attribute\Required" attribute instead.');
+
+        $container = new ContainerBuilder();
+        $container->register(FooAnnotation::class);
+
+        $container
+            ->register('wither', WitherAnnotationStaticReturnType::class)
+            ->setAutowired(true);
+
+        (new ResolveClassPass())->process($container);
+        (new AutowireRequiredMethodsPass())->process($container);
+
+        $methodCalls = $container->getDefinition('wither')->getMethodCalls();
+
+        $expected = [
+            ['withFoo', [], true],
+            ['setFoo', []],
+        ];
+        $this->assertSame($expected, $methodCalls);
+    }
+
    public function testWitherWithStaticReturnTypeInjection()
    {
        $container = new ContainerBuilder();

diff --git a/...mfony/Component/DependencyInjection/Tests/Compiler/AutowireRequiredPropertiesPassTest.php b/...mfony/Component/DependencyInjection/Tests/Compiler/AutowireRequiredPropertiesPassTest.php
@@ -12,6 +12,7 @@
 namespace Symfony\Component\DependencyInjection\Tests\Compiler;

 use PHPUnit\Framework\TestCase;
+use Symfony\Bridge\PhpUnit\ExpectDeprecationTrait;
 use Symfony\Component\DependencyInjection\Compiler\AutowireRequiredPropertiesPass;
 use Symfony\Component\DependencyInjection\Compiler\ResolveClassPass;
 use Symfony\Component\DependencyInjection\ContainerBuilder;
@@ -21,8 +22,15 @@

 class AutowireRequiredPropertiesPassTest extends TestCase
 {
+    use ExpectDeprecationTrait;
+
+    /**
+     * @group legacy
+     */
    public function testInjection()
    {
+        $this->expectDeprecation('Since symfony/dependency-injection 6.3: Using the "@required" annotation on property "Symfony\Component\DependencyInjection\Tests\Compiler\PropertiesInjection::$plop" is deprecated, use the "Symfony\Contracts\Service\Attribute\Required" attribute instead.');
+
        $container = new ContainerBuilder();
        $container->register(Bar::class);
        $container->register(A::class);