Merge pull request #530 from goaop/feature/enum-interception-support

Feature: Add Enum interception support

Author: lisachenko

CHANGELOG.md

@@ -4,6 +4,7 @@ Changelog
 * [BC BREAK] Requires PHP 8.4+
 * [BC BREAK] Proxy engine switched from inheritance-based to **trait-based**: the original class body is converted to a PHP trait (`Foo__AopProxied`) and the proxy class uses it via `use` with private method aliases instead of extending the renamed class. This removes the `__AopProxied` parent from the inheritance chain.
 * [Feature] **Private method interception** — both dynamic (`private function foo()`) and static (`private static function bar()`) private methods can now be intercepted by aspects. This was impossible with the old extend-based engine because PHP does not allow overriding private methods in subclasses.
+* [Feature] **PHP 8.1+ enum interception** — instance and static methods on both unit (pure) and backed enums can now be intercepted by aspects. The enum body is extracted into a trait (`Foo__AopProxied`); a proxy enum re-declares the cases and dispatches intercepted methods via per-method `static $__joinPoint` caching. Built-in enum methods (`cases`, `from`, `tryFrom`) and initialization joinpoints are never woven.
 * [Feature] `self::` in proxied classes now resolves to the proxy class naturally (via PHP trait semantics), removing the need for `SelfValueTransformer`.
 * [Removed] `SelfValueTransformer` and `SelfValueVisitor` — no longer needed with the trait-based engine.
 * [Performance] Pre-bound `Closure::bind` closures replace per-call `ReflectionMethod::getClosure()` + rebind in the method invocation proceed path, eliminating reflection overhead on every intercepted call.

CLAUDE.md

@@ -136,9 +136,14 @@ Key properties of this engine:
 
 The framework supports PHP 8.4+ and handles most modern PHP syntax transparently. The following constructs have documented limitations or are intentionally excluded:
 
-### Enums (PHP 8.1+) — not woven
+### Enums (PHP 8.1+) — woven via trait extraction
 
-Enums are **silently skipped** by `WeavingTransformer`. They cannot be converted to traits (PHP does not allow traits to become enums), and they cannot be extended. Aspects targeting enum methods will have no effect.
+Enums are supported by `WeavingTransformer` using the same trait-extraction approach as classes, with adjustments for enum constraints:
+- The original enum body is converted to a **trait** (cases stripped, backed type removed, `enum` → `trait`)
+- A proxy **enum** is generated that re-uses the trait, re-declares all cases, and adds per-method `static $__joinPoint` dispatch — using `EnumProxyGenerator`
+- Enums **cannot** have properties (static or instance), so the `$__joinPoints` class property pattern used by `ClassProxyGenerator` does not apply; per-method static variables are used instead (same as `TraitProxyGenerator`)
+- Built-in enum methods (`cases`, `from`, `tryFrom`) are **never** intercepted — they are synthesised by PHP and cannot be aliased via trait use
+- Built-in PHP enum interfaces (`UnitEnum`, `BackedEnum`) are **never** listed in the proxy's `implements` clause — PHP applies them automatically, and listing them explicitly in a namespaced file resolves them as `Ns\UnitEnum` instead of the global `\UnitEnum`, causing a fatal error
 
 ### Readonly classes (PHP 8.2+) — proxy is not readonly
 
@@ -152,6 +157,16 @@ When a method marked `#[\Override]` is intercepted (i.e., aliased as `__aop__met
 
 Property hooks are included verbatim in the generated trait body; they are not a separate join-point type. You can intercept the owning method (if any) but you cannot write a pointcut that targets a hook `get`/`set` clause directly. `ClassFieldAccess` property interception and hooked properties on the same property are not supported simultaneously.
 
+### Woven trait file line numbers must match the original source (XDebug compatibility)
+
+The **woven file** (the trait that replaces the original class/enum body) **must** preserve the original source line numbers. This is required for XDebug breakpoints to map correctly: a breakpoint placed at a method in the original source file must land on the same line number in the woven trait file, because that is the file XDebug steps through when executing the real method body.
+
+`WeavingTransformer` achieves this via token-level surgery on the original source:
+- For classes: `convertClassToTrait()` replaces the `class` keyword and strips modifiers/extends/implements, but keeps all other tokens (including blank lines) in place.
+- For enums: `convertEnumToTrait()` must **replace removed tokens** (case declarations, backed type, implements clause) with an **equal number of newlines** so that methods remain at their original line positions. Removing tokens without replacement shifts subsequent lines upward.
+
+The proxy file (generated by `ClassProxyGenerator`/`EnumProxyGenerator`) is a thin dispatch wrapper and does **not** need to match original line numbers. Debuggers will step through the woven trait for the real method bodies.
+
 ### Aspects themselves — never woven
 
 Classes that implement `\Go\Aop\Aspect` are unconditionally skipped by `WeavingTransformer`. Aspects cannot weave themselves.

README.md

@@ -34,6 +34,7 @@ The framework provides powerful core interception capabilities that can be used
 | Interception of private methods            |    ✅    |
 | Interception of methods in `final` classes |    ✅    |
 | Interception of trait methods              |    ✅    |
+| Interception of enum methods (PHP 8.1+)    |    ✅    |
 | Before, After and Around type of hooks     |    ✅    |
 
 ### 🛠️ Developer Experience

src/Instrument/Transformer/WeavingTransformer.php

@@ -27,8 +27,10 @@
 use Go\ParserReflection\ReflectionFileNamespace;
 use Go\ParserReflection\ReflectionMethod;
 use Go\Proxy\ClassProxyGenerator;
+use Go\Proxy\EnumProxyGenerator;
 use Go\Proxy\FunctionProxyGenerator;
 use Go\Proxy\TraitProxyGenerator;
+use PhpParser\Node\Stmt\EnumCase;
 
 /**
  * Main transformer that performs weaving of aspects into the source code
@@ -95,8 +97,8 @@ public function transform(StreamMetaData $metadata): TransformerResultEnum
         foreach ($namespaces as $namespace) {
             $classes = $namespace->getClasses();
             foreach ($classes as $class) {
-                // Skip interfaces, enums, and aspects — these cannot be proxied as traits
-                if ($class->isInterface() || $class->isEnum() || in_array(Aspect::class, $class->getInterfaceNames(), true)) {
+                // Skip interfaces and aspects — enums are now supported via EnumProxyGenerator
+                if ($class->isInterface() || in_array(Aspect::class, $class->getInterfaceNames(), true)) {
                     continue;
                 }
                 $wasClassProcessed = $this->processSingleClass(
@@ -146,10 +148,14 @@ private function processSingleClass(
         $newFqcn      = ($class->getNamespaceName() !== '' ? $class->getNamespaceName() . '\\' : '') . $newClassName;
 
         // For traits: rename the trait (legacy approach, TraitProxyGenerator generates a child trait).
+        // For enums: convert the enum body to a trait (cases extracted to proxy enum by EnumProxyGenerator).
         // For classes: convert the class body to a trait (new trait-based engine).
         if ($class->isTrait()) {
             $this->adjustOriginalClass($class, $advices, $metadata, $newClassName);
             $childProxyGenerator = new TraitProxyGenerator($class, $newFqcn, $advices, $this->useParameterWidening);
+        } elseif ($class->isEnum()) {
+            $this->convertEnumToTrait($class, $advices, $metadata, $newClassName);
+            $childProxyGenerator = new EnumProxyGenerator($class, $newFqcn, $advices, $this->useParameterWidening);
         } else {
             $this->convertClassToTrait($class, $advices, $metadata, $newClassName);
             $childProxyGenerator = new ClassProxyGenerator($class, $newFqcn, $advices, $this->useParameterWidening);
@@ -372,6 +378,127 @@ private function convertClassToTrait(
         $this->stripOverrideAttributeFromInterceptedMethods($class, $advices, $streamMetaData);
     }
 
+    /**
+     * Convert an enum declaration into a trait for the trait-based AOP engine.
+     *
+     * Performs the following token-stream modifications in-place:
+     *  - Changes 'enum' keyword text to 'trait'
+     *  - Renames the enum to $newClassName (__AopProxied suffix)
+     *  - Removes the backed type (': string' / ': int') and any 'implements ...' clause
+     *  - Removes all enum case declarations from the body (cases live in the proxy enum instead)
+     *
+     * @param array<string, array<string, array<string>>> $advices List of class advices (sorted advice IDs)
+     */
+    private function convertEnumToTrait(
+        ReflectionClass $class,
+        array $advices,
+        StreamMetaData $streamMetaData,
+        string $newClassName
+    ): void {
+        $classNode = $class->getNode();
+        if ($classNode === null) {
+            return;
+        }
+        $position = $classNode->getAttribute('startTokenPos');
+        if (!is_int($position)) {
+            return;
+        }
+
+        $classNameFound = false;
+
+        do {
+            if (!isset($streamMetaData->tokenStream[$position])) {
+                ++$position;
+                continue;
+            }
+
+            $token = $streamMetaData->tokenStream[$position];
+
+            if (!$classNameFound) {
+                // Rewrite 'enum' keyword to 'trait'
+                if ($token->id === T_ENUM) {
+                    $streamMetaData->tokenStream[$position]->text = 'trait';
+                    ++$position;
+                    continue;
+                }
+                // First T_STRING after the keyword is the enum name — rename it
+                if ($token->id === T_STRING) {
+                    $streamMetaData->tokenStream[$position]->text = $newClassName;
+                    $classNameFound = true;
+                    ++$position;
+                    continue;
+                }
+            } else {
+                // After the enum name: strip backed type (': string/int') and 'implements ...' up to '{'
+                if ($token->text === '{') {
+                    break;
+                }
+                // Keep whitespace tokens to preserve original brace placement
+                if ($token->id !== T_WHITESPACE) {
+                    unset($streamMetaData->tokenStream[$position]);
+                }
+            }
+
+            ++$position;
+        } while (true);
+
+        // Remove all enum case declarations from the trait body.
+        // Cases cannot exist in traits; they are re-declared in the proxy enum by EnumProxyGenerator.
+        // The trailing whitespace token (newline + indent) after each case is intentionally kept so
+        // that subsequent methods remain at their original line numbers in the woven file, which is
+        // required for XDebug breakpoints to map correctly (see CLAUDE.md).
+        foreach ($classNode->stmts as $stmt) {
+            if (!($stmt instanceof EnumCase)) {
+                continue;
+            }
+            $start = $stmt->getAttribute('startTokenPos');
+            $end   = $stmt->getAttribute('endTokenPos');
+            if (!is_int($start) || !is_int($end)) {
+                continue;
+            }
+            // Remove the case tokens only (not the trailing whitespace/newline).
+            // Keeping the trailing whitespace preserves blank lines in place of the removed case,
+            // so the line numbers of all following methods are unchanged.
+            for ($pos = $start; $pos <= $end; $pos++) {
+                unset($streamMetaData->tokenStream[$pos]);
+            }
+        }
+
+        // Remove 'final' from all intercepted enum methods — final methods cannot be overridden in
+        // the proxy enum. Only intercepted methods need stripping; unintercepted final methods are
+        // not overridden by the proxy and can safely remain final in the trait.
+        foreach ($class->getMethods(ReflectionMethod::IS_FINAL) as $finalMethod) {
+            if ($finalMethod->getDeclaringClass()->name !== $class->name) {
+                continue;
+            }
+            $hasDynamicAdvice = isset($advices[AspectContainer::METHOD_PREFIX][$finalMethod->name]);
+            $hasStaticAdvice  = isset($advices[AspectContainer::STATIC_METHOD_PREFIX][$finalMethod->name]);
+            if (!$hasDynamicAdvice && !$hasStaticAdvice) {
+                continue;
+            }
+            $methodNode = $finalMethod->getNode();
+            $position   = $methodNode->getAttribute('startTokenPos');
+            if (!is_int($position)) {
+                continue;
+            }
+            do {
+                if (isset($streamMetaData->tokenStream[$position])) {
+                    $token = $streamMetaData->tokenStream[$position];
+                    if ($token->id === T_FINAL) {
+                        unset($streamMetaData->tokenStream[$position], $streamMetaData->tokenStream[$position + 1]);
+                        break;
+                    }
+                }
+                ++$position;
+            } while (true);
+        }
+
+        // Strip #[\Override] from intercepted methods to prevent fatal errors on the alias.
+        // PHP copies attributes to alias names (e.g. __aop__label), and since __aop__label has
+        // no matching parent method, #[\Override] on the alias would be a fatal error.
+        $this->stripOverrideAttributeFromInterceptedMethods($class, $advices, $streamMetaData);
+    }
+
     /**
      * Removes #[\Override] attribute groups from all intercepted methods in the token stream.
      *