From f67f5f5219e3f688d8b48f61e4c22b3c97f1dcd5 Mon Sep 17 00:00:00 2001
From: Wilmer Arambula <terabytesoftw@gmail.com>
Date: Tue, 3 Mar 2026 16:47:02 -0300
Subject: [PATCH 1/2] feat(helper): Add generic PHPStan annotations to
 `Reflector` for typed attribute inference in consumers.

---
 CHANGELOG.md      |  2 ++
 src/Reflector.php | 16 +++++++++++++---
 2 files changed, 15 insertions(+), 3 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index a4561b8..fe52d8e 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,6 +2,8 @@
 
 ## 0.2.1 Under development
 
+- Enh #10: Add generic PHPStan annotations to `Reflector` for typed attribute inference in consumers (@terabytesoftw)
+
 ## 0.2.1 March 3, 2026
 
 - Enh #9: Add `Reflector` helper for class, property, type, and attribute metadata introspection (@terabytesoftw)
diff --git a/src/Reflector.php b/src/Reflector.php
index 5e437fe..e5903df 100644
--- a/src/Reflector.php
+++ b/src/Reflector.php
@@ -71,7 +71,9 @@ public static function cacheSize(): int
      *
      * @return array Class attributes.
      *
-     * @phpstan-return list<ReflectionAttribute<object>>
+     * @phpstan-template TAttribute of object
+     * @phpstan-param class-string<TAttribute>|null $attribute
+     * @phpstan-return ($attribute is null ? list<ReflectionAttribute<object>> : list<ReflectionAttribute<TAttribute>>)
      */
     public static function classAttributes(object|string $class, string|null $attribute = null, int $flags = 0): array
     {
@@ -111,6 +113,10 @@ public static function clearCache(): void
      * ```
      *
      * @return object|null First matching instantiated attribute, or `null` if no matching attribute is found.
+     *
+     * @phpstan-template TAttribute of object
+     * @phpstan-param class-string<TAttribute> $attribute
+     * @phpstan-return TAttribute|null
      */
     public static function firstPropertyAttribute(
         object|string $class,
@@ -205,7 +211,9 @@ public static function property(object|string $class, string $property): Reflect
      *
      * @return array Instantiated property attributes.
      *
-     * @phpstan-return list<object>
+     * @phpstan-template TAttribute of object
+     * @phpstan-param class-string<TAttribute>|null $attribute
+     * @phpstan-return ($attribute is null ? list<object> : list<TAttribute>)
      */
     public static function propertyAttributeInstances(
         object|string $class,
@@ -236,7 +244,9 @@ public static function propertyAttributeInstances(
      *
      * @return array Property attributes.
      *
-     * @phpstan-return list<ReflectionAttribute<object>>
+     * @phpstan-template TAttribute of object
+     * @phpstan-param class-string<TAttribute>|null $attribute
+     * @phpstan-return ($attribute is null ? list<ReflectionAttribute<object>> : list<ReflectionAttribute<TAttribute>>)
      */
     public static function propertyAttributes(
         object|string $class,

From 5804e9f8b67ca23dabb28347b4710e209334fce3 Mon Sep 17 00:00:00 2001
From: Wilmer Arambula <terabytesoftw@gmail.com>
Date: Tue, 3 Mar 2026 16:53:43 -0300
Subject: [PATCH 2/2] Apply fixed Coderabbitai review.

---
 CHANGELOG.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index fe52d8e..135e7a6 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,6 +1,6 @@
 # ChangeLog
 
-## 0.2.1 Under development
+## 0.2.2 Under development
 
 - Enh #10: Add generic PHPStan annotations to `Reflector` for typed attribute inference in consumers (@terabytesoftw)