feat(reflection): preserve the previous body of redefine() under an alias and accept method donors

[lisachenko]

What this changes

Runtime method weaving needs two things from the engine that redefine() did not offer: swapping a method body for one compiled elsewhere while the original body stays callable, and overriding an inherited method in a class that does not declare it. This PR adds both on the existing redefine() surface instead of a new interceptMethod() API.

• redefine(\Closure|FunctionLikeInterface $newBody, ?string $preserveAs = null): a user method of another class (the donor) is adopted as the new body in place, exactly like a closure body. The entry keeps its identity (name, scope, prototype, visibility, static/final flags) while the compiled body, signature, attributes and doc comment follow the donor. The donor's signature must be compatible with the entry's one (self/parent resolved against each side's own scope).
• preserveAs: the previous body is published before the swap as a private method of the declaring class (marked ZEND_ACC_CHANGED when an ancestor declares a private method of that name, shared into every subclass linked before, taking over the live static variables of the body it preserves) or, for a function, as a second global function. It stays callable and can be swapped back in with a later redefine().
• ReflectionClass::addMethod() accepts a method donor too and publishes an override of an inherited method with the engine's inheritance rules: prototype kept, no override of a final method, no visibility narrowing, same static-ness, parent-private redeclaration marked CHANGED (and the bit propagated from a CHANGED inherited method). The magic slots of the class and the method tables of subclasses linked before follow the override.
• FunctionBodySwap allocates the fresh run-time cache of a swapped or published entry from request memory without ZEND_ACC_HEAP_RT_CACHE and releases it on the next swap of the entry, after detaching the engine copies that still point at it (see below). A heap-flagged cache shared by a parent and a subclass method table was efree()d once per table at a destructor-path shutdown (USE_ZEND_ALLOC=0), once for every subclass linked after a swap.
• New RedefinitionException (named factories) and SharedMemoryException::sharedEntryHasLinkedSubclasses(): a class whose entry lives in opcache shared memory and already has linked subclasses is refused, since the subclass tables point at the shared entry.
• docs/hot-swap.md documents method donors, preserveAs, the addMethod() override, the run-time cache rule, the engine copies a swap must respect and the cost of a swap. README.md links the section.

Known limitation (documented): a private or final method whose body is a literal may be inlined by the opcache optimizer into its callers, so a swap of it is invisible at those call sites. On PHP 8.5 a closure donor's captured (use) variables stay with the closure object and are not carried into the entry, as before this PR.

The PHP 8.4 port is #284 (8.4, the minimum affected branch; its merge-up into 8.5 conflicts in FunctionBodySwap/PendingBodySwap because 8.5 has no statics duplication, and this PR is the resolution). The goaop/framework z-engine driver (goaop/framework#765) consumes this API on both minors.

Fixes from the adversarial review

An independent review of the feature found nine defects, each reproduced on the pre-fix tree (segfault, zend_mm_heap corrupted, wrong dispatch); the six that exist on 8.5 are fixed in 5d3f079/9e97ad5 (the three others concern the statics duplicates PHP 8.4 mints, see #284):

• Minted run-time cache freed under its copies. The engine copies a swapped entry, cache pointer included, into every fake closure made over it (Closure::fromCallable(), first-class callable, ReflectionMethod::getClosure()) and into the interface-induced clone a subclass gets of an inherited entry; the next swap freed the block under them (use-after-free). Before a block is released its copies are found: fake closures get a private heap copy flagged ZEND_ACC_HEAP_RT_CACHE, clones get a fresh minted cache, a frame still running on the block keeps it allocated.
• preserveAs orphaned the materialized live statics table. The alias now takes over the live table of the body it preserves (the preserved body keeps its state), and the entry starts afresh.
• removeMethods() of a preserved alias leaked its live statics and minted cache. FunctionBodySwap::retireUnpublishedEntry() releases what the engine never will once the bucket is deleted from the only table holding it.
• Alias not shared into subclasses linked before that override the method. The swapped body's $this->alias() reached through parent:: failed with "Call to undefined method"; the alias is now published into every subclass linked before (an inheriting subclass receives the pointer with inherited-bucket ownership, a redeclaring subclass gets ZEND_ACC_CHANGED on its own method), and a shared-memory entry with any linked subclass is refused.
• publishOverride() cleared ZEND_ACC_CHANGED. The engine propagates the bit from a CHANGED (non-private) inherited method; without it an ancestor's private method was bypassed from the ancestor's own scope.
• Interface-induced engine clones invisible to the swap. A subclass implementing an interface that declares an inherited method holds a struct copy of the entry (do_inheritance_check_on_method), not the pointer: it kept the previous body after a redefine(), missed the alias, was skipped by an addMethod() override on an intermediate class and let a shared-memory ancestor be copied out from under it. Clones now follow the swap in place, carry the alias, are reached by overrides and guarded like pointer holders; immutability is judged by the holder class, not by the body-level ZEND_ACC_IMMUTABLE an entry adopts from an opcache-cached donor.

Each defect has a regression test group of its own (tests/Reflection/Redefine*Test.php, AddMethodChangedFlagTest.php, EntryPublicationsTest.php, stubs under tests/Stub/Alias/), and tests/HotSwap/scripts/redefine-alias-matrix.php runs five destructor-path scenarios under both allocators and both opcache modes.

Performance

A swap used to walk the whole class table for every question it asked about its entry and the object store once per check, building a reflection wrapper per visited class: about 190 ms per redefine() in a process holding 1,800 classes. EntryPublications (beb5d51) takes one survey per redefinition through an integer view of the class table (HashTable::pointerValueAddresses(), the technique ObjectStore already uses) and answers every question of the entry swap, the clone swaps and their commits from memory; a commit gathers the live closures once, before anything is destroyed. MethodPublisher reaches the linked subclasses through ReflectionClass::getLinkedSubclasses(), the same walk with a parent-chain check.

1,800-class process (PHP 8.5.11)	before	after
redefine(), 1,500 subclasses sharing the entry	~190 ms	5 ms
redefine(), unrelated classes	-	2 ms

Environment it was verified on

• PHP version (full first line of php -v): PHP 8.5.11 (cli) (built: Sep 24 2026 13:49:29) (NTS)
• Thread safety: NTS
• OS / architecture: Linux x86_64
• Debug build (--enable-debug)? no

Verified with opcache on and off, and with the JIT disabled (opcache.jit=off, opcache.jit_buffer_size=0): the tracing JIT on PHP 8.5 has a known upstream bug. The new tests pass in both runner modes (also under USE_ZEND_ALLOC=0), composer test, composer phpstan (PHPStan 2.3.1) and composer cs:check are green, and the goaop/framework zengine driver group passes against this head. Two failures of the local opcache-active runner mode (ClassSpecializerSlotTest segfault, FunctionLikeInfoTest type errors) reproduce on origin/8.5 without this PR and are not in CI's job.

Checklist

• Targets the minimum affected version branch (master = newest
  supported minor, 8.4 = PHP 8.4, …) — fixes cascade upward, never
  downward (targets 8.5; the 8.4 port is feat(reflection): preserve the previous body of redefine() under an alias and accept method donors (PHP 8.4) #284, see above)
• composer test passes on the matching PHP minor
• composer phpstan (level max) and composer cs:check are green
• Tests added or updated; structs the code dereferences are listed in
  layout_structs in tools/generator/symbols.php (no new structs are dereferenced)
• If tools/generator/symbols.php changed: regenerated with
  composer gen-headers and committed the result — nothing under
  include/, stubs/ or .phpstorm.meta.php was hand-edited (unchanged)
• Conventional Commits used for the commit messages

🤖 Generated with Claude Code

https://claude.ai/code/session_01VLQcsvgdQUzwBFsoKUAcG2

---

Generated by Claude Code

[lisachenko]

CI: PHPStan (level max) was red on every head of this PR, and it is not this PR's. The five findings are in tests/Memory/scenarios/get-iterator-hook.php, tests/Reflection/ReflectionClassResolutionHandlersTest.php and tests/System/Hook/ErrorCallbackHookTest.php, which this PR does not touch; they appear on origin/8.4 and origin/8.5 as well since PHPStan 2.3.1 (the lock file is not committed, so CI resolves the newest release). The fix is #283 against 8.4 (the minimum affected branch), and the same commit is cherry-picked into this PR (3843b85, with b807faa completing the ArrayObject typing), so the check is green here without waiting for the merge-up.

Two more notes for the review of this PR:

• 91a170c resolves self/parent against each side's own scope in the donor signature check. PHP 8.4 reflection reports the keywords verbatim while 8.5 resolves them, so without it a method donor spelling the target class failed the check on 8.4 only.
• Unrelated to this PR: on a PHP 8.4.19 build (NTS, release) ZEngine\System\ExecutionDataTest::testGetThis corrupts the heap (zend_mm_heap corrupted, corrupted double-linked list under USE_ZEND_ALLOC=0) on origin/8.4 without any of these changes; the 8.4 port of this feature is feature/redefine-preserve-alias-8.4 and was verified with that one test excluded.

---

Generated by Claude Code