[12.x] Introduce Reflector methods for accessing class attributes

src/Illuminate/Support/Reflector.php

@@ -2,6 +2,7 @@
 
 namespace Illuminate\Support;
 
+use ReflectionAttribute;
 use ReflectionClass;
 use ReflectionEnum;
 use ReflectionMethod;
@@ -56,6 +57,46 @@ public static function isCallable($var, $syntaxOnly = false)
         return false;
     }
 
+    /**
+     * Get the specified class attribute, optionally following an inheritance chain.
+     *
+     * @template TAttribute of object
+     *
+     * @param  object|class-string  $objectOrClass
+     * @param  class-string<TAttribute>  $attribute
+     * @return TAttribute|null
+     */
+    public static function getClassAttribute($objectOrClass, $attribute, $ascend = false)
+    {
+        return static::getClassAttributes($objectOrClass, $attribute, $ascend)->flatten()->first();
+    }
+
+    /**
+     * Get the specified class attribute(s), optionally following an inheritance chain.
+     *
+     * @template TTarget of object
+     * @template TAttribute of object
+     *
+     * @param  TTarget|class-string<TTarget>  $objectOrClass
+     * @param  class-string<TAttribute>  $attribute
+     * @return ($includeParents is true ? Collection<class-string<contravariant TTarget>, Collection<int, TAttribute>> : Collection<int, TAttribute>)
+     */
+    public static function getClassAttributes($objectOrClass, $attribute, $includeParents = false)
+    {
+        $reflectionClass = new ReflectionClass($objectOrClass);
+
+        $attributes = [];
+
+        do {
+            $attributes[$reflectionClass->name] = new Collection(array_map(
+                fn (ReflectionAttribute $reflectionAttribute) => $reflectionAttribute->newInstance(),
+                $reflectionClass->getAttributes($attribute)
+            ));
+        } while ($includeParents && false !== $reflectionClass = $reflectionClass->getParentClass());
+
+        return $includeParents ? new Collection($attributes) : reset($attributes);
+    }
+
     /**
      * Get the class name of the given parameter's type, if possible.
      *

tests/Support/Fixtures/ClassesWithAttributes.php

@@ -0,0 +1,41 @@
+<?php
+
+namespace Illuminate\Tests\Support\Fixtures;
+
+use Attribute;
+
+#[Attribute(Attribute::TARGET_CLASS | Attribute::IS_REPEATABLE)]
+class UnusedAttr
+{
+}
+
+#[Attribute(Attribute::TARGET_CLASS | Attribute::IS_REPEATABLE)]
+class ParentOnlyAttr
+{
+}
+
+#[Attribute(Attribute::TARGET_CLASS | Attribute::IS_REPEATABLE)]
+class StrAttr
+{
+    public function __construct(public string $string)
+    {
+    }
+}
+
+#[Attribute(Attribute::TARGET_CLASS | Attribute::IS_REPEATABLE)]
+class NumAttr
+{
+    public function __construct(public int $number)
+    {
+    }
+}
+
+#[StrAttr('lazy'), StrAttr('dog'), NumAttr(2), NumAttr(3), ParentOnlyAttr]
+class ParentClass
+{
+}
+
+#[StrAttr('quick'), StrAttr('brown'), StrAttr('fox'), NumAttr(7)]
+class ChildClass extends ParentClass
+{
+}

tests/Support/SupportReflectorTest.php

@@ -75,6 +75,63 @@ public function testIsCallable()
         $this->assertFalse(Reflector::isCallable(['TotallyMissingClass', 'foo']));
         $this->assertTrue(Reflector::isCallable(['TotallyMissingClass', 'foo'], true));
     }
+
+    public function testGetClassAttributes()
+    {
+        require_once __DIR__.'/Fixtures/ClassesWithAttributes.php';
+
+        $this->assertSame([], Reflector::getClassAttributes(Fixtures\ChildClass::class, Fixtures\UnusedAttr::class)->toArray());
+
+        $this->assertSame(
+            [Fixtures\ChildClass::class => [], Fixtures\ParentClass::class => []],
+            Reflector::getClassAttributes(Fixtures\ChildClass::class, Fixtures\UnusedAttr::class, true)->toArray()
+        );
+
+        $this->assertSame(
+            ['quick', 'brown', 'fox'],
+            Reflector::getClassAttributes(Fixtures\ChildClass::class, Fixtures\StrAttr::class)->map->string->all()
+        );
+
+        $this->assertSame(
+            ['quick', 'brown', 'fox', 'lazy', 'dog'],
+            Reflector::getClassAttributes(Fixtures\ChildClass::class, Fixtures\StrAttr::class, true)->flatten()->map->string->all()
+        );
+
+        $this->assertSame(7, Reflector::getClassAttributes(Fixtures\ChildClass::class, Fixtures\NumAttr::class)->sum->number);
+        $this->assertSame(12, Reflector::getClassAttributes(Fixtures\ChildClass::class, Fixtures\NumAttr::class, true)->flatten()->sum->number);
+        $this->assertSame(5, Reflector::getClassAttributes(Fixtures\ParentClass::class, Fixtures\NumAttr::class)->sum->number);
+        $this->assertSame(5, Reflector::getClassAttributes(Fixtures\ParentClass::class, Fixtures\NumAttr::class, true)->flatten()->sum->number);
+
+        $this->assertSame(
+            [Fixtures\ChildClass::class, Fixtures\ParentClass::class],
+            Reflector::getClassAttributes(Fixtures\ChildClass::class, Fixtures\StrAttr::class, true)->keys()->all()
+        );
+
+        $this->assertContainsOnlyInstancesOf(
+            Fixtures\StrAttr::class,
+            Reflector::getClassAttributes(Fixtures\ChildClass::class, Fixtures\StrAttr::class)->all()
+        );
+
+        $this->assertContainsOnlyInstancesOf(
+            Fixtures\StrAttr::class,
+            Reflector::getClassAttributes(Fixtures\ChildClass::class, Fixtures\StrAttr::class, true)->flatten()->all()
+        );
+    }
+
+    public function testGetClassAttribute()
+    {
+        require_once __DIR__.'/Fixtures/ClassesWithAttributes.php';
+
+        $this->assertNull(Reflector::getClassAttribute(Fixtures\ChildClass::class, Fixtures\UnusedAttr::class));
+        $this->assertNull(Reflector::getClassAttribute(Fixtures\ChildClass::class, Fixtures\UnusedAttr::class, true));
+        $this->assertNull(Reflector::getClassAttribute(Fixtures\ChildClass::class, Fixtures\ParentOnlyAttr::class));
+        $this->assertInstanceOf(Fixtures\ParentOnlyAttr::class, Reflector::getClassAttribute(Fixtures\ChildClass::class, Fixtures\ParentOnlyAttr::class, true));
+        $this->assertInstanceOf(Fixtures\StrAttr::class, Reflector::getClassAttribute(Fixtures\ChildClass::class, Fixtures\StrAttr::class));
+        $this->assertInstanceOf(Fixtures\StrAttr::class, Reflector::getClassAttribute(Fixtures\ChildClass::class, Fixtures\StrAttr::class, true));
+        $this->assertSame('quick', Reflector::getClassAttribute(Fixtures\ChildClass::class, Fixtures\StrAttr::class)->string);
+        $this->assertSame('quick', Reflector::getClassAttribute(Fixtures\ChildClass::class, Fixtures\StrAttr::class, true)->string);
+        $this->assertSame('lazy', Reflector::getClassAttribute(Fixtures\ParentClass::class, Fixtures\StrAttr::class)->string);
+    }
 }
 
 class A