From 79fb931fdf38454d5a8a8e79b1ea3eec10bf5d13 Mon Sep 17 00:00:00 2001 From: Carlos Granados Date: Sat, 5 Sep 2026 08:32:08 +0200 Subject: [PATCH] write the step debugging guide page --- docs/user-guide/step-debugging.md | 91 +++++++++++++++++++++++++++++-- 1 file changed, 87 insertions(+), 4 deletions(-) diff --git a/docs/user-guide/step-debugging.md b/docs/user-guide/step-debugging.md index 22d20ca..c626787 100644 --- a/docs/user-guide/step-debugging.md +++ b/docs/user-guide/step-debugging.md @@ -2,8 +2,91 @@ title: Step Debugging --- -Step over, into, and out of your code with ease, following execution across files, closures, and includes. +When a [breakpoint](./breakpoints.md) fires, your script freezes exactly where it +is and the debugger hands control to your editor. Nothing else happens until you +say so — PHP is sitting inside the request, holding its stack, its variables and +its open connections, waiting. -:::note -This page is a work in progress — full documentation is coming soon. -::: +From there you have four ways to move, and two ways to finish. + +## Moving through the code + +| Action | What happens | +| --- | --- | +| Step into | Runs the next statement. If it calls a function, enter the function and stop on its first line. | +| Step over | Runs the next statement, including any calls it makes, and stops on the line after without entering them. | +| Step out | Runs the rest of the current function and stops just after it returns. | +| Run | Carries on until the next breakpoint, or to the end of the request. | + +**Step into** is the one that follows your code down. It descends into your +functions, methods and closures, and into files pulled in by `include` or +`require`. Bear in mind that it descends into *everything* your code calls — step +into a line that starts with a framework call and you can find yourself several +layers deep in code you did not write. + +**Step over** is what you want on the lines you already trust. The call still +happens, and its breakpoints still fire — stepping over a function does not disable +what is inside it. It only means you do not want to watch. + +**Step out** is the way back up when you have descended too far, or when you have +seen what you needed to and want to get back to the caller. If you are already at +the top level, there is nothing to return to, and it behaves like Run. + +**Run** — your editor may call it Continue or Resume — continues running the +script. If nothing else stops it, the request completes normally and the session +ends with it. + +## Run to cursor + +Most editors offer a "run to cursor" or "run to here": put the caret somewhere +ahead and the script continues until it reaches that spot. + +There is no such command in the debugger. What your editor does is set a +[temporary breakpoint](./breakpoints.md#temporary-breakpoints) on that line and +then Run. The breakpoint fires once and switches itself off, which produces exactly +the behaviour you asked for. + +Worth knowing for two reasons. The line still has to be one that executes, exactly +as with any other breakpoint — aim at a comment or a closing brace and the script +will run straight past it to the end. And it is subject to everything else in the +way: any other breakpoint that fires first will stop you before you arrive. + +## Seeing return values + +By default, stepping out of a function drops you on the line after the call, and +the value that came back is not shown anywhere — you have to step on and inspect +whatever it was assigned to. If it was not assigned to anything, or the call is +part of a longer chain, that value is awkward to get at. + +The debugger can add an extra stop on the way out of each function, showing what it +is about to return. This is off unless your editor asks for it — it is negotiated +when the session starts, so where you turn it on is an editor setting, usually +along the lines of "break on return" or "show return values". + +The cost is one more stop per function you step out of, which is the reason it is +not on by default. Turn it on while you are chasing a wrong value through a chain +of calls, and off again afterwards. + +## Stopping and detaching + +Two ways to end a session, and the difference matters: + +| Action | Effect | +| --- | --- | +| Stop | The script is killed. It does not finish. | +| Detach | The debugger lets go and the script runs to completion on its own. | + +**Stop** terminates the request where it stands. Nothing after the current point +runs — no remaining output, no shutdown functions, no destructors you were counting +on. Anything half-finished stays half-finished: a transaction that was never +committed, a file that was written but not closed, a queue message taken but not +acknowledged. + +**Detach** disconnects the debugger and leaves the script running. Breakpoints stop +firing, the request finishes as it normally would, and your editor goes quiet. This +is the one to use when you have seen what you came for on a request that ought to +complete — a checkout that should reach the end, a job that should be marked done. + +Neither turns the debugger off. The next request starts a fresh session and +connects again, so if you are stepping through something and want the noise to stop +for a while, disconnect your editor rather than detaching from each request in turn.