Add native PHP 8.4 property-hook field interception for class and trait proxies

[Copilot]

This change implements the PHP 8.4 property-hooks MVP for field interception in the trait-based engine. Intercepted properties are emitted as native hooked properties on generated proxies, while unsupported properties are intentionally excluded from advice matching.

• Proxy property interception moved to native hooks

  • Added InterceptedPropertyGenerator to generate intercepted properties with native hooks for class proxies.
  • ClassProxyGenerator re-declares intercepted properties on the proxy and routes access via ClassFieldAccess join points (prop:<name> keys).
  • Preserves visibility, final, type/default value, attributes, and asymmetric set visibility (protected(set) / private(set)).
  • Generated hook bodies include inline IDE typing for joinpoint access:
    • /** @var \Go\Aop\Intercept\FieldAccess<self,<type>> $fieldAccess */

• Trait property interception support

  • Added TraitInterceptedPropertyGenerator to generate native hooked properties for trait proxies.
  • TraitProxyGenerator now emits intercepted trait fields as hooked properties and initializes join points lazily per hook via TraitProxyGenerator::getJoinPoint(...).
  • Trait proxy property hooks support the same uninitialized typed-property safeguards and array &get-only behavior used for class proxies.
  • Trait-generated property hooks intentionally do not use class-style self::$__joinPoints[...] storage.

• Parent property interception support

  • Property matching includes inherited public/protected parent properties.
  • Inherited private properties remain excluded by reflection behavior.
  • final properties are skipped only when inherited from parent classes.
  • Added coverage for parent-property interception and explicit final-parent-property exclusion.
  • Added coverage that final properties declared in the current class are supported.

• Uninitialized typed property safeguard

  • For typed properties without a default value, generated get hooks guard with:
    • $fieldAccess->getField()->isInitialized($this)
  • Generated set hooks include the same initialization guard:
    • initialized path uses backed value (WRITE, $this->prop, $value)
    • uninitialized path uses fallback invocation without backed value (WRITE, $value)
  • Generated code returns invocation results directly (no extra temporary variable in get flow).
  • Runtime ClassFieldAccess handling supports both:
    • READ invocations without a backed value
    • WRITE invocations without a backed current value (for uninitialized typed properties)

• Array property special-case for indirect modification

  • For array-typed intercepted properties, generation uses &get only and intentionally omits set to preserve indirect modifications (for example array_push($this->items, ...)).
  • Union types that include array are handled as array-backed for this behavior.

• Reflection-first flow and validation boundaries

  • Property interception generation operates on ReflectionProperty only (no AST input in InterceptedPropertyGenerator / TraitInterceptedPropertyGenerator).
  • Suitability filtering is centralized in AdviceMatcher; proxy generators only enforce generator-specific wiring constraints.
  • Invalid interception attempts (static, readonly, already-hooked properties) are rejected explicitly.

• Woven trait property handling

  • WeavingTransformer comments out intercepted property declarations in woven bodies and appends relocation metadata:
    • // Moved by weaving interceptor to the {@see Class->property}
  • This behavior now applies to trait weaving as well, preventing trait/property composition conflicts when hooked properties are re-declared in proxies.
  • Uses token ranges and preserves debugger line mapping (including CRLF-safe newline handling).

• Field-access/runtime docs and cleanup

  • Updated FieldAccess/API docs and internal architecture notes to reflect native-hook interception and current limitations.
  • Added a dedicated README section documenting PHP 8.4 property interception behavior and constraints, including current-class vs inherited final handling.

• Test coverage updates

  • Added/updated tests for:
    • advice matching filter behavior (readonly + already-hooked excluded),
    • promoted constructor-property examples (normal, readonly, hooked),
    • parent public/protected property matching and final-parent-property exclusion,
    • current-class final-property interception support,
    • class proxy generation of hooked properties (including asymmetric visibility),
    • trait proxy generation of hooked properties and trait-specific joinpoint wiring,
    • uninitialized typed property guard generation in property get hooks,
    • uninitialized typed property guard generation in property set hooks,
    • runtime READ invocation handling without a backed property value,
    • runtime WRITE invocation handling without a backed current value,
    • array-property &get-only generation behavior,
    • functional indirect array modification behavior through intercepted properties,
    • weaving behavior that comments/moves intercepted declarations from class/trait source,
    • generated inline typed FieldAccess phpDoc in property hook bodies.

Example of generated class proxy property shape (non-array, potentially uninitialized typed property):

public protected(set) string $value {
    get {
        /** @var \Go\Aop\Intercept\FieldAccess<self,string> $fieldAccess */
        $fieldAccess = self::$__joinPoints['prop:value'];
        if ($fieldAccess->getField()->isInitialized($this)) {
            return $fieldAccess->__invoke($this, FieldAccessType::READ, $this->value);
        }
        return $fieldAccess->__invoke($this, FieldAccessType::READ);
    }
    set {
        /** @var \Go\Aop\Intercept\FieldAccess<self,string> $fieldAccess */
        $fieldAccess = self::$__joinPoints['prop:value'];
        if ($fieldAccess->getField()->isInitialized($this)) {
            $this->value = $fieldAccess->__invoke($this, FieldAccessType::WRITE, $value, $this->value);
        } else {
            $this->value = $fieldAccess->__invoke($this, FieldAccessType::WRITE, $value);
        }
    }
}

Example for array-backed property:

public array $items = [] {
    &get {
        /** @var \Go\Aop\Intercept\FieldAccess<self,array> $fieldAccess */
        $fieldAccess = self::$__joinPoints['prop:items'];
        return $fieldAccess->__invoke($this, FieldAccessType::READ, $this->items);
    }
}

[lisachenko]

@copilot please read and fix comments

[Copilot]

@copilot please read and fix comments

Done — I addressed the full review set in commits 715945e, 51e9f75, 4f5bfbe, and f1e60ff.

[lisachenko]

@copilot

1. I have enabled interception even of parent protected+public properties in AdviceMatcher. This should be documented (prepare small, but nice looking doc in README about property interception), also tests should be added. If parent class doesn't use readonly/static/final/hooks, then we can define the same property with the same modifiers in our woven class and add hooks to it according to the PHP documentation. Check test for final parent property - if missing, add it
2. If typed property doesn't have a default value - it will be uninitialized and all attempts to send such property by reference will fail with error. Please add a test for that and see this error first. If property doesn't have a default value, then generated code should contain a safeguard check $fieldAccess->getField()->isInitialized() and alternative version that will use just 2 arguments without reference (this can be later used also for virtual properties which not backed):

    private string $privateProperty {
        get {
            /** @var \Go\Aop\Intercept\FieldAccess<self,string> $fieldAccess */
            $fieldAccess = self::$__joinPoints['prop:privateProperty'];
            if ($fieldAccess->getField()->isInitialized()) {
                $value =& $fieldAccess->__invoke($this, \Go\Aop\Intercept\FieldAccessType::READ, $this->privateProperty);
                return $value;                
            } else {
                return $fieldAccess->__invoke($this, \Go\Aop\Intercept\FieldAccessType::READ);
            }
        }
    }

same logic needed for setters as well. If property has default value - then we can keep existing template.

3. extract result of $this->isArrayTypedProperty() inside \Go\Proxy\Part\InterceptedPropertyGenerator into variable to avoid 2 calculations.
4. Simplify code of getters to immediately return value (drop intermediate variable by-reference and return directly):

            return $fieldAccess->__invoke($this, \Go\Aop\Intercept\FieldAccessType::READ, $this->value);

5. property can be defined inside PHP traits too - ensure that interception of properties also works for trait fields. Add test cases for this
6. fix tests

[Copilot]

@copilot

1. I have enabled interception even of parent protected+public properties in AdviceMatcher. This should be documented (prepare small, but nice looking doc in README about property intercept...

Implemented in 9a1428c. Added README docs for PHP 8.4 property interception (including inherited public/protected behavior and unsupported cases), added tests for parent property interception and final-parent-property exclusion, and added uninitialized typed-property get-hook safeguard generation with isInitialized() + two-arg fallback path. Also updated runtime handling in ClassFieldAccess for READ invocation without a backed value. No UI changes.

[lisachenko]

@copilot fix review comments

[Copilot]

@copilot fix review comments

Done — I fixed the latest review comments in 866e30b and updated related tests/README accordingly. No UI changes.

[lisachenko]

@copilot

This still doesn't work for traits:

property can be defined inside PHP traits too - ensure that interception of properties also works for trait fields. Add test cases for this

[Copilot]

@copilot

1. I have enabled interception even of parent protected+public properties in AdviceMatcher. This should be documented (prepare small, but nice looking doc in README about property intercept...

Implemented in aab4b44 and finalized in ec3a21c: uninitialized typed-property handling is now added for generated set hooks with an isInitialized() guard and fallback WRITE invocation that avoids reading an uninitialized backed property. I also added/updated tests for generated set-hook branches and runtime WRITE fallback without a backed value.

[Copilot]

@copilot

This still doesn't work for traits:
...

Implemented in 796d244: trait-defined properties are now intercepted via native hooks in TraitProxyGenerator with lazy per-hook joinpoint initialization, and trait weaving now comments out moved intercepted trait properties to avoid hook/property composition conflicts. I also added trait-focused test coverage in TraitProxyGeneratorTest for READ/WRITE hook generation.

[lisachenko]

@copilot fix broken tests after my recent changes.

Also, try to extract similar boilerplate code from InterceptedPropertyGenerator + TraitInterceptedPropertyGenerator either into common abstract parent class or into separate helper class.

[Copilot]

@copilot fix broken tests after my recent changes.

Also, try to extract similar boilerplate code from InterceptedPropertyGenerator + TraitInterceptedPropertyGenerator either into common abstract pa...

Fixed in 058c991: repaired the broken PHPUnit cases after recent changes (including ClassFieldAccess uninitialized-read fallback and updated generator expectations), and extracted shared class/trait property-hook boilerplate into AbstractInterceptedPropertyGenerator used by both InterceptedPropertyGenerator and TraitInterceptedPropertyGenerator.

[lisachenko]

@copilot everything looks good, the only small remaining thing - if property uses a PHP class type, then typehint may be incorrect, check this:

    private \Exception $privateProperty;

becomes

    private \Exception $privateProperty {
        get {
            /** @var \Go\Aop\Intercept\FieldAccess<self, Exception> $fieldAccess */
            $fieldAccess = self::$__joinPoints['prop:privateProperty'];
            if ($fieldAccess->getField()->isInitialized($this)) {
                return $fieldAccess->__invoke($this, \Go\Aop\Intercept\FieldAccessType::READ, $this->privateProperty);
            } else {
                return $fieldAccess->__invoke($this, \Go\Aop\Intercept\FieldAccessType::READ);
            }
        }
        set {
            /** @var \Go\Aop\Intercept\FieldAccess<self, Exception> $fieldAccess */
            $fieldAccess = self::$__joinPoints['prop:privateProperty'];
            if ($fieldAccess->getField()->isInitialized($this)) {
                $this->privateProperty = $fieldAccess->__invoke($this, \Go\Aop\Intercept\FieldAccessType::WRITE, $value, $this->privateProperty);
            } else {
                $this->privateProperty = $fieldAccess->__invoke($this, \Go\Aop\Intercept\FieldAccessType::WRITE, $value);
            }
        }

and typehint is incorrect:

/** @var \Go\Aop\Intercept\FieldAccess<self, Exception> $fieldAccess */

it should have FQDN too: \Exception. But ensure that you don't add "" for simple types like "string", etc

[Copilot]

@copilot everything looks good, the only small remaining thing - if property uses a PHP class type, then typehint may be incorrect, check this:

    private \Exception $privateProperty;

...

Fixed in 2a4bb7b: class-typed property generics in generated hook phpDoc now use fully-qualified names (for example FieldAccess<self, \Exception>), and I added class + trait generator tests to cover this case. No UI changes in this PR (codegen/runtime only).