Support constructor method-level qualifiers in BcParameterQualifier (#308)

This change enhances backward compatibility by allowing method-level
Qualifier attributes on constructors, addressing the issue where
packages like bear/streamer use Qualifier-only attributes (without
InjectInterface) on single-parameter constructors.

Key changes:
- Remove TARGET_PARAMETER requirement: Method-level qualifiers no
  longer need to support TARGET_PARAMETER, as they are meant to be
  used at the method level
- Add constructor-specific logic: For constructors, Qualifier-only
  attributes are sufficient since InjectInterface is implicit
- For setters: Still require InjectInterface + Qualifier combination

All changes are confined to src-deprecated/ directory, keeping the
core codebase clean. This embodies Ray.Di's BC (backward compatibility)
philosophy.

Test updates:
- Add constructor test case with Qualifier-only attribute
- Update existing tests to reflect new Qualifier inference behavior
- Fix binding declarations in test modules

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude <noreply@anthropic.com>

Author: koriym

src-deprecated/di/BcParameterQualifier.php

@@ -13,10 +13,13 @@
 use function count;
 
 /**
- * Backward compatible parameter qualifier for single-parameter setters
+ * Backward compatible parameter qualifier for single-parameter methods
  *
- * Automatically applies method-level InjectInterface+Qualifier attributes to parameters
- * when the method has only one parameter and no parameter-level qualifier is specified.
+ * Automatically applies method-level Qualifier attributes to parameters when:
+ * - Method has exactly one parameter
+ * - Parameter has no explicit qualifier
+ * - For constructors: Method has a Qualifier attribute (InjectInterface is implicit)
+ * - For setters: Method has an attribute implementing both InjectInterface and Qualifier
  *
  * This behavior is deprecated for the following reasons:
  * - Violates Single Responsibility Principle (one attribute serving dual purposes)
@@ -44,10 +47,10 @@ final class BcParameterQualifier
      * Returns parameter name mapping if:
      * 1. Method has exactly one parameter
      * 2. Parameter has no qualifier attribute
-     * 3. Method has an attribute implementing both InjectInterface and Qualifier
-     * 4. The attribute supports TARGET_PARAMETER (not just TARGET_METHOD)
+     * 3. For setters: Method has an attribute implementing both InjectInterface and Qualifier
+     * 4. For constructors: Method has a Qualifier attribute (InjectInterface is implicit)
      *
-     * @param ReflectionMethod $method The setter method to analyze
+     * @param ReflectionMethod $method The method to analyze
      *
      * @return array<string, string> Parameter name to qualifier mapping (empty if not applicable)
      */
@@ -74,10 +77,10 @@ public static function getNames(ReflectionMethod $method): array
      * Returns the qualifier name if:
      * 1. Method has exactly one parameter
      * 2. Parameter has no qualifier attribute
-     * 3. Method has an attribute implementing both InjectInterface and Qualifier
-     * 4. The attribute supports TARGET_PARAMETER (not just TARGET_METHOD)
+     * 3. For setters: Method has an attribute implementing both InjectInterface and Qualifier
+     * 4. For constructors: Method has a Qualifier attribute (InjectInterface is implicit)
      *
-     * @param ReflectionMethod $method The setter method to analyze
+     * @param ReflectionMethod $method The method to analyze
      *
      * @return string The qualifier class name, or empty string if not applicable
      */
@@ -97,33 +100,29 @@ private static function getQualifier(ReflectionMethod $method): string
             return '';
         }
 
-        // Check method-level attributes for InjectInterface+Qualifier combination
+        $isConstructor = $method->name === '__construct';
+
+        // Check method-level attributes for Qualifier
         $methodAttributes = $method->getAttributes();
         foreach ($methodAttributes as $attr) {
             $instance = $attr->newInstance();
-
-            // Must implement InjectInterface
-            if (! $instance instanceof InjectInterface) {
-                continue;
-            }
-
-            // Must also be marked with Qualifier
             $attrClass = new ReflectionClass($attr->getName());
             $qualifierAttr = $attrClass->getAttributes(Qualifier::class);
 
+            // Skip if not a Qualifier
             if ($qualifierAttr === []) {
                 continue;
             }
 
-            // IMPORTANT: Only infer if attribute supports TARGET_PARAMETER
-            // If it's TARGET_METHOD only, it's meant for Provider/InjectionPoint pattern
-            if (! self::supportsParameterTarget($attrClass)) {
-                continue;
+            // For constructors: Qualifier alone is sufficient (InjectInterface is implicit)
+            if ($isConstructor) {
+                return $attr->getName();
             }
 
-            // Found a method-level attribute that is both Inject and Qualifier
-            // AND supports being used at parameter level
-            return $attr->getName();
+            // For setters: Must also implement InjectInterface
+            if ($instance instanceof InjectInterface) {
+                return $attr->getName();
+            }
         }
 
         return '';
@@ -147,25 +146,4 @@ private static function hasParameterQualifier(array $attributes): bool
 
         return false;
     }
-
-    /**
-     * Check if attribute supports TARGET_PARAMETER
-     *
-     * @param ReflectionClass<object> $attrClass
-     */
-    private static function supportsParameterTarget(ReflectionClass $attrClass): bool
-    {
-        $attributeAttrs = $attrClass->getAttributes(\Attribute::class);
-        if ($attributeAttrs === []) {
-            return false;
-        }
-
-        $attributeInstance = $attributeAttrs[0]->newInstance();
-        if (! $attributeInstance instanceof \Attribute) {
-            return false;
-        }
-
-        // Check if Attribute::TARGET_PARAMETER is included in the flags
-        return ($attributeInstance->flags & \Attribute::TARGET_PARAMETER) !== 0;
-    }
 }

tests/di/AnnotatedClassTest.php

@@ -29,7 +29,7 @@ public function testInvoke(): void
         (new Bind($container, FakeHandleInterface::class))->toProvider(FakeHandleProvider::class);
         (new Bind($container, FakeMirrorInterface::class))->annotatedWith('right')->to(FakeMirrorRight::class);
         (new Bind($container, FakeMirrorInterface::class))->annotatedWith('left')->to(FakeMirrorRight::class);
-        (new Bind($container, FakeGearStickInterface::class))->toProvider(FakeGearStickProvider::class);
+        (new Bind($container, FakeGearStickInterface::class))->annotatedWith(FakeGearStickInject::class)->toProvider(FakeGearStickProvider::class);
         $car = $newInstance($container);
         if (! $car instanceof FakeCar) {
             throw new LogicException();

tests/di/BcParameterQualifierTest.php

@@ -6,6 +6,7 @@
 
 use PHPUnit\Framework\TestCase;
 use Ray\Di\Annotation\FakeInjectOne;
+use Ray\Di\Annotation\FakeQualifierOnly;
 use ReflectionMethod;
 
 class BcParameterQualifierTest extends TestCase
@@ -55,14 +56,25 @@ public function testNoNamesForMethodWithoutInjectInterface(): void
         $this->assertSame([], $names);
     }
 
-    public function testNoNamesForTargetMethodOnly(): void
+    public function testNamesForTargetMethodOnly(): void
     {
-        // FakeGearStickInject has TARGET_METHOD only, not TARGET_PARAMETER
-        // It's meant for Provider/InjectionPoint pattern, not parameter binding
+        // FakeGearStickInject has TARGET_METHOD only
+        // BC parameter qualifier now supports TARGET_METHOD-only attributes for backward compatibility
         $method = new ReflectionMethod(FakeBcParameterQualifierClass::class, 'setSingleParamMethodOnly');
         /** @psalm-suppress DeprecatedClass */
         $names = BcParameterQualifier::getNames($method);
 
-        $this->assertSame([], $names);
+        $this->assertSame(['param' => FakeGearStickInject::class], $names);
+    }
+
+    public function testConstructorWithQualifierOnly(): void
+    {
+        // Constructor with Qualifier-only attribute (no InjectInterface)
+        // BC parameter qualifier should apply for constructors (InjectInterface is implicit)
+        $method = new ReflectionMethod(FakeBcConstructorQualifierClass::class, '__construct');
+        /** @psalm-suppress DeprecatedClass */
+        $names = BcParameterQualifier::getNames($method);
+
+        $this->assertSame(['param' => FakeQualifierOnly::class], $names);
     }
 }

tests/di/Fake/Annotation/FakeQualifierOnly.php

@@ -0,0 +1,16 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Ray\Di\Annotation;
+
+use Attribute;
+use Ray\Di\Di\Qualifier;
+
+/**
+ * Qualifier-only attribute for testing (no InjectInterface)
+ */
+#[Attribute(Attribute::TARGET_METHOD), Qualifier]
+final class FakeQualifierOnly
+{
+}

tests/di/Fake/FakeBcConstructorQualifierClass.php

@@ -0,0 +1,19 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Ray\Di;
+
+use Ray\Di\Annotation\FakeQualifierOnly;
+
+class FakeBcConstructorQualifierClass
+{
+    /**
+     * Constructor with method-level Qualifier-only attribute (no InjectInterface)
+     * This should trigger BC parameter qualifier for constructors
+     */
+    #[FakeQualifierOnly]
+    public function __construct(public $param)
+    {
+    }
+}

tests/di/Fake/FakeBcParameterQualifierClass.php

@@ -18,7 +18,7 @@ class FakeBcParameterQualifierClass
 
     /**
      * Single parameter with method-level InjectInterface+Qualifier
-     * This should trigger BC parameter qualifier (FakeInjectOne supports TARGET_PARAMETER)
+     * This should trigger BC parameter qualifier
      */
     #[FakeInjectOne]
     public function setSingleParam(FakeGearStickInterface $param): void
@@ -63,12 +63,12 @@ public function setSingleParamNoInject(FakeGearStickInterface $param): void
     }
 
     /**
-     * Method-level attribute with TARGET_METHOD only (Provider pattern)
-     * Should NOT infer because it doesn't support TARGET_PARAMETER
+     * Method-level attribute with TARGET_METHOD only
+     * BC parameter qualifier now supports this for backward compatibility
      */
     #[FakeGearStickInject('test')]
     public function setSingleParamMethodOnly(FakeGearStickInterface $param): void
     {
-        // This is for Provider/InjectionPoint pattern, not parameter binding
+        $this->singleParam = $param;
     }
 }

tests/di/Fake/FakeCarModule.php

@@ -18,7 +18,7 @@ protected function configure()
         $this->bind(FakeMirrorInterface::class)->annotatedWith('left')->to(FakeMirrorLeft::class)->in(Scope::SINGLETON); // named binding
         $this->bind('')->annotatedWith('logo')->toInstance('momo');
         $this->bind(FakeHandleInterface::class)->toProvider(FakeHandleProvider::class);
-        $this->bind(FakeGearStickInterface::class)->to(FakeLeatherGearStick::class);
+        $this->bind(FakeGearStickInterface::class)->annotatedWith(FakeGearStickInject::class)->to(FakeLeatherGearStick::class);
         $this->bindInterceptor(
             $this->matcher->any(),
             $this->matcher->any('start'),

tests/di/Fake/FakePhp8CarModule.php

@@ -21,7 +21,7 @@ protected function configure()
         $this->bind(FakeMirrorInterface::class)->annotatedWith(FakeRight::class)->to(FakeMirrorRight::class); // named binding
         $this->bind('')->annotatedWith('logo')->toInstance('momo');
         $this->bind(FakeHandleInterface::class)->toProvider(FakeHandleProvider::class);
-        $this->bind(FakeGearStickInterface::class)->toProvider(FakeGearStickProvider::class);
+        $this->bind(FakeGearStickInterface::class)->annotatedWith(FakeGearStickInject::class)->toProvider(FakeGearStickProvider::class);
         $this->bind()->annotatedWith(FakeInjectOne::class)->toInstance(1);
     }
 }

tests/di/VisitorTest.php

@@ -173,7 +173,7 @@ public function visitArgument(string $index, bool $isDefaultAvailable, $defaultV
 
         $this->dependency->accept($visitor);
         $this->assertStringContainsString('Ray\Di\FakeCar', $collector->newInstance);
-        $this->assertStringContainsString('(prototype.Ray\Di\FakeGearStickInterface-)', $collector->newInstance);
+        $this->assertStringContainsString('(prototype.Ray\Di\FakeGearStickInterface-Ray\Di\FakeGearStickInject)', $collector->newInstance);
         $this->assertSame('setTires(prototype.Ray\Di\FakeEngineInterface-)', $collector->methods[0]);
         $this->assertSame('setHardtop(prototype.Ray\Di\FakeTyreInterface-,prototype.Ray\Di\FakeTyreInterface-)', $collector->methods[1]);
     }