From 2717a670517dd9234217322bba58eb926fee041c Mon Sep 17 00:00:00 2001 From: Carlos Granados Date: Tue, 25 Aug 2026 16:46:15 +0200 Subject: [PATCH 1/2] replace configuration page with starting the debugger guide --- docs/getting-started/configuration.md | 32 ------ docs/getting-started/docker.mdx | 2 +- docs/getting-started/installation.mdx | 2 +- docs/getting-started/quick-start.md | 2 +- docs/user-guide/starting-the-debugger.md | 120 +++++++++++++++++++++++ sidebars.js | 2 +- 6 files changed, 124 insertions(+), 36 deletions(-) delete mode 100644 docs/getting-started/configuration.md create mode 100644 docs/user-guide/starting-the-debugger.md diff --git a/docs/getting-started/configuration.md b/docs/getting-started/configuration.md deleted file mode 100644 index 2409430..0000000 --- a/docs/getting-started/configuration.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -title: Configuration ---- - -PHP Debugger is configured through `php.ini` directives, all carrying the `php_debugger.` prefix. If you have set up step debugging for PHP before, most settings will look familiar. - -## Common settings - -```ini -zend_extension=php_debugger - -; debug is the only mode; profiling, coverage, and tracing were removed -php_debugger.mode=debug - -; start a session only when triggered (recommended), or always -php_debugger.start_with_request=trigger - -; where your IDE is listening -php_debugger.client_host=127.0.0.1 -php_debugger.client_port=9003 -``` - -## Directives - -| Directive | Default | Description | -| --- | --- | --- | -| `php_debugger.mode` | `debug` | Operating mode. Set to `off` to disable the extension entirely. | -| `php_debugger.start_with_request` | `trigger` | `trigger` starts a session only when a trigger is present; `yes` starts on every request. | -| `php_debugger.client_host` | `127.0.0.1` | Host the debugger connects back to (your IDE). | -| `php_debugger.client_port` | `9003` | Port the debugger connects back to. | - -See the [Configuration File](../reference/configuration-file.md) reference for the complete list of directives, and [Environment Variables](../reference/environment-variables.md) for runtime overrides. diff --git a/docs/getting-started/docker.mdx b/docs/getting-started/docker.mdx index a568c1a..be27233 100644 --- a/docs/getting-started/docker.mdx +++ b/docs/getting-started/docker.mdx @@ -163,4 +163,4 @@ image that already has the debugger in it. - [More install options](./install-options/index.md) — PIE, prebuilt binaries, and building from source -- [Configuration](./configuration.md) — the settings you can change +- [Quick Start](./quick-start.md) — pointing your editor at it diff --git a/docs/getting-started/installation.mdx b/docs/getting-started/installation.mdx index 3182253..e74849a 100644 --- a/docs/getting-started/installation.mdx +++ b/docs/getting-started/installation.mdx @@ -103,4 +103,4 @@ With the debugger installed, point your editor at it and set your first breakpoint: - [Quick Start](./quick-start.md) -- [Configuration](./configuration.md) +- [Starting the debugger](../user-guide/starting-the-debugger.md) diff --git a/docs/getting-started/quick-start.md b/docs/getting-started/quick-start.md index a5c168a..3af132c 100644 --- a/docs/getting-started/quick-start.md +++ b/docs/getting-started/quick-start.md @@ -53,5 +53,5 @@ See [IDE Support](../integrations/ide-support.md) for PhpStorm, VS Code and Neov ## Next steps +- [Starting the debugger](../user-guide/starting-the-debugger.md) — if you need something other than the defaults - [Breakpoints](../user-guide/breakpoints.md) and [step debugging](../user-guide/step-debugging.md) -- [Configuration](./configuration.md) — everything you can change, if you need to diff --git a/docs/user-guide/starting-the-debugger.md b/docs/user-guide/starting-the-debugger.md new file mode 100644 index 0000000..03de86c --- /dev/null +++ b/docs/user-guide/starting-the-debugger.md @@ -0,0 +1,120 @@ +--- +title: Starting the Debugger +--- + +Once PHP Debugger is installed and loaded, it is ready. Debugging is on, every +request starts a session, and the debugger connects whenever your editor is +listening. **We recommend leaving it exactly like that.** Used the way it is meant +to be used, the cost of having it there is very small. + +Everything below is for the cases where you need something different. You probably +do not. + +## Turning it off entirely + +`php_debugger.mode` decides whether the debugger does anything at all. It takes two +values: + +| Value | Meaning | +| --- | --- | +| `debug` | Step debugging is available. This is the default. | +| `off` | The debugger does nothing. | + +Anything else is rejected. Modes for profiling, coverage, tracing, +garbage-collection statistics and development helpers are not supported, because +those features are not part of this project. Setting one logs an error and falls +back to the default. + +Reach for `off` only if you want *no* overhead rather than *very small* overhead — +a benchmark you want undisturbed, or a long-running migration you would rather not +share the machine with. For everyday development the difference is not worth the +switch. + +## Not starting with every request + +`php_debugger.start_with_request` decides when a session begins. It defaults to +`yes`: every request starts one, and connects if your editor is listening. + +| Value | Meaning | +| --- | --- | +| `yes` | Start a session with every request. The default. | +| `no` | Never start a session. | +| `trigger` | Start only when a trigger is present. | + +### `no`, and starting later + +With `no`, the debugger never starts on its own — and it cannot be started later +either. Connecting mid-request with `php_debugger_connect_to_client()` does +nothing, and neither does `php_debugger_break()`, nor an error or exception. + +Setting `php_debugger.on_demand_debugging_enabled=1` makes all three work, letting +the debugger attach part-way through a request. + +:::warning[On-demand debugging is expensive] + +It is off by default for a reason. To be able to attach at any moment, every +request has to be compiled with debugging instrumentation, whether or not it ends +up being debugged. + +The near-zero overhead you would otherwise get drops to roughly half of it. Turn +it on only if you genuinely need to attach mid-request. + +::: + +### `trigger` + +With `trigger`, a session starts only when a trigger value is present in the +request. Nothing happens otherwise. + +The debugger looks for a trigger under any of these names, in this order: + +1. `XDEBUG_TRIGGER` +2. `PHP_DEBUGGER_TRIGGER` +3. `XDEBUG_SESSION` +4. `PHP_DEBUGGER_SESSION` + +Each is looked for in the environment first, then `$_GET`, then `$_POST`, then +`$_COOKIE`. So both of these start a session: + +```bash +PHP_DEBUGGER_TRIGGER=1 php your-script.php +``` + +``` +https://example.test/page.php?PHP_DEBUGGER_TRIGGER=1 +``` + +By default *any* value will do. `php_debugger.trigger_value` turns that into a +shared secret — the trigger only counts if its value matches, and a value that +does not match is refused and logged: + +```ini +php_debugger.start_with_request=trigger +php_debugger.trigger_value=letmein +``` + +Several secrets can be accepted at once by separating them with commas, which is +useful when more than one person shares an environment. + +Worth saying plainly: `trigger` was how you kept a heavyweight debugger out of the +way when it was not needed. That is not the problem here — an idle session costs +almost nothing — so the default of `yes` is usually the better choice. + +## Keeping the overhead low + +The cost of running the debugger depends on what it is doing: + +| Situation | Cost | +| --- | --- | +| No client connected | Near zero. | +| Client connected, nothing set | Low. | +| Breakpoints set, stepping through code | Real, and unavoidable — this is the work you asked for. | + +The middle row is the one that catches people out. A session you forgot about is +not free, and neither are breakpoints you no longer need. Two habits keep things +fast: + +- **Remove breakpoints once you are done with them.** Every one left behind is + checked on every request. +- **Disconnect your editor when you stop debugging.** With nothing listening, the + debugger drops back to costing almost nothing. diff --git a/sidebars.js b/sidebars.js index 90ad159..68f3f4e 100644 --- a/sidebars.js +++ b/sidebars.js @@ -25,7 +25,6 @@ const sidebars = { ], }, 'getting-started/quick-start', - 'getting-started/configuration', ], }, { @@ -33,6 +32,7 @@ const sidebars = { label: 'User Guide', collapsed: false, items: [ + 'user-guide/starting-the-debugger', 'user-guide/breakpoints', 'user-guide/step-debugging', 'user-guide/inspect-variables', From 03339217a83fb87f404481a8a18850bda769e791 Mon Sep 17 00:00:00 2001 From: Carlos Granados Date: Tue, 25 Aug 2026 16:58:16 +0200 Subject: [PATCH 2/2] highlight the overhead advice in a box --- docs/user-guide/starting-the-debugger.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/docs/user-guide/starting-the-debugger.md b/docs/user-guide/starting-the-debugger.md index 03de86c..13c1d37 100644 --- a/docs/user-guide/starting-the-debugger.md +++ b/docs/user-guide/starting-the-debugger.md @@ -111,10 +111,13 @@ The cost of running the debugger depends on what it is doing: | Breakpoints set, stepping through code | Real, and unavoidable — this is the work you asked for. | The middle row is the one that catches people out. A session you forgot about is -not free, and neither are breakpoints you no longer need. Two habits keep things -fast: +not free, and neither are breakpoints you no longer need. + +:::tip[Two habits worth keeping] - **Remove breakpoints once you are done with them.** Every one left behind is checked on every request. - **Disconnect your editor when you stop debugging.** With nothing listening, the debugger drops back to costing almost nothing. + +:::