Add filterTargetClasses and filterTargetMethods (#12)

Author: olvlvl

MIGRATION.md

@@ -1,5 +1,31 @@
 # Migration
 
+## v1.1 to v1.2
+
+### New Requirements
+
+None
+
+### New features
+
+- [#11](https://github.com/olvlvl/composer-attribute-collector/pull/11) Attribute instantiation errors are decorated to help find origin (@withinboredom @olvlvl)
+- [#12](https://github.com/olvlvl/composer-attribute-collector/pull/12) `Attributes::filterTargetClasses()` can filter target classes using a predicate (@olvlvl)
+- [#12](https://github.com/olvlvl/composer-attribute-collector/pull/12) `Attributes::filterTargetMethods()` can filter target methods using a predicate (@olvlvl)
+
+### Backward Incompatible Changes
+
+None
+
+### Deprecated Features
+
+None
+
+### Other Changes
+
+None
+
+
+
 ## v1.0 to v1.1
 
 ### New Requirements

README.md

@@ -39,15 +39,22 @@ require_once 'vendor/attributes.php'; // <-- the file created by the plugin
 foreach (Attributes::findTargetClasses(AsMessageHandler::class) as $target) {
     // $target->attribute is an instance of the specified attribute
     // with the actual data.
-    var_dump($target->name, $target->attribute);
+    var_dump($target->attribute, $target->name);
 }
 
 // Find the target methods of the Route attribute.
 foreach (Attributes::findTargetMethods(Route::class) as $target) {
-    var_dump($target->class, $target->name, $target->attribute);
+    var_dump($target->attribute, $target->class, $target->name);
 }
 
-// Find attributes for the ArticleController class.
+// Filter target methods using a predicate.
+foreach (Attributes::filterTargetMethods(
+    fn($attribute) => is_a($attribute, Route::class, true)
+) as $target) {
+    var_dump($target->attribute, $target->class, $target->name);
+}
+
+// Find class and method attributes for the ArticleController class.
 $attributes = Attributes::forClass(ArticleController::class);
 
 var_dump($attributes->classAttributes);
@@ -289,6 +296,41 @@ final class IsAdmin implements Voter
 }
 ```
 
+## Using Attributes
+
+### Filtering target methods
+
+`filterTargetMethods()` can filter target methods using a predicate. This can be helpful when a number of attributes extend another one, and you are interested in collecting any instance of that attribute.
+
+Let's say we have a `Route` attribute extended by `Get`, `Post`, `Put`…
+
+```php
+<?php
+
+use olvlvl\ComposerAttributeCollector\Attributes;
+
+/** @var TargetMethod<Route>[] $target_methods */
+$target_methods = [
+    ...Attributes::findTargetMethods(Get::class),
+    ...Attributes::findTargetMethods(Head::class),
+    ...Attributes::findTargetMethods(Post::class),
+    ...Attributes::findTargetMethods(Put::class),
+    ...Attributes::findTargetMethods(Delete::class),
+    ...Attributes::findTargetMethods(Connect::class),
+    ...Attributes::findTargetMethods(Options::class),
+    ...Attributes::findTargetMethods(Trace::class),
+    ...Attributes::findTargetMethods(Patch::class),
+    ...Attributes::findTargetMethods(Route::class),
+];
+
+// Can be replaced by:
+
+/** @var TargetMethod<Route>[] $target_methods */
+$target_methods = Attributes::filterTargetMethods(
+    fn($attribute) => is_a($attribute, Route::class, true)
+);
+```
+
 
 
 ----------

composer.json

@@ -20,7 +20,10 @@
         "psr-4": {
             "tests\\olvlvl\\ComposerAttributeCollector\\": "tests",
             "Acme\\": "tests/Acme"
-        }
+        },
+        "classmap": [
+            "tests/Acme/ClassMap"
+        ]
     },
     "config": {
         "sort-packages": true

src/Attributes.php

@@ -54,6 +54,26 @@ public static function findTargetMethods(string $attribute): array
         return self::getCollection()->findTargetMethods($attribute);
     }
 
+    /**
+     * @param callable(class-string $attribute, class-string $class):bool $predicate
+     *
+     * @return array<TargetClass<object>>
+     */
+    public static function filterTargetClasses(callable $predicate): array
+    {
+        return self::getCollection()->filterTargetClasses($predicate);
+    }
+
+    /**
+     * @param callable(class-string $attribute, class-string $class, string $method):bool $predicate
+     *
+     * @return array<TargetMethod<object>>
+     */
+    public static function filterTargetMethods(callable $predicate): array
+    {
+        return self::getCollection()->filterTargetMethods($predicate);
+    }
+
     /**
      * @var array<class-string, ForClass>
      */

src/Collection.php

@@ -38,7 +38,7 @@ public function __construct(
      *
      * @param class-string<T> $attribute
      *
-     * @return TargetClass<T>[]
+     * @return array<TargetClass<T>>
      */
     public function findTargetClasses(string $attribute): array
     {
@@ -74,7 +74,7 @@ private static function createClassAttribute(string $attribute, array $arguments
      *
      * @param class-string<T> $attribute
      *
-     * @return TargetMethod<T>[]
+     * @return array<TargetMethod<T>>
      */
     public function findTargetMethods(string $attribute): array
     {
@@ -84,6 +84,51 @@ public function findTargetMethods(string $attribute): array
         );
     }
 
+    /**
+     * @param callable(class-string $attribute, class-string $class):bool $predicate
+     *
+     * @return array<TargetClass<object>>
+     */
+    public function filterTargetClasses(callable $predicate): array
+    {
+        $ar = [];
+
+        foreach ($this->targetClasses as $attribute => $references) {
+            foreach ($references as [ $arguments, $class ]) {
+                if ($predicate($attribute, $class)) {
+                    $ar[] = new TargetClass(self::createClassAttribute($attribute, $arguments, $class), $class);
+                }
+            }
+        }
+
+        return $ar;
+    }
+
+    /**
+     * @param callable(class-string $attribute, class-string $class, string $method):bool $predicate
+     *
+     * @return array<TargetMethod<object>>
+     */
+    public function filterTargetMethods(callable $predicate): array
+    {
+        $ar = [];
+
+        foreach ($this->targetMethods as $attribute => $references) {
+            foreach ($references as [ $arguments, $class, $method ]) {
+                if ($predicate($attribute, $class, $method)) {
+                    $ar[] = new TargetMethod(self::createMethodAttribute(
+                        $attribute,
+                        $arguments,
+                        $class,
+                        $method
+                    ), $class, $method);
+                }
+            }
+        }
+
+        return $ar;
+    }
+
     /**
      * @template T of object
      *
@@ -111,38 +156,19 @@ private static function createMethodAttribute(
 
     /**
      * @param class-string $class
-     *
-     * @return ForClass
      */
     public function forClass(string $class): ForClass
     {
         $classAttributes = [];
 
-        foreach ($this->targetClasses as $attribute => $references) {
-            foreach ($references as [ $arguments, $targetClass ]) {
-                if ($targetClass != $class) {
-                    continue;
-                }
-
-                $classAttributes[] = self::createClassAttribute($attribute, $arguments, $class);
-            }
+        foreach ($this->filterTargetClasses(fn($a, $c): bool => $c === $class) as $targetClass) {
+            $classAttributes[] = $targetClass->attribute;
         }
 
         $methodAttributes = [];
 
-        foreach ($this->targetMethods as $attribute => $references) {
-            foreach ($references as [ $arguments, $targetClass, $targetMethod ]) {
-                if ($targetClass != $class) {
-                    continue;
-                }
-
-                $methodAttributes[$targetMethod][] = self::createMethodAttribute(
-                    $attribute,
-                    $arguments,
-                    $class,
-                    $targetMethod
-                );
-            }
+        foreach ($this->filterTargetMethods(fn($a, $c): bool => $c === $class) as $targetMethod) {
+            $methodAttributes[$targetMethod->name][] = $targetMethod->attribute;
         }
 
         return new ForClass($classAttributes, $methodAttributes);

tests/Acme/Attribute/Get.php

@@ -0,0 +1,16 @@
+<?php
+
+namespace Acme\Attribute;
+
+use Attribute;
+
+#[Attribute(Attribute::TARGET_METHOD)]
+class Get extends Route
+{
+    public function __construct(
+        string $pattern = '',
+        ?string $id = null
+    ) {
+        parent::__construct($pattern, 'GET', $id);
+    }
+}

tests/Acme/Attribute/Post.php

@@ -0,0 +1,16 @@
+<?php
+
+namespace Acme\Attribute;
+
+use Attribute;
+
+#[Attribute(Attribute::TARGET_METHOD)]
+class Post extends Route
+{
+    public function __construct(
+        string $pattern = '',
+        ?string $id = null
+    ) {
+        parent::__construct($pattern, 'POST', $id);
+    }
+}

tests/Acme/Attribute/Route.php

@@ -11,8 +11,8 @@
 
 use Attribute;
 
-#[Attribute(Attribute::TARGET_METHOD)]
-final class Route
+#[Attribute(Attribute::TARGET_CLASS | Attribute::TARGET_METHOD)]
+class Route
 {
     /**
      * @param string|string[] $method

tests/Acme/ClassMap/controllers.php

@@ -9,29 +9,32 @@
 
 namespace Acme\Presentation;
 
+use Acme\Attribute\Get;
 use Acme\Attribute\Route;
 
+#[Route('/images')]
 final class ImageController
 {
-    #[Route("/images")]
+    #[Get]
     protected function list(): void
     {
     }
 
-    #[Route("/images/{id}")]
+    #[Get("/{id}")]
     private function show(int $id): void
     {
     }
 }
 
+#[Route('/files')]
 final class FileController
 {
-    #[Route("/files")]
+    #[Get]
     public function list(): void
     {
     }
 
-    #[Route("/files/{id}")]
+    #[Get('/{id}')]
     public function show(int $id): void
     {
     }