Inline forwarding: a class double runs the real bodies on itself

[rasuvaeff]

Fixes #150

A forwarding double of a class now runs the real bodies on itself. The state the instance held is copied onto the double when forwarding() is called, and an unmatched call runs the doubled class's own body with $this still the double — so a self-call inside real code re-enters the double, meets stubs, an armed protocol and the call log, and is recorded like the boundary call. An interface double has no bodies to reach and proxies exactly as before. The README limitation paragraph is deleted, which was the acceptance criterion.

Mechanism: reflection, not a parent:: closure

The issue proposed what jasonmccreary/double does — a generated __td_real_*() sibling calling parent::. Golden rule 3 closes that: every member added to a double is a name the doubled type can no longer use.

The next candidate, a closure rendered into each generated method and handed to the dispatcher, was built and measured. It cost +10% per call on every class double, forwarding or not, because the argument is evaluated before dispatch can decide it is not needed. perf/ doubles only interfaces, so make perf cannot see this; the figure comes from a loop over a loose class double (1.217 → 1.337 µs/call, three paired runs, no overlap).

Runtime::runInline() therefore enters the body through ReflectionMethod::invokeArgs() on a reflection of the doubled class: the same non-virtual entry parent:: gives, while $this stays the double so the body's self-calls dispatch virtually and land back in the override. The generated code is byte-identical to master. spikes/08-inline-forwarding pins the language claim (non-virtual entry, virtual self-calls, protected bodies, by-reference parameters, $this identity) on 8.3, 8.4 and 8.5.

Decisions open to review

Decision	Why
Inline is the default for class doubles	An opt-in mode would leave the limitation as the default behaviour, and the acceptance asks for the paragraph deleted, not reworded
Inline requires the instance to be exactly the doubled class	A subclass instance carries overrides the doubled class's bodies do not contain; running those instead would silently change which code executes, so such a double keeps the proxy form
callOriginal() follows the double's own form	After the copy, the donor's state is no longer the current one — an inline double's escape hatch has to run where the state is
A clone made while a body runs inherits that double's forwarding — but only when it IS a copy of that double	Without the inheritance a : self wither, or a body computing over an internal copy, would hold a default-answering double in the middle of real code. Without the second half, a body handed another double of its own class and cloning that one — merge(self $other) — would adopt it with no state copy to run bodies over. Runtime::isCopyOf() compares both property tables through get_mangled_object_vars(); expectations are still not copied
The frames a clone can see stop at the test's own closure	An answers()/returns() closure runs inside dispatch, which a real body can reach, and clone $double written there is the test's clone. Runtime::$inlineFloor hides what is underneath for exactly its span, so only what the closure itself enters (callOriginal()) stays visible
A new static is refused, by registration rather than return type	Its constructor built its own state, so it cannot be adopted, and an instance no context knows is broken for every caller
Re-pointing an inline double is refused	A readonly property cannot be written twice, and a second copy would discard what the real code has written since

Behaviour changes for a suite that already forwards class doubles

Documented as **Changed.** in CHANGELOG.md, one test each:

• a self-call counts toward expect(...)->times(n) and can fill a step of an armed protocol;
• callOriginal() runs on the double, over the state the double holds;
• static::class inside a real body names the generated class;
• a real body handing out a new static raises OriginalReturnTypeViolation;
• the instance stops receiving the calls — it holds the state it had when forwarding() ran, and the copy is shallow, so writes through an object-valued property still land on the donor's collaborators.

The one thing PHP leaves open

Two doubles of one class in the same state are indistinguishable: __clone()
is handed no reference to its source, so a copy of the other double is
adopted and answers for real, over the state it already holds. It is stated as
a limitation in both READMEs, the forwarding guide and the CHANGELOG, rather
than called harmless — proxied, that copy answered defaults.

Verification

Gate	Result
composer build	PASS — Unit 1173, Integration 27, examples 8
PHP 8.3 / 8.4 / 8.5	1173 tests green on each; spikes 7/7 on 8.3 and 8.4
composer mutation	3586 mutants, 249 escaped, MSI 93% (gate 92) — master: 3481 / 234 / 93%. On the changed lines the survivors are equivalents, and the clone-adoption fix added none: cache-key permutations that stay unique per Class::method, ??= → =, ?-> where null is unreachable, >= 80400 vs > 80400
make perf / perf-memory	ours −3.9…+3.5% against competitors' −5.7…+0.6% in the same runs; memory per double unchanged (586 / 571 bytes). Class-double dispatch loop: −3.4%, −4.8%, +3.4%. re-taken for the clone-adoption fix on 2026-10-13, which puts two integer writes and a try/finally on every matched-with-action call: six runs of the full harness in one sitting, alternating b8a8f8e and 8befa94, medians of three a side. Ours moved −2.6%, +1.6%, −18.3%, −18.5%, 0.0%, 0.0% across the six tables while Mockery, Prophecy and PHPUnit moved −18.4% to +3.0% in the same runs — the two −18% tables moved for everybody, so the machine moved, not the library, and the two per-call dispatch tables (narrow, wide) are 0.0% for us against ±3.0% for them. RStDev ran 6.5–20%, so the ratios are the reading, not the microseconds. perf-memory identical to the byte (586 / 571 B)
make release-check	rector clean; roave reports only the pre-existing verifyAll(): void → int from #154
bin/package-audit	0 errors, 0 warnings
docs	docs-api, docs-build, docs-claims, docs-cookbook, docs-links green; MIGRATION.md regenerated; the @throws completeness budget lowered 8 → 7. make docs-vale needs a vale binary the authoring host has not got — the docs job lints the prose

The @throws budget move and the version strings across docs/src/api/** are the ordinary product of make docs-api on this branch.

Review follow-up (b91073a)

A review of the branch found that adoption decided on the clone's class,
and one generated class serves every double of a type. A body handed another
double of its own class and cloning that one adopted it on the running
double's behalf, with bodies to run and no state copy to run them over: PHP's
own must not be accessed before initialization where the class declares a
typed property, and a quiet answer computed from the declaration's default
where it has one. Both were regressions — proxied, the copy answered defaults.
A clone $double in the test's own answers() closure was adopted too,
against the documented rule for it.

The fix is the two table rows above. Seven tests came with it; five fail or
error on the commit before it, and two pin mechanisms that did not exist
there — the floor coming back after a throwing stub, and a hook that counts
its own calls to show that neither the state copy nor the comparison runs one.

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

• Configuration used: defaults
• Review profile: CHILL
• Plan: Advanced
• Run ID: a5fdd3e8-9bf5-4a4d-949b-db4d12d0ecd4

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}