Add AttributeReader* and AttributeInstantiator*.

Author: donquixote

README.md

@@ -78,3 +78,62 @@ $attribute_instances = get_attributes($reflection_function, MyReflectorAwareAttr
 assert($attribute_instances[0] instanceof MyReflectorAwareAttribute);
 assert($attribute_instances[0]->reflector === $reflection_function);
 ```
+
+### Using AttributeReader.
+
+The AttributeReader class allows to support attribute types that do not use the mechanisms from this package.
+
+Assume you have an attribute class like this, coming from a 3rd party package:
+
+```php
+#[\Attribute(\Attribute::TARGET_CLASS)]
+class ThirdPartyAttribute {
+  public readonly \Reflector $reflector;
+}
+```
+
+You can create a custom instantiator that will populate the property.
+
+Ideally this should use the decorator pattern, so that multiple operations can be applied.
+
+```php
+use Ock\ReflectorAwareAttributes\Instantiator\AttributeInstantiatorInterface;
+use Ock\ReflectorAwareAttributes\Reader\AttributeReader;
+
+class MyInstantiator implements AttributeInstantiatorInterface {
+
+  public function __construct(
+    private readonly AttributeInstantiatorInterface $decorated,
+  ) {}
+
+  public function newInstance(
+    \ReflectionAttribute $attribute,
+    \ReflectionClassConstant|\ReflectionParameter|\ReflectionClass|\ReflectionProperty|\ReflectionFunctionAbstract $reflector,
+  ): object {
+    $instance = $this->decorated->newInstance($attribute, $reflector);
+    if ($instance instanceof ThirdPartyAttribute) {
+      $instance->reflector = $reflector;
+    }
+    return $instance;
+  }
+
+}
+```
+
+Now we can use a reader with this instantiator decorator to get the attribute instances.
+
+```php
+#[ThirdPartyAttribute]
+class C {}
+
+$reader = AttributeReader::basic()
+  ->withDecoratingInstantiator(
+    fn (AttributeInstantiatorInterface $decorated) => new MyInstantiator($decorated),
+  );
+
+$reflection_class = new \ReflectionClass(C::class);
+$instances = $reader->getInstances($reflection_class, ThirdPartyAttribute::class);
+
+assert($instances[0] instanceof ThirdPartyAttribute);
+assert($instances[0]->reflector === $reflection_class);
+```

src/Instantiator/AttributeInstantiator.php

@@ -0,0 +1,37 @@
+<?php
+
+declare(strict_types = 1);
+
+namespace Ock\ReflectorAwareAttributes\Instantiator;
+
+/**
+ * Static factories for attribute instantiators.
+ */
+class AttributeInstantiator {
+
+  /**
+   * Creates an instantiator with decorators.
+   *
+   * @param array<\Closure(AttributeInstantiatorInterface): AttributeInstantiatorInterface> $decorators
+   *   Callbacks that decorate the instantiator.
+   */
+  public static function compose(array $decorators): AttributeInstantiatorInterface {
+    $instantiator = new BasicAttributeInstantiator();
+    foreach ($decorators as $decorator) {
+      $instantiator = $decorator($instantiator);
+      assert($instantiator instanceof AttributeInstantiatorInterface);
+    }
+    return $instantiator;
+  }
+
+  /**
+   * Creates an instantiator with the default decorators from this package.
+   */
+  public static function createDefault(): AttributeInstantiatorInterface {
+    $instantiator = new BasicAttributeInstantiator();
+    $instantiator = new ReflectorProvidingDecorator($instantiator);
+    $instantiator = new ReflectorSettingDecorator($instantiator);
+    return $instantiator;
+  }
+
+}

src/Instantiator/AttributeInstantiatorInterface.php

@@ -0,0 +1,14 @@
+<?php
+
+declare(strict_types = 1);
+
+namespace Ock\ReflectorAwareAttributes\Instantiator;
+
+interface AttributeInstantiatorInterface {
+
+  public function newInstance(
+    \ReflectionAttribute $attribute,
+    \ReflectionClass|\ReflectionFunctionAbstract|\ReflectionParameter|\ReflectionProperty|\ReflectionClassConstant $reflector,
+  ): object;
+
+}

src/Instantiator/BasicAttributeInstantiator.php

@@ -0,0 +1,20 @@
+<?php
+
+declare(strict_types = 1);
+
+namespace Ock\ReflectorAwareAttributes\Instantiator;
+
+/**
+ * Basic attribute instantiator without any additional functionality.
+ */
+class BasicAttributeInstantiator implements AttributeInstantiatorInterface {
+
+  #[\Override]
+  public function newInstance(
+    \ReflectionAttribute $attribute,
+    \ReflectionClass|\ReflectionFunctionAbstract|\ReflectionParameter|\ReflectionProperty|\ReflectionClassConstant $reflector,
+  ): object {
+    return $attribute->newInstance();
+  }
+
+}

src/Instantiator/ReflectorProvidingDecorator.php

@@ -0,0 +1,31 @@
+<?php
+
+declare(strict_types = 1);
+
+namespace Ock\ReflectorAwareAttributes\Instantiator;
+
+use Ock\ReflectorAwareAttributes\AttributeConstructor;
+
+/**
+ * Decorator that makes the reflector available to the attribute constructor.
+ *
+ * @see AttributeConstructor::getReflector()
+ */
+class ReflectorProvidingDecorator implements AttributeInstantiatorInterface {
+
+  public function __construct(
+    private readonly AttributeInstantiatorInterface $decorated,
+  ) {}
+
+  #[\Override]
+  public function newInstance(
+    \ReflectionAttribute $attribute,
+    \ReflectionClass|\ReflectionFunctionAbstract|\ReflectionParameter|\ReflectionProperty|\ReflectionClassConstant $reflector,
+  ): object {
+    return AttributeConstructor::callWithReflector(
+      fn () => $this->decorated->newInstance($attribute, $reflector),
+      $reflector,
+    );
+  }
+
+}

src/Instantiator/ReflectorSettingDecorator.php

@@ -0,0 +1,32 @@
+<?php
+
+declare(strict_types = 1);
+
+namespace Ock\ReflectorAwareAttributes\Instantiator;
+
+use Ock\ReflectorAwareAttributes\ReflectorAwareAttributeInterface;
+
+/**
+ * Decorator that calls ->setReflector() on the attribute instance.
+ *
+ * @see ReflectorAwareAttributeInterface::setReflector()
+ */
+class ReflectorSettingDecorator implements AttributeInstantiatorInterface {
+
+  public function __construct(
+    private readonly AttributeInstantiatorInterface $decorated,
+  ) {}
+
+  #[\Override]
+  public function newInstance(
+    \ReflectionAttribute $attribute,
+    \ReflectionClass|\ReflectionFunctionAbstract|\ReflectionParameter|\ReflectionProperty|\ReflectionClassConstant $reflector,
+  ): object {
+    $instance = $this->decorated->newInstance($attribute, $reflector);
+    if ($instance instanceof ReflectorAwareAttributeInterface) {
+      $instance->setReflector($reflector);
+    }
+    return $instance;
+  }
+
+}

src/Reader/AttributeReader.php

@@ -0,0 +1,65 @@
+<?php
+
+declare(strict_types = 1);
+
+namespace Ock\ReflectorAwareAttributes\Reader;
+
+use Ock\ReflectorAwareAttributes\Instantiator\AttributeInstantiator;
+use Ock\ReflectorAwareAttributes\Instantiator\AttributeInstantiatorInterface;
+use Ock\ReflectorAwareAttributes\Instantiator\BasicAttributeInstantiator;
+
+class AttributeReader implements AttributeReaderInterface {
+
+  /**
+   * Static cache for the basic reader.
+   */
+  private static self $basicInstance;
+
+  /**
+   * Static cache for the default reader.
+   */
+  private static self $defaultInstance;
+
+  public function __construct(
+    private AttributeInstantiatorInterface $instantiator,
+  ) {}
+
+  /**
+   * Creates a reader with no extra behaviors.
+   */
+  public static function basic(): self {
+    return self::$basicInstance ??= new self(new BasicAttributeInstantiator());
+  }
+
+  /**
+   * Creates a reader with the default extra behaviors from this package.
+   */
+  public static function default(): self {
+    return self::$defaultInstance ??= new self(AttributeInstantiator::createDefault());
+  }
+
+  /**
+   * @param \Closure(AttributeInstantiatorInterface): AttributeInstantiatorInterface $decorate
+   *
+   * @return static
+   */
+  public function withDecoratingInstantiator(\Closure $decorate): static {
+    $clone = clone $this;
+    $clone->instantiator = $decorate($this->instantiator);
+    return $clone;
+  }
+
+  #[\Override]
+  public function getInstances(
+    \ReflectionClass|\ReflectionFunctionAbstract|\ReflectionParameter|\ReflectionProperty|\ReflectionClassConstant $reflector,
+    string $name,
+    int $flags = \ReflectionAttribute::IS_INSTANCEOF,
+  ): array {
+    $attributes = $reflector->getAttributes($name, $flags);
+    return array_map(
+      fn (\ReflectionAttribute $attribute) => $this->instantiator->newInstance($attribute, $reflector),
+      $attributes,
+    );
+  }
+
+}

src/Reader/AttributeReaderInterface.php

@@ -0,0 +1,28 @@
+<?php
+
+/**
+ * @file
+ */
+
+declare(strict_types = 1);
+
+namespace Ock\ReflectorAwareAttributes\Reader;
+
+interface AttributeReaderInterface {
+
+  /**
+   * @template T of object
+   *
+   * @param \ReflectionClass|\ReflectionFunctionAbstract|\ReflectionParameter|\ReflectionProperty|\ReflectionClassConstant $reflector
+   * @param class-string<T> $name
+   * @param int $flags
+   *
+   * @return list<T&object>
+   */
+  public function getInstances(
+    \ReflectionClass|\ReflectionFunctionAbstract|\ReflectionParameter|\ReflectionProperty|\ReflectionClassConstant $reflector,
+    string $name,
+    int $flags = \ReflectionAttribute::IS_INSTANCEOF,
+  ): array;
+
+}

tests/src/AttributeReaderTest.php

@@ -0,0 +1,37 @@
+<?php
+
+declare(strict_types = 1);
+
+namespace Ock\ReflectorAwareAttributes\Tests;
+
+use Ock\ReflectorAwareAttributes\Instantiator\BasicAttributeInstantiator;
+use Ock\ReflectorAwareAttributes\Instantiator\ReflectorProvidingDecorator;
+use Ock\ReflectorAwareAttributes\Reader\AttributeReader;
+use PHPUnit\Framework\Assert;
+use PHPUnit\Framework\Attributes\CoversClass;
+use PHPUnit\Framework\TestCase;
+
+#[CoversClass(AttributeReader::class)]
+class AttributeReaderTest extends TestCase {
+
+  public function testWithDecorator(): void {
+    $instantiator = new BasicAttributeInstantiator();
+    $reader = new AttributeReader($instantiator);
+    $reader = $reader->withDecoratingInstantiator(function ($decorated) use ($instantiator, &$decorating) {
+      Assert::assertSame($instantiator, $decorated);
+      $decorating = new ReflectorProvidingDecorator($decorated);
+      return $decorating;
+    });
+    $reader = $reader->withDecoratingInstantiator(function ($decorated) use ($decorating) {
+      Assert::assertSame($decorating, $decorated);
+      return $decorated;
+    });
+    $this->assertEquals(
+      new AttributeReader(
+        new ReflectorProvidingDecorator($instantiator),
+      ),
+      $reader,
+    );
+  }
+
+}