New mechanism to get reflector in attribute constructor.

Author: donquixote

README.md

@@ -4,6 +4,44 @@ Provides mechanisms for attribute objects to know about the symbol they are atta
 
 ## Usage
 
+### Using AttributeConstructor::getReflector().
+
+Create an attribute class that calls `AttributeConstructor::getReflector()` in the constructor.
+
+```php
+use Ock\ReflectorAwareAttributes\AttributeConstructor;
+use Ock\ReflectorAwareAttributes\ReflectorAwareAttributeInterface;
+
+#[\Attribute(\Attribute::TARGET_ALL)]
+class MyAttribute {
+
+  public readonly \Reflector $reflector;
+
+  public function __construct(): void {
+    $this->reflector = AttributeConstructor::getReflector();
+  }
+
+}
+```
+
+Attach the attribute to a class or other symbol.
+
+```php
+#[MyAttribute]
+class MyClass {}
+```
+
+Call `get_attributes()` to extract attributes instances from the class.
+
+```php
+use function Ock\ReflectorAwareAttributes\get_attributes;
+
+$reflection_class = new \ReflectionClass(MyClass::class);
+$attribute_instances = get_attributes($reflection_class, MyAttribute::class);
+assert($attribute_instances[0] instanceof MyAttribute);
+assert($attribute_instances[0]->reflector === $reflection_function);
+```
+
 ### Using the interface with ->setReflector().
 
 Create an attribute class that implements `ReflectorAwareAttributeInterface`.

functions/functions.attributes.php

@@ -32,7 +32,10 @@ function get_attributes(
   string $name,
   int $flags = \ReflectionAttribute::IS_INSTANCEOF,
 ): array {
-  $instances = get_raw_attributes($reflector, $name, $flags);
+  $instances = AttributeConstructor::callWithReflector(
+    fn () => get_raw_attributes($reflector, $name, $flags),
+    $reflector,
+  );
   foreach ($instances as $instance) {
     if ($instance instanceof ReflectorAwareAttributeInterface) {
       $instance->setReflector($reflector);

src/AttributeConstructor.php

@@ -0,0 +1,64 @@
+<?php
+
+declare(strict_types = 1);
+
+namespace Ock\ReflectorAwareAttributes;
+
+/**
+ * Static methods to be called from attribute constructors.
+ */
+class AttributeConstructor {
+
+  /**
+   * Reflector that an attribute is attached to.
+   */
+  private static \ReflectionClass|\ReflectionFunctionAbstract|\ReflectionParameter|\ReflectionProperty|\ReflectionClassConstant|null $reflector = null;
+
+  /**
+   * @template TReturn
+   *
+   * @param \Closure(): TReturn $callback
+   * @param \ReflectionClass|\ReflectionFunctionAbstract|\ReflectionParameter|\ReflectionProperty|\ReflectionClassConstant $reflector
+   *
+   * @return TReturn
+   */
+  public static function callWithReflector(
+    \Closure $callback,
+    \ReflectionClass|\ReflectionFunctionAbstract|\ReflectionParameter|\ReflectionProperty|\ReflectionClassConstant $reflector,
+  ): mixed {
+    try {
+      self::$reflector = $reflector;
+      return $callback();
+    }
+    finally {
+      self::$reflector = null;
+    }
+  }
+
+  /**
+   * Gets the reflector the current attribute is attached to.
+   *
+   * This should only be called from an attribute constructor that was invoked
+   * with ::newAttributeInstance() above.
+   *
+   * @throws \LogicException
+   *   The method is called at the wrong time.
+   */
+  public static function getReflector(): \ReflectionClass|\ReflectionFunctionAbstract|\ReflectionParameter|\ReflectionProperty|\ReflectionClassConstant {
+    if (self::$reflector === null) {
+      throw new \LogicException("This method can only be called from an attribute constructor, and only when the attribute is instantiated using the 'ock/reflector-aware-attributes' package.");
+    }
+    return self::$reflector;
+  }
+
+  /**
+   * Gets the reflector the current attribute is attached to, or NULL.
+   *
+   * This should only be called from an attribute constructor that was invoked
+   * with ::newAttributeInstance() above.
+   */
+  public static function getReflectorIfSet(): \ReflectionClass|\ReflectionFunctionAbstract|\ReflectionParameter|\ReflectionProperty|\ReflectionClassConstant|null {
+    return self::$reflector;
+  }
+
+}

tests/src/Fixtures/Attribute/ReflectorAwareConstructorTestAttribute.php

@@ -0,0 +1,32 @@
+<?php
+
+declare(strict_types = 1);
+
+namespace Ock\ReflectorAwareAttributes\Tests\Fixtures\Attribute;
+
+use Ock\ReflectorAwareAttributes\AttributeConstructor;
+
+#[\Attribute(\Attribute::IS_REPEATABLE | \Attribute::TARGET_ALL)]
+class ReflectorAwareConstructorTestAttribute {
+
+  public readonly ?\Reflector $reflectorIfSet;
+
+  public readonly ?\Reflector $reflector;
+
+  public readonly ?\LogicException $exception;
+
+  public function __construct(
+    public readonly string $name,
+  ) {
+    $this->reflectorIfSet = AttributeConstructor::getReflectorIfSet();
+    try {
+      $this->reflector = AttributeConstructor::getReflector();
+      $this->exception = NULL;
+    }
+    catch (\LogicException $e) {
+      $this->reflector = NULL;
+      $this->exception = $e;
+    }
+  }
+
+}

tests/src/Fixtures/TestClassWithAttributes.php

@@ -5,12 +5,14 @@
 namespace Ock\ReflectorAwareAttributes\Tests\Fixtures;
 
 use Ock\ReflectorAwareAttributes\Tests\Fixtures\Attribute\OtherTestAttribute;
+use Ock\ReflectorAwareAttributes\Tests\Fixtures\Attribute\ReflectorAwareConstructorTestAttribute;
 use Ock\ReflectorAwareAttributes\Tests\Fixtures\Attribute\ReflectorAwareTestAttribute;
 use Ock\ReflectorAwareAttributes\Tests\Fixtures\Attribute\TestAttribute;
 
 #[TestAttribute('on a class')]
 #[OtherTestAttribute('on a class')]
 #[ReflectorAwareTestAttribute]
+#[ReflectorAwareConstructorTestAttribute('on a class')]
 class TestClassWithAttributes {
 
   #[TestAttribute('on a class constant')]

tests/src/GetAttributesTest.php

@@ -5,6 +5,7 @@
 namespace Ock\ReflectorAwareAttributes\Tests;
 
 use Ock\ReflectorAwareAttributes\Tests\Fixtures\Attribute\OtherTestAttribute;
+use Ock\ReflectorAwareAttributes\Tests\Fixtures\Attribute\ReflectorAwareConstructorTestAttribute;
 use Ock\ReflectorAwareAttributes\Tests\Fixtures\Attribute\ReflectorAwareTestAttribute;
 use Ock\ReflectorAwareAttributes\Tests\Fixtures\Attribute\TestAttribute;
 use Ock\ReflectorAwareAttributes\Tests\Fixtures\Attribute\TestAttributeInterface;
@@ -39,6 +40,20 @@ public function testSetReflector(): void {
     $this->assertNull($attributes[0]->reflector);
   }
 
+  public function testGetReflectorFromConstructor(): void {
+    $reflector = new \ReflectionClass(TestClassWithAttributes::class);
+    [$attribute] = get_attributes($reflector, ReflectorAwareConstructorTestAttribute::class);
+    $this->assertSame($reflector, $attribute->reflectorIfSet);
+    $this->assertSame($reflector, $attribute->reflector);
+    $this->assertNull($attribute->exception ?? NULL);
+
+    [$raw_attribute] = get_raw_attributes($reflector, ReflectorAwareConstructorTestAttribute::class);
+    $this->assertNull($raw_attribute->reflectorIfSet);
+    $this->assertNull($raw_attribute->reflector ?? NULL);
+    $this->assertNotNull($raw_attribute->exception);
+    $this->assertSame(\LogicException::class, get_class($raw_attribute->exception));
+  }
+
   /**
    * @param \Closure(\ReflectionClass|\ReflectionFunctionAbstract|\ReflectionParameter|\ReflectionProperty|\ReflectionClassConstant, class-string, int=): list<object> $get_attributes
    */