feat(interceptors): Add InterceptorOptions with order and ConflictPolicy

Author: roxblnfk

src/Module/Interceptor/InterceptorOptions.php

@@ -0,0 +1,27 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Testo\Module\Interceptor;
+
+use Testo\Module\Interceptor\Policy\ConflictPolicy;
+
+/**
+ * Interceptor options.
+ */
+#[\Attribute(\Attribute::TARGET_CLASS)]
+final class InterceptorOptions
+{
+    const DEFAULT_ORDER = 0;
+
+    public function __construct(
+        /**
+         * The priority of the interceptor.
+         *
+         * Lower priority interceptors are applied first in the interceptor chain.
+         * Higher priority interceptors are closer to the test function in the interceptor chain.
+         */
+        public readonly int $order = self::DEFAULT_ORDER,
+        public readonly ConflictPolicy $onConflict = ConflictPolicy::Merge,
+    ) {}
+}

src/Module/Interceptor/InterceptorProvider.php

@@ -15,6 +15,7 @@
 use Testo\Interceptor\Reflection\Reflection;
 use Testo\Interceptor\TestCaseCallInterceptor\InstantiateTestCase;
 use Testo\Module\Interceptor\Internal\InterceptorMarker;
+use Testo\Module\Interceptor\Internal\Sorter;
 use Testo\Sample\Internal\TestInlineFinder;
 use Yiisoft\Injector\Injector;
 
@@ -89,7 +90,7 @@ public function fromClasses(string $class, string|InterceptorMarker ...$intercep
 
             $interceptor instanceof $class and $result[] = $interceptor;
         }
-        return $result;
+        return Sorter::sortAndFilter($result);
     }
 
     /**
@@ -115,7 +116,7 @@ public function fromAttributes(string $class, Interceptable ...$attributes): arr
             \is_a($iClass, $class, true) and $result[] = $this->createInstance($iClass, [$attribute]);
         }
 
-        return $result;
+        return Sorter::sortAndFilter($result);
     }
 
     /**

src/Module/Interceptor/Internal/Sorter.php

@@ -0,0 +1,110 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Testo\Module\Interceptor\Internal;
+
+use Testo\Interceptor\Reflection\Reflection;
+use Testo\Module\Interceptor\InterceptorOptions;
+use Testo\Module\Interceptor\Internal\InterceptorMarker as TInterceptor;
+use Testo\Module\Interceptor\Policy\ConflictPolicy;
+
+/**
+ * Sorts and filters interceptors.
+ * @internal
+ */
+final class Sorter
+{
+    /** @var array<class-string<TInterceptor>, ConflictPolicy> */
+    private static array $conflictPolicyCache = [];
+
+    /** @var array<class-string<TInterceptor>, int> */
+    private static array $orderCache = [];
+
+    /**
+     * Sort and filter interceptors.
+     *
+     * @param TInterceptor[] $interceptors
+     *
+     * @return TInterceptor[]
+     */
+    public static function sortAndFilter(array $interceptors): array
+    {
+        # Local caches
+        $conflicts = [];
+        $orders = [];
+
+        /** @var array<int, array<class-string<TInterceptor>|int, TInterceptor>>  $groups */
+        $groups = [];
+        foreach ($interceptors as $interceptor) {
+            $class = $interceptor::class;
+            $conflict = $conflicts[$class] ??= self::getConflictPolicy($interceptor);
+            $order = $orders[$class] ??= self::getOrder($interceptor);
+
+            switch ($conflict) {
+                case ConflictPolicy::First:
+                    $groups[$order][$class] ??= $interceptor;
+                    break;
+                case ConflictPolicy::Last:
+                    unset($groups[$order][$class]);
+                    $groups[$order][$class] = $interceptor;
+                    break;
+                case ConflictPolicy::Error:
+                    \array_key_exists($class, $groups[$order])
+                        ? throw new \RuntimeException("Conflict detected for interceptor '$class' with policy 'Error'.")
+                        : $groups[$order][$class] = $interceptor;
+                    break;
+                default:
+                    $groups[$order][] = $interceptor;
+                    break;
+            }
+        }
+
+        \ksort($groups);
+        return \array_values(\array_merge(...$groups));
+    }
+
+    /**
+     * Warm up the cache for the given interceptor class.
+     *
+     * @param class-string<TInterceptor> $class
+     */
+    private static function warmUpCache(string $class): void
+    {
+        /** @var list<\ReflectionAttribute<InterceptorOptions>> $attributes */
+        $attributes = Reflection::fetchClassAttributes(
+            $class,
+            attributeClass: InterceptorOptions::class,
+        );
+
+        if ($attributes === []) {
+            self::$conflictPolicyCache[$class] = ConflictPolicy::default();
+            self::$orderCache[$class] = InterceptorOptions::DEFAULT_ORDER;
+            return;
+        }
+
+        $attribute = $attributes[0]->newInstance();
+        self::$conflictPolicyCache[$class] = $attribute->onConflict;
+        self::$orderCache[$class] = $attribute->order;
+    }
+
+    /**
+     * Get the conflict policy of the given interceptor by its attribute.
+     */
+    private static function getConflictPolicy(TInterceptor $interceptor): ConflictPolicy
+    {
+        $class = $interceptor::class;
+        \array_key_exists($class, self::$conflictPolicyCache) or self::warmUpCache($class);
+        return self::$conflictPolicyCache[$class];
+    }
+
+    /**
+     * Get the order of the given interceptor by its attribute.
+     */
+    private static function getOrder(TInterceptor $interceptor): int
+    {
+        $class = $interceptor::class;
+        \array_key_exists($class, self::$orderCache) or self::warmUpCache($class);
+        return self::$orderCache[$class];
+    }
+}

src/Module/Interceptor/Policy/ConflictPolicy.php

@@ -0,0 +1,39 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Testo\Module\Interceptor\Policy;
+
+/**
+ * Merge policy for interceptors.
+ *
+ * Determines how to handle multiple interceptors of the same type.
+ */
+enum ConflictPolicy
+{
+    /**
+     * Use the first interceptor.
+     * Default behavior.
+     */
+    case First;
+
+    /**
+     * Do nothing: all the interceptors will be applied.
+     */
+    case Merge;
+
+    /**
+     * Use the last interceptor.
+     */
+    case Last;
+
+    /**
+     * Break the pipeline with an error.
+     */
+    case Error;
+
+    public static function default(): self
+    {
+        return self::First;
+    }
+}

src/Sample/Internal/InlineTestInvoker.php

@@ -4,7 +4,11 @@
 
 namespace Testo\Sample\Internal;
 
-use Testo\Assert;use Testo\Sample\TestInline;use Testo\Test\Dto\TestInfo;class InlineTestInvoker
+use Testo\Assert;
+use Testo\Sample\TestInline;
+use Testo\Test\Dto\TestInfo;
+
+class InlineTestInvoker
 {
     public function __construct() {}
 

src/Sample/Internal/TestInlineInterceptor.php

@@ -5,16 +5,11 @@
 namespace Testo\Sample\Internal;
 
 use Psr\EventDispatcher\EventDispatcherInterface;
-use Testo\Attribute\Test;
-use Testo\Interceptor\CaseLocatorInterceptor;
-use Testo\Interceptor\FileLocatorInterceptor;
-use Testo\Interceptor\Reflection\Reflection;
 use Testo\Interceptor\TestRunInterceptor;
-use Testo\Module\Tokenizer\Reflection\FileDefinitions;
-use Testo\Module\Tokenizer\Reflection\TokenizedFile;
+use Testo\Module\Interceptor\InterceptorOptions;
+use Testo\Module\Interceptor\Policy\ConflictPolicy;
 use Testo\Sample\MultipleResult;
 use Testo\Sample\TestInline;
-use Testo\Test\Dto\CaseDefinitions;
 use Testo\Test\Dto\Status;
 use Testo\Test\Dto\TestInfo;
 use Testo\Test\Dto\TestResult;
@@ -26,16 +21,12 @@
 /**
  * Interceptor that runs the target method as a pure function with provided arguments and expected result.
  */
+#[InterceptorOptions(onConflict: ConflictPolicy::First)]
 final class TestInlineInterceptor implements TestRunInterceptor
 {
-    /** @var callable(TestInfo): mixed Invoker for the test method. */
-    private readonly \CLosure $invoker;
-
     public function __construct(
         private readonly EventDispatcherInterface $eventDispatcher,
-    ) {
-        $this->invoker = (new InlineTestInvoker())(...);
-    }
+    ) {}
 
     #[\Override]
     public function runTest(TestInfo $info, callable $next): TestResult
@@ -54,16 +45,16 @@ public function runTest(TestInfo $info, callable $next): TestResult
         # Dispatch batch starting event
         $this->eventDispatcher->dispatch(new TestBatchStarting($info));
 
-        // Run the test for each data set
+        # Run the test for each data set
         $results = [];
         $status = Status::Passed;
         foreach ($attributes as $index => $inline) {
-            $newInfo = $info->with(arguments: $inline->arguments);
+            $newInfo = $info->with(arguments: $inline->arguments)->withAttribute(TestInline::class, $inline);
             $label = "$index";
 
             # Dispatch dataset starting event
             $this->eventDispatcher->dispatch(
-                new TestDataSetStarting($newInfo, $label, $index)
+                new TestDataSetStarting($newInfo, $label, $index),
             );
 
             try {
@@ -74,7 +65,7 @@ public function runTest(TestInfo $info, callable $next): TestResult
 
             # Dispatch dataset finished event
             $this->eventDispatcher->dispatch(
-                new TestDataSetFinished($newInfo, $result, $label, $index)
+                new TestDataSetFinished($newInfo, $result, $label, $index),
             );
 
             unset($inline, $newInfo);

testo.php

@@ -16,5 +16,6 @@
             ),
         ],
         require 'tests/Assert/suites.php',
+        require 'tests/Sample/suites.php',
     ),
 );

tests/Sample/Self/TestInline.php

@@ -4,8 +4,6 @@
 
 namespace Tests\Sample\Self;
 
-use Testo\Assert;
-use Testo\Attribute\ExpectException;
 use Testo\Attribute\Test;
 use Testo\Expect;
 
@@ -14,6 +12,7 @@
  */
 final class TestInline
 {
+    #[\Testo\Sample\TestInline(arguments: [1, 1], result: 2)]
     #[\Testo\Sample\TestInline(arguments: [40, 2], result: 42)]
     public function sum(int $a, int $b): int
     {