feat(protocol): complete the core DBGp command set

[lisachenko]

Closes the five commands the spec requires and zdebug still answered error 4 for, adds the two Xdebug breakpoint types it was missing, and gives object properties the visibility an IDE draws them with.

Commands

Command	Notes
stack_depth	The frame count stack_get will report; zero rather than an error while nothing is suspended.
typemap_get	The type column is the exact spelling PropertySerializer puts on its <property> elements, so what the map promises and what the properties carry cannot drift. Declares the xsi/xsd namespaces its <map> elements need.
source	Hands the IDE the code the debuggee is running — -f defaults to the frame's own file, -b/-e select an inclusive range.
breakpoint_update	Changes -s/-n/-h/-o in place, keeping the id and the accumulated hit count.
property_set	Writes through to the live frame.

source is a file-read primitive on an open socket

It reads through the same FileFilter the instrumentation uses, so it is scoped to the code configured as debuggable rather than to whatever the debuggee process can open. An integration test asserts that a file outside ZDEBUG_PATH_FILTER comes back as error 100. With no filter configured it observes everything — the same trade the instrumentation already makes, now made once and visibly.

breakpoint_update moves the breakpoint, not just the field

line is a key of the index the statement hook reads on its hot path. Assigning it alone would leave the breakpoint firing on its old line forever, so -n goes through BreakpointRegistry::relocate().

property_set — the first write path into the engine

It resolves the base variable to its live CV slot (ExecutionData::getLocalVariable()) and pushes the rebuilt root back through setNativeValue(). Rebuilding rather than mutating: PHP arrays are value types, so the array a read handed over is a copy, and writing into it would change nothing the debuggee can observe. Objects are handles, so a ReflectionProperty write lands in the real object and assigning the root back is a harmless no-op that keeps one code path for both.

Every step is a refusal by default:

• the base must be a real CV slot of the selected frame, or a superglobal — $this is deliberately not writable;
• intermediate steps must already exist (error 300) — inventing an array key would be an addition disguised as an edit;
• a write the engine rejects (readonly property, typed property the value does not fit) is success="0", not a broken debuggee;
• -t names the incoming type, and without it the type already at that path is kept, so editing an int in the variables panel does not silently store "42".

A declared-but-unset local is exempt from the "must exist" rule on purpose: it has a slot to write and no value to resolve, and giving it one is a legitimate edit.

The test asserts the debuggee's own output after it resumes — MUTATED=42|after|true|2.5|99|77|5|PV|locked|given — because a success="1" for a write into a materialized copy would look exactly the same on the wire.

Call / return breakpoints

They ride different machinery:

• -t return is a handler on the RETURN opline, where the leaving frame is still current and its locals still readable. Every function body ends in one, including a body that falls off the end. RETURN_BY_REF and GENERATOR_RETURN are not this opcode and are documented as out of reach.
• -t call has no function-entry event to hook, so it uses the one statement guaranteed to run once per call: the op_array's first EXT_STMT. Control always enters a frame at the top of its op_array, so that statement is exact. Consecutive statements on the same line are deduped; the residual gap (a one-statement function called twice inside one expression, f(f()), reports one entry) is documented in the code.

The opcode scan is memoized per op_array and only reached when a call breakpoint exists, so a debuggee without one pays nothing. -m accepts fn, Class::fn or Class->fn; the class part is checked against the bound object when there is one, and ignored for a static method rather than never matching — a breakpoint that silently never fires is worse to debug than one that fires once too often.

facet

ObjectProperties was already demangling the property-table key to recover the declaring class and throwing the visibility away. It now travels with the value, so <property facet="private"> is what the IDE draws its padlock from. Array elements and frame locals carry no facet — they are not declared under a visibility.

Tests

• PropertyMutationSessionTest — writes to scalars, nested array elements, private/protected/public object properties, a private array one step deeper, a null local; a refused readonly write; four unwritable paths as error 300; and the debuggee's own output as proof.
• FunctionBreakpointSessionTest — call fires once per call with the body not yet run, return stops with the frame still readable, both on a single-statement function, a hit condition skipping the first call, and -m-less rejection.
• ProtocolCommandsSessionTest — stack_depth agreeing with stack_get, the typemap, source inside and outside the path filter, breakpoint_update disabling without losing the id or hit count, and the facets of $this.
• SourceReaderTest — inclusive one-based ranges, empty-versus-null, and the filter refusal.
• Unit coverage in CommandDispatcherTest for every new command's error paths, and the line-index move.

All four gates pass locally: phpunit (281 tests), phpunit --group integration --fail-on-skipped (37 tests), phpstan analyse at level max, php-cs-fixer --dry-run.

Still not implemented

break (async pause) was postponed by request. stdout/stderr remain acknowledged-as-unsupported, and watch breakpoints, spawnpoint_*, interact, exec/expr and stdin are unimplemented — Xdebug declines most of those too. feature_get continues to report every one of them as unsupported.

---

Generated by Claude Code