From b76d793f1ccc5c4dc5c9a8e34bc4e38939f2a5f9 Mon Sep 17 00:00:00 2001 From: Carlos Granados Date: Sun, 1 Nov 2026 08:50:31 +0100 Subject: [PATCH 01/10] make agentic debugging a headline feature on the home page --- docs/agentic-debugging/dbgp-client.md | 3 ++ docs/index.mdx | 2 +- docusaurus.config.js | 2 +- sidebars.js | 6 ++++ src/components/HomeCards/index.js | 32 ++++++++++++---------- src/components/HomeCards/styles.module.css | 31 --------------------- src/components/HomeFeatureStrip/index.js | 22 ++++++++------- src/components/HomeHero/index.js | 4 +-- src/components/HomeHero/styles.module.css | 4 +-- 9 files changed, 44 insertions(+), 62 deletions(-) create mode 100644 docs/agentic-debugging/dbgp-client.md diff --git a/docs/agentic-debugging/dbgp-client.md b/docs/agentic-debugging/dbgp-client.md new file mode 100644 index 00000000..a951fe77 --- /dev/null +++ b/docs/agentic-debugging/dbgp-client.md @@ -0,0 +1,3 @@ +--- +title: DBGP Client +--- diff --git a/docs/index.mdx b/docs/index.mdx index 85f76162..f381029f 100644 --- a/docs/index.mdx +++ b/docs/index.mdx @@ -2,7 +2,7 @@ id: home slug: / title: PHP Debugger -description: Zero-overhead debugging for PHP — a lightweight, powerful debugger that doesn't slow you down. +description: Agentic zero-overhead debugging for PHP — a lightweight, powerful debugger that doesn't slow you down, and that your AI agents can drive too. displayed_sidebar: docsSidebar hide_title: true hide_table_of_contents: true diff --git a/docusaurus.config.js b/docusaurus.config.js index d9586834..6e1cdd55 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -45,7 +45,7 @@ async function latestDebuggerVersion() { /** @type {import('@docusaurus/types').Config} */ const config = { title: 'PHP Debugger', - tagline: 'Zero-overhead debugging for PHP', + tagline: 'Agentic zero-overhead debugging for PHP', favicon: 'img/favicon.svg', future: { diff --git a/sidebars.js b/sidebars.js index 91dde172..10a0ea90 100644 --- a/sidebars.js +++ b/sidebars.js @@ -43,6 +43,12 @@ const sidebars = { 'user-guide/troubleshooting', ], }, + { + type: 'category', + label: 'Agentic debugging', + collapsed: false, + items: ['agentic-debugging/dbgp-client'], + }, { type: 'category', label: 'Reference', diff --git a/src/components/HomeCards/index.js b/src/components/HomeCards/index.js index cd8d4345..68c1ad82 100644 --- a/src/components/HomeCards/index.js +++ b/src/components/HomeCards/index.js @@ -1,11 +1,13 @@ import Link from '@docusaurus/Link'; import styles from './styles.module.css'; -const quickStartSteps = [ - 'Install it with one command', - 'Start your editor listening', - 'Set a breakpoint', - 'Run your code as usual', +const dbgpClientFeatures = [ + 'MCP server for Claude Code and others', + 'Breakpoints, stepping, stack and variables', + 'Sees script output and PHP warnings', + 'Local, container or remote PHP', + 'Optional read-only mode', + 'Also a terminal debugger, no IDE needed', ]; const keyFeatures = [ @@ -39,18 +41,18 @@ export default function HomeCards() {
>_} - title="Quick Start" - linkTo="/getting-started/quick-start" - linkLabel="View quick start guide"> -

Four steps, and nothing to configure.

-
    - {quickStartSteps.map((step, i) => ( -
  1. - {i + 1} - {step} + title="DBGP Client" + linkTo="/agentic-debugging/dbgp-client" + linkLabel="Debug with your agent"> +

    Let AI agents debug PHP the way you would.

    +
      + {dbgpClientFeatures.map((feature) => ( +
    • + ✓ + {feature}
      • ))} -
+ + + + + + + ), + }, { title: 'Fast & Lightweight', text: 'Built for speed with zero performance overhead.', @@ -32,16 +44,6 @@ const features = [ ), }, - { - title: 'IDE Integration', - text: 'Works seamlessly with your favorite IDE.', - icon: ( - - - - - ), - }, { title: 'Always Available', text: 'Leave it on. It costs almost nothing until you debug.', diff --git a/src/components/HomeHero/index.js b/src/components/HomeHero/index.js index c5a78dc6..ef7a4c54 100644 --- a/src/components/HomeHero/index.js +++ b/src/components/HomeHero/index.js @@ -16,10 +16,10 @@ export default function HomeHero() { {`v${siteConfig.customFields.debuggerVersion}`}

- Zero-overhead debugging for PHP + Agentic zero-overhead debugging for PHP

- A lightweight, powerful debugger that doesn't slow you down. + A lightweight, powerful debugger that doesn't slow you down, and that your AI agents can drive too.

diff --git a/src/components/HomeHero/styles.module.css b/src/components/HomeHero/styles.module.css index 96364ef8..727f91ed 100644 --- a/src/components/HomeHero/styles.module.css +++ b/src/components/HomeHero/styles.module.css @@ -30,7 +30,7 @@ } .title { - font-size: 3rem; + font-size: 2.6rem; line-height: 1.1; margin: 0; } @@ -124,6 +124,6 @@ } .title { - font-size: 2.25rem; + font-size: 2rem; } } From 0b4bbe1aa0ccebd5134f5fd3d7c3d9eef1ca566c Mon Sep 17 00:00:00 2001 From: Carlos Granados Date: Sun, 1 Nov 2026 08:59:40 +0100 Subject: [PATCH 02/10] shorten the hero tagline and give the DBGP Client card an agent icon --- docs/index.mdx | 2 +- src/components/HomeCards/index.js | 17 ++++++++++++++++- src/components/HomeCards/styles.module.css | 6 ------ src/components/HomeHero/index.js | 2 +- 4 files changed, 18 insertions(+), 9 deletions(-) diff --git a/docs/index.mdx b/docs/index.mdx index f381029f..6f19704f 100644 --- a/docs/index.mdx +++ b/docs/index.mdx @@ -2,7 +2,7 @@ id: home slug: / title: PHP Debugger -description: Agentic zero-overhead debugging for PHP — a lightweight, powerful debugger that doesn't slow you down, and that your AI agents can drive too. +description: Agentic zero-overhead debugging for PHP — a lightweight, powerful debugger that doesn't slow you down. Built for you and your AI agents. displayed_sidebar: docsSidebar hide_title: true hide_table_of_contents: true diff --git a/src/components/HomeCards/index.js b/src/components/HomeCards/index.js index 68c1ad82..d50f32a1 100644 --- a/src/components/HomeCards/index.js +++ b/src/components/HomeCards/index.js @@ -40,7 +40,22 @@ export default function HomeCards() { return (
>_} + icon={ + + + + + + + } title="DBGP Client" linkTo="/agentic-debugging/dbgp-client" linkLabel="Debug with your agent"> diff --git a/src/components/HomeCards/styles.module.css b/src/components/HomeCards/styles.module.css index d0b16122..665d071e 100644 --- a/src/components/HomeCards/styles.module.css +++ b/src/components/HomeCards/styles.module.css @@ -26,12 +26,6 @@ color: var(--ifm-color-primary); } -.promptIcon { - font-family: var(--ifm-font-family-monospace); - font-weight: 700; - font-size: 1.1rem; -} - .cardTitle { font-size: 1.15rem; margin: 0; diff --git a/src/components/HomeHero/index.js b/src/components/HomeHero/index.js index ef7a4c54..3e877aad 100644 --- a/src/components/HomeHero/index.js +++ b/src/components/HomeHero/index.js @@ -19,7 +19,7 @@ export default function HomeHero() { Agentic zero-overhead debugging for PHP

- A lightweight, powerful debugger that doesn't slow you down, and that your AI agents can drive too. + A lightweight, powerful debugger that doesn't slow you down. Built for you and your AI agents.

From 12eb6206a029a51ed58d0929d47b343f4999f00d Mon Sep 17 00:00:00 2001 From: Carlos Granados Date: Mon, 2 Nov 2026 08:12:05 +0100 Subject: [PATCH 03/10] write the DBGP Client introduction page --- docs/agentic-debugging/dbgp-client.md | 106 ++++++++++++++++++++++++++ 1 file changed, 106 insertions(+) diff --git a/docs/agentic-debugging/dbgp-client.md b/docs/agentic-debugging/dbgp-client.md index a951fe77..b26cb2e7 100644 --- a/docs/agentic-debugging/dbgp-client.md +++ b/docs/agentic-debugging/dbgp-client.md @@ -1,3 +1,109 @@ --- title: DBGP Client +description: DBGP Client lets AI agents debug PHP with PHP Debugger, the way you would. It also works as a standalone debugger in your terminal. --- + +[DBGP Client](https://github.com/php-debugger/dbgp-client) is a debugger client for +PHP. Its `dbgp` command speaks [DBGp](../reference/debug-protocol.md), the same +protocol your IDE uses to talk to PHP Debugger, and it can be used in two ways: + +- **As a debugging tool for AI agents.** `dbgp mcp` is an + [MCP](https://modelcontextprotocol.io) server that lets an agent such as Claude + Code debug PHP the way you would: set breakpoints, run the code, step through it, + and look at the stack, variables, output and warnings. +- **As a command-line debugger.** `dbgp` on its own is an interactive debugger in + your terminal, for when you want to debug PHP yourself without an IDE. + +Both work with PHP scripts and web requests, on your own machine, in a container or +on a server. + +## Why let an agent use a debugger? + +Ask a coding agent to find out why something is broken and it will usually do one of +two things. It reads the code and reasons about what *should* happen, which works +until the bug is in something it cannot see: the data in your database, a value +from the request, a config setting, the order in which things actually ran. Or it +adds `var_dump()` and log lines, runs the code, reads the output, adds some more, and +eventually has to remember to take them all out again. + +That second approach is the one [we tell people to stop using](../user-guide/stop-using-dd.md), +and the reasons are the same for an agent. Every round adds code you did not ask for, +each run shows only what it decided to print beforehand, and anything it forgot to +print means another round. + +With a debugger, the agent stops the code where it wants to look and sees everything: +the real values of every variable, the call stack that led there and the path the +code actually took. It does not have to guess what to print, and there is nothing to +clean up afterwards, because your code is never changed. + +## Why it pairs well with PHP Debugger + +An agent debugs in short bursts, between long stretches of reading and editing code. +For most of that time nothing is being debugged, so the debugger should cost nothing +then. + +That is how PHP Debugger works: it can stay on all the time and costs almost nothing +until something is listening. dbgp only listens while the agent is actually +debugging, and stops when it is done. You can leave both of them set up permanently, +and PHP runs at full speed except while the agent is stepping through it. + +dbgp also works with Xdebug. Run `php -v` to see which one your PHP has. + +## What an agent can do with it + +dbgp gives the agent the same tools you have in your IDE: + +- **Breakpoints** on a line, optionally with a condition, when a function is called + or returns, or when an exception is thrown +- **Running and stepping**: run to the next breakpoint, or step into, over and out + of the code +- **The call stack and variables** in any frame, including large arrays and objects + a page at a time +- **The source** around where the code stopped +- **What the script printed** and the **PHP warnings and notices** it raised +- **Evaluating PHP expressions** and **changing variables** in the stopped script +- **Path mappings** for PHP running in a container or on another machine + +The agent also starts the code to debug on its own, running a script or sending a +web request, so you only have to tell it what is wrong. For example: + +> Find out why the total on the checkout page is wrong: debug the request to +> /checkout with a breakpoint in CartService::total(). + +## How it works + +dbgp sits between the agent and PHP. The agent talks to dbgp over MCP, and dbgp +talks to PHP Debugger over DBGp, on port `9003` by default: + +```text +AI agent ──MCP──▶ dbgp ◀──DBGp, port 9003── PHP Debugger, in PHP +``` + +A typical debugging run goes like this: + +1. The agent adds a breakpoint and tells dbgp to start listening. +2. It runs the script or sends the request. PHP Debugger connects to dbgp, and the + script waits there. +3. The agent runs the code to the breakpoint, and looks at the stack, the variables + and the source. +4. It steps through the code, or runs on to another breakpoint, until it has found + what it was looking for. +5. It ends the session, removes the breakpoint and stops listening, and PHP runs at + full speed again. + +Each script run or request that connects is a separate session, so the agent can +debug several at a time, for example a web request and the queue job it sets off. + +## Security + +Like any debugger, dbgp trusts the PHP that connects to it and the agent that uses +it: + +- **The agent sees what your code sees.** While debugging, an agent can read every + variable of the script, including passwords and API keys, and any file PHP can + read. Start dbgp with `-no-eval` to stop the agent from running PHP code of its own + in the script, so it can only look. This does not hide anything from it. +- **The PHP port is not authenticated.** Anything that can reach port `9003` can + connect to dbgp as if it were PHP, and show the agent made-up code and values. Make + sure only your own PHP hosts and containers can reach it, and use an SSH tunnel or + a VPN to debug PHP across a network you do not trust. From ceb50eff3860856466c0c19e44ae955bfcb9d21f Mon Sep 17 00:00:00 2001 From: Carlos Granados Date: Mon, 2 Nov 2026 08:25:11 +0100 Subject: [PATCH 04/10] add a boxes diagram and a security warning to the DBGP Client page --- .../{dbgp-client.md => dbgp-client.mdx} | 12 +- src/components/DbgpDiagram/index.js | 79 ++++++++++ src/components/DbgpDiagram/styles.module.css | 141 ++++++++++++++++++ 3 files changed, 227 insertions(+), 5 deletions(-) rename docs/agentic-debugging/{dbgp-client.md => dbgp-client.mdx} (96%) create mode 100644 src/components/DbgpDiagram/index.js create mode 100644 src/components/DbgpDiagram/styles.module.css diff --git a/docs/agentic-debugging/dbgp-client.md b/docs/agentic-debugging/dbgp-client.mdx similarity index 96% rename from docs/agentic-debugging/dbgp-client.md rename to docs/agentic-debugging/dbgp-client.mdx index b26cb2e7..b996c25d 100644 --- a/docs/agentic-debugging/dbgp-client.md +++ b/docs/agentic-debugging/dbgp-client.mdx @@ -3,6 +3,8 @@ title: DBGP Client description: DBGP Client lets AI agents debug PHP with PHP Debugger, the way you would. It also works as a standalone debugger in your terminal. --- +import DbgpDiagram from '@site/src/components/DbgpDiagram'; + [DBGP Client](https://github.com/php-debugger/dbgp-client) is a debugger client for PHP. Its `dbgp` command speaks [DBGp](../reference/debug-protocol.md), the same protocol your IDE uses to talk to PHP Debugger, and it can be used in two ways: @@ -73,11 +75,9 @@ web request, so you only have to tell it what is wrong. For example: ## How it works dbgp sits between the agent and PHP. The agent talks to dbgp over MCP, and dbgp -talks to PHP Debugger over DBGp, on port `9003` by default: +talks to PHP Debugger over DBGp: -```text -AI agent ──MCP──▶ dbgp ◀──DBGp, port 9003── PHP Debugger, in PHP -``` + A typical debugging run goes like this: @@ -94,7 +94,7 @@ A typical debugging run goes like this: Each script run or request that connects is a separate session, so the agent can debug several at a time, for example a web request and the queue job it sets off. -## Security +:::warning[Security] Like any debugger, dbgp trusts the PHP that connects to it and the agent that uses it: @@ -107,3 +107,5 @@ it: connect to dbgp as if it were PHP, and show the agent made-up code and values. Make sure only your own PHP hosts and containers can reach it, and use an SSH tunnel or a VPN to debug PHP across a network you do not trust. + +::: diff --git a/src/components/DbgpDiagram/index.js b/src/components/DbgpDiagram/index.js new file mode 100644 index 00000000..87a39fc7 --- /dev/null +++ b/src/components/DbgpDiagram/index.js @@ -0,0 +1,79 @@ +import styles from './styles.module.css'; + +const iconProps = { + width: 26, + height: 26, + viewBox: '0 0 24 24', + fill: 'none', + stroke: 'currentColor', + strokeWidth: 1.8, + strokeLinecap: 'round', + strokeLinejoin: 'round', + 'aria-hidden': true, +}; + +function Box({icon, title, text, highlight}) { + return ( +
+ {icon} + {title} + {text} +
+ ); +} + +function Link({label}) { + return ( +
+ {label} + +
+ ); +} + +/* Agent <-> dbgp <-> PHP Debugger, for the DBGP Client "How it works" section. + Plain boxes rather than an image so it follows the light and dark themes. */ +export default function DbgpDiagram() { + return ( +
+ + + + + + + } + title="AI agent" + text="Claude Code or any other MCP agent" + /> + + + + + + } + title="DBGP Client" + text="DBGP Client, running on your machine" + /> + + + + + + + } + title="PHP Debugger" + text="In the PHP script or request being debugged" + /> +
+ ); +} diff --git a/src/components/DbgpDiagram/styles.module.css b/src/components/DbgpDiagram/styles.module.css new file mode 100644 index 00000000..4523d53c --- /dev/null +++ b/src/components/DbgpDiagram/styles.module.css @@ -0,0 +1,141 @@ +.diagram { + display: flex; + align-items: stretch; + margin: 1.5rem 0 2rem; +} + +.box { + flex: 1 1 0; + min-width: 0; + display: flex; + flex-direction: column; + align-items: center; + text-align: center; + gap: 0.35rem; + border: 1px solid var(--phpdbg-card-border); + border-radius: 10px; + background: var(--phpdbg-surface); + padding: 1.1rem 1rem 1.2rem; +} + +.highlight { + border-color: var(--ifm-color-primary); +} + +.icon { + display: inline-flex; + color: var(--ifm-color-primary); +} + +.title { + font-size: 1rem; +} + +.text { + font-size: 0.85rem; + line-height: 1.45; + color: var(--ifm-color-emphasis-700); +} + +/* The connector between two boxes: a label over a double-headed arrow. */ +.link { + flex: 0 0 5.5rem; + display: flex; + flex-direction: column; + align-items: center; + justify-content: center; + gap: 0.4rem; +} + +.label { + font-family: var(--ifm-font-family-monospace); + font-size: 0.8rem; + font-weight: 700; + color: var(--ifm-color-primary); +} + +.line { + position: relative; + width: calc(100% - 1rem); + height: 2px; + background: var(--ifm-color-emphasis-500); +} + +.line::before, +.line::after { + content: ''; + position: absolute; + top: 50%; + width: 0; + height: 0; + border-top: 5px solid transparent; + border-bottom: 5px solid transparent; + transform: translateY(-50%); +} + +.line::before { + left: -1px; + border-right: 7px solid var(--ifm-color-emphasis-500); +} + +.line::after { + right: -1px; + border-left: 7px solid var(--ifm-color-emphasis-500); +} + +/* On narrow screens the boxes stack, and the arrows turn vertical. */ +@media (max-width: 768px) { + .diagram { + flex-direction: column; + } + + /* A spacer, the arrow, then the label, so the arrow stays centred. */ + .link { + flex: 0 0 4rem; + flex-direction: row; + gap: 0.6rem; + } + + .link::before { + content: ''; + flex: 1 1 0; + order: 0; + } + + .line { + order: 1; + } + + .label { + flex: 1 1 0; + order: 2; + text-align: left; + } + + .line { + width: 2px; + height: auto; + align-self: stretch; + margin: 0.5rem 0; + } + + .line::before, + .line::after { + top: auto; + left: 50%; + border: 5px solid transparent; + transform: translateX(-50%); + } + + .line::before { + top: -6px; + border-bottom: 7px solid var(--ifm-color-emphasis-500); + border-top-width: 0; + } + + .line::after { + bottom: -6px; + border-top: 7px solid var(--ifm-color-emphasis-500); + border-bottom-width: 0; + } +} From 379dd00f558c7642f64579a1f202c22b1fd57f05 Mon Sep 17 00:00:00 2001 From: Carlos Granados Date: Mon, 2 Nov 2026 09:04:48 +0100 Subject: [PATCH 05/10] add the DBGP Client installation page --- docs/agentic-debugging/installation.mdx | 164 ++++++++++++++++++++++++ sidebars.js | 2 +- 2 files changed, 165 insertions(+), 1 deletion(-) create mode 100644 docs/agentic-debugging/installation.mdx diff --git a/docs/agentic-debugging/installation.mdx b/docs/agentic-debugging/installation.mdx new file mode 100644 index 00000000..c1e6aa5a --- /dev/null +++ b/docs/agentic-debugging/installation.mdx @@ -0,0 +1,164 @@ +--- +title: Installation +description: Install DBGP Client on Linux, macOS or Windows, and check that PHP is ready to be debugged. +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import ConsoleSample from '@site/src/components/ConsoleSample'; + +DBGP Client is a single program, `dbgp`, with nothing to install alongside it. The +install script downloads the right build for your system and puts it on your +`PATH`. + +:::info[Install it where your agent runs] + +dbgp runs on the machine where your agent, or your terminal, runs. If PHP runs in +a container or on a server, you do not need to install dbgp there: PHP connects +to it over the network. + +::: + +## Install it + + + + +```bash +curl -fsSL https://github.com/php-debugger/dbgp-client/releases/latest/download/install.sh | sh +``` + +This installs `dbgp` to `/usr/local/bin`. If you cannot write there, the script +uses `sudo` and asks for your password. + + + + +Run this in PowerShell as administrator: + +```powershell +powershell -c "irm https://github.com/php-debugger/dbgp-client/releases/latest/download/install.ps1 | iex" +``` + +This installs `dbgp` to `%ProgramFiles%\dbgp` and adds that folder to the system +`PATH`. Open a new terminal afterwards so it picks up the change. + + + + +### Choosing where and what to install + +Two environment variables change what the script does: + +| Variable | What it does | +| --- | --- | +| `INSTALL_DIR` | Installs to this directory instead. | +| `VERSION` | Installs this release, such as `0.1.1`, instead of the latest one. | + +For example, to install into your home directory, where no administrator rights +are needed: + + + + +```bash +curl -fsSL https://github.com/php-debugger/dbgp-client/releases/latest/download/install.sh | INSTALL_DIR="$HOME/.local/bin" sh +``` + +If the directory is not on your `PATH`, the script prints the line to add to your +shell's profile. + + + + +```powershell +$env:INSTALL_DIR = "$env:LOCALAPPDATA\dbgp" +powershell -c "irm https://github.com/php-debugger/dbgp-client/releases/latest/download/install.ps1 | iex" +``` + +With `INSTALL_DIR` set, the script adds the directory to your own `PATH` rather +than the system one. + + + + +### Other platforms + +Builds are published for Linux and macOS, on both `amd64` and `arm64`, and for +Windows on `amd64`. On anything else, install it with Go 1.26 or later: + +```bash +go install github.com/php-debugger/dbgp-client/cmd/dbgp@latest +``` + +### Downloading it yourself + +You can also download the archive for your system from the +[Releases page](https://github.com/php-debugger/dbgp-client/releases) and put the +`dbgp` binary anywhere on your `PATH`. Each release file has a build provenance +attestation, which shows it was built by the project's own release workflow. To +check a file you downloaded, run: + +```bash +gh attestation verify dbgp-linux-amd64.tar.gz --repo php-debugger/dbgp-client +``` + +## Check that it works + +```bash +dbgp -version +``` + +This prints `dbgp` followed by the version you installed. + +## Make sure PHP can be debugged + +dbgp debugs PHP through PHP Debugger, or through Xdebug, so PHP needs one of them. +Run `php -v` and look for PHP Debugger in the output: + +{`$ php -v +PHP 8.4.23 (cli) (built: Jul 2 2026 20:39:24) (NTS) +Copyright (c) The PHP Group +Zend Engine v4.4.23, Copyright (c) Zend Technologies + with PHP Debugger v__VERSION__, Copyright (c) 2002-2026, by Derick Rethans`} + +If it is not there, [install PHP Debugger](../getting-started/installation.mdx) +first. + +## Updating + +Run the install command again to update to the latest release. Set `VERSION` to +move to a particular one, including an older one. + +If you run dbgp's MCP server in the background, it keeps running the version it +started with. Restart it to use the new one: + +```bash +dbgp mcp stop && dbgp mcp start +``` + +On Windows, stop it with `dbgp mcp stop` before updating: a running `dbgp` cannot be +replaced. + +## Uninstalling + +Stop the background MCP server if you started one, then delete the `dbgp` binary: + + + + +```bash +dbgp mcp stop +sudo rm /usr/local/bin/dbgp +``` + + + + +Run `dbgp mcp stop`, delete the `%ProgramFiles%\dbgp` folder, and remove it from the +system `PATH`. + + + + +Remember to remove `dbgp` from your agent's MCP settings too. diff --git a/sidebars.js b/sidebars.js index 10a0ea90..b6cdd7e5 100644 --- a/sidebars.js +++ b/sidebars.js @@ -47,7 +47,7 @@ const sidebars = { type: 'category', label: 'Agentic debugging', collapsed: false, - items: ['agentic-debugging/dbgp-client'], + items: ['agentic-debugging/dbgp-client', 'agentic-debugging/installation'], }, { type: 'category', From d043ad2fb4384e11e6e85c1c0c5849a02d50196e Mon Sep 17 00:00:00 2001 From: Carlos Granados Date: Mon, 2 Nov 2026 22:23:06 +0100 Subject: [PATCH 06/10] add the debugging with agents page --- docs/agentic-debugging/agents.mdx | 244 ++++++++++++++++++++++++++++++ sidebars.js | 6 +- 2 files changed, 249 insertions(+), 1 deletion(-) create mode 100644 docs/agentic-debugging/agents.mdx diff --git a/docs/agentic-debugging/agents.mdx b/docs/agentic-debugging/agents.mdx new file mode 100644 index 00000000..f4c15cc3 --- /dev/null +++ b/docs/agentic-debugging/agents.mdx @@ -0,0 +1,244 @@ +--- +title: Debugging with agents +description: Add DBGP Client to Claude Code or any other MCP agent, and let it debug your PHP scripts and web requests. +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +`dbgp mcp` runs DBGP Client as an [MCP](https://modelcontextprotocol.io) server. +Once you add it to your agent, the agent can debug PHP the way you would in your +IDE: set breakpoints, run the code, step through it, and look at the stack, the +variables, the output and the warnings. + +## Add it to your agent + + + + +```bash +claude mcp add dbgp -- dbgp mcp +``` + +This adds it to the current project. Add `--scope user` to make it available in +all of your projects: + +```bash +claude mcp add --scope user dbgp -- dbgp mcp +``` + +Run `/mcp` inside Claude Code to check that it is connected. + + + + +Any agent that supports MCP servers can use dbgp. Add a server that runs the +command `dbgp` with the argument `mcp`. Most agents take a JSON configuration like +this one: + +```json +{ + "mcpServers": { + "dbgp": { + "command": "dbgp", + "args": ["mcp"] + } + } +} +``` + +See your agent's documentation for where its MCP settings live. + + + + +The agent starts `dbgp mcp` itself when it needs it, so there is nothing else to +run. [Options](#options) go after `mcp`, for example `dbgp mcp -no-eval`. + +## Make sure PHP can reach dbgp + +When a script or request starts, PHP Debugger connects to the address in +[`php_debugger.client_host`](../user-guide/connecting-to-a-client.md) on the port in +`php_debugger.client_port`. They default to `localhost` and `9003`, and dbgp listens +on port `9003` by default. So when PHP runs on the same machine as your agent, +there is nothing to set up. + +### PHP in a container or on a server + +PHP has to connect to the machine your agent runs on. Set `client_host` to an +address that reaches it, such as `host.docker.internal` from a Docker container: + +```ini +php_debugger.client_host=host.docker.internal +``` + +[Connecting to a client](../user-guide/connecting-to-a-client.md#when-the-code-runs-somewhere-else) +covers the other ways to find that address. + +dbgp also needs to know where your project's files are inside the container, so +that the files and lines the agent works with match the ones PHP runs. The agent +can work this out and add the mapping itself, but if you always debug the same +setup you can pass it with `-map`, as `LOCAL=REMOTE`: + +```bash +claude mcp add dbgp -- dbgp mcp -map /home/you/myapp=/var/www/html +``` + +### If your IDE is listening too + +Only one program can listen on a port at a time. If your IDE is listening on +`9003`, dbgp cannot, and PHP might connect to your IDE instead of to the agent. +Stop listening in your IDE while the agent debugs. + +To use both at the same time, give dbgp a port of its own with `-php-port`, and set +`client_port` to that port for the PHP the agent runs. For a script, the +[`PHP_DEBUGGER_CONFIG`](../reference/environment-variables.md#php_debugger_config) +environment variable does it for a single run: + +```bash +PHP_DEBUGGER_CONFIG="client_port=9013" php app.php +``` + +## Ask it to debug something + +Tell the agent what is wrong and how to make it happen, and ask it to use the +debugger. It decides where to put breakpoints, runs the code, and reports what it +found. For example: + +> The total on the checkout page is wrong when a coupon is applied. Debug the +> request to /checkout with a breakpoint in CartService::total() and find out why. + +> `php bin/console app:import users.csv` skips some of the rows. Use the debugger +> to find out which ones, and why. + +> The test `testRefundIsCapped` fails. Debug it and step through `Refund::amount()` +> to see where the value goes wrong. + +The more you tell it, the faster it gets there: the URL or command that shows the +problem, what you expected to happen, and where you think the problem is. Asking +it to *use the debugger* matters too: otherwise, many agents still reach for +`var_dump()` out of habit. + +## What happens while it debugs + +dbgp does not listen for PHP until the agent asks it to, and stops when the agent +is done. A typical run goes like this: + +1. The agent adds its breakpoints and starts listening. +2. It runs the script, or sends the web request, in the background. +3. PHP Debugger connects to dbgp, and the script waits there, stopped at its + start. The agent takes that session and runs it to the first breakpoint. +4. It looks at the stack, the variables and the source, steps through the code, and + reads what the script has printed and the warnings it raised. +5. When it has what it needs, it ends the session, removes its breakpoints and + stops listening. + +### Other requests while it listens + +PHP Debugger is always on, so while dbgp is listening, *every* script or request +that runs connects to it, not just the agent's. If you load a page of your app in +the browser while the agent is debugging, that request connects too, and waits. + +dbgp lets such requests go: a session that no agent takes within a minute of +connecting is detached, and its script runs on to its end without the debugger. So +nothing is left hanging, but a request you make while the agent is debugging can +take up to a minute to answer. + +Agents keep their listening short, so this rarely comes up. When it does, it is +usually a sign that the agent forgot to stop listening: ask it to. + +## The tools it gets + +These are the tools dbgp gives the agent. You do not need to know them to use it, +but they show what it can and cannot do: + +| Tool | What it does | +| --- | --- | +| `status` | Shows whether dbgp is listening, the sessions, breakpoints and path mappings. | +| `listen`, `unlisten` | Start and stop listening for PHP. | +| `add_breakpoint`, `remove_breakpoint`, `breakpoints` | Manage breakpoints: on a line, optionally with a condition, when a function is called or returns, or when an exception is thrown. | +| `add_path_mapping`, `path_mappings` | Map a project directory to where PHP sees it, for PHP in a container or on a server. | +| `sessions`, `wait_for_session` | List the sessions, and wait for the next one to connect. | +| `continue`, `wait_for_stop` | Run to the next breakpoint, or step into, over or out of the code. | +| `stop`, `detach` | End a session where it is, or let its script run on without the debugger. | +| `stack`, `variables`, `variable`, `variable_value` | Show the call stack and the variables of any frame, a page at a time for large arrays and objects. | +| `source` | Show the source around where the code stopped, or around any file and line. | +| `output`, `warnings` | Show what the script printed, and the PHP warnings and notices it raised. | +| `eval`, `set_variable` | Evaluate a PHP expression in the stopped script, or change a variable. | + +## Options + +Add these after `dbgp mcp` in the command your agent runs: + +| Option | What it does | +| --- | --- | +| `-no-eval` | Turns off everything that runs PHP code the agent writes. See [Look, don't touch](#look-dont-touch). | +| `-map LOCAL=REMOTE` | Maps a directory on this machine to where PHP sees it. Repeat it for several mappings. | +| `-php-port PORT` | The port to listen on for PHP. Defaults to `9003`. | +| `-idekey KEY` | Accepts only sessions with this IDE key, and turns away any other PHP that connects. | +| `-listen` | Listens for PHP from the start, instead of waiting for the agent to ask. | + +`dbgp mcp -h` lists them all. + +## Look, don't touch + +With `-no-eval`, the agent cannot run PHP code of its own in the script it is +debugging. That turns off the `eval` and `set_variable` tools, and conditions on +breakpoints. It can still stop the code anywhere, step through it, and read every +variable, so it can still find out what went wrong. It just cannot change anything +along the way. + +```bash +claude mcp add dbgp -- dbgp mcp -no-eval +``` + +:::warning[It can still see everything] + +This limits what the agent can *do*, not what it can *see*: it still reads every +variable the script has, passwords and API keys included. And PHP still runs some +code when it is read: reading an object property that does not exist calls the +object's `__get()` method, if it has one. + +::: + +## Sharing one dbgp between agents + +By default, each agent session starts its own dbgp, which goes away when the +session ends, along with its breakpoints. To keep one running in the background +instead, start it yourself: + +```bash +dbgp mcp start # start it, with any of the options above +dbgp mcp status # is it running? +dbgp mcp stop # stop it +``` + +While it runs, agents that start `dbgp mcp` connect to it instead of starting their +own, and use the options it was started with. That gives you: + +- **Breakpoints and sessions that last** from one agent session to the next. +- **Several agents debugging at once**, sharing the same breakpoints and path + mappings. Each agent has its own current session, and dbgp keeps listening until + every agent that asked it to listen has stopped. + +Agents reach it on port `9004`, on this machine only. Change the port with +`-mcp-port` when you start it. Only you can use it: agents connect with a token +kept in a file that other users on the machine cannot read. + +It does not start again by itself after a restart, so run `dbgp mcp start` again +when you need it. After [updating dbgp](./installation.mdx#updating), restart it +to use the new version. + +## Using it with Xdebug + +dbgp works with Xdebug too. PHP Debugger starts debugging every request by itself, +but Xdebug has to be told to: + +```ini +xdebug.mode=debug +xdebug.start_with_request=yes +``` + +Xdebug in debug mode slows every request down, even while nothing is listening. +PHP Debugger costs almost nothing until something listens, which is what makes it +the better fit for leaving on while an agent works. diff --git a/sidebars.js b/sidebars.js index b6cdd7e5..616ae1ff 100644 --- a/sidebars.js +++ b/sidebars.js @@ -47,7 +47,11 @@ const sidebars = { type: 'category', label: 'Agentic debugging', collapsed: false, - items: ['agentic-debugging/dbgp-client', 'agentic-debugging/installation'], + items: [ + 'agentic-debugging/dbgp-client', + 'agentic-debugging/installation', + 'agentic-debugging/agents', + ], }, { type: 'category', From 01c40863079ad95f55536775b58845e426b432bd Mon Sep 17 00:00:00 2001 From: Carlos Granados Date: Mon, 2 Nov 2026 22:33:45 +0100 Subject: [PATCH 07/10] polish the debugging with agents page --- docs/agentic-debugging/agents.mdx | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/docs/agentic-debugging/agents.mdx b/docs/agentic-debugging/agents.mdx index f4c15cc3..09ae67ef 100644 --- a/docs/agentic-debugging/agents.mdx +++ b/docs/agentic-debugging/agents.mdx @@ -57,9 +57,9 @@ run. [Options](#options) go after `mcp`, for example `dbgp mcp -no-eval`. ## Make sure PHP can reach dbgp -When a script or request starts, PHP Debugger connects to the address in -[`php_debugger.client_host`](../user-guide/connecting-to-a-client.md) on the port in -`php_debugger.client_port`. They default to `localhost` and `9003`, and dbgp listens +When a script or request starts, PHP Debugger +[connects](../user-guide/connecting-to-a-client.md) to the address in +`php_debugger.client_host` on the port in `php_debugger.client_port`. They default to `localhost` and `9003`, and dbgp listens on port `9003` by default. So when PHP runs on the same machine as your agent, there is nothing to set up. @@ -172,11 +172,12 @@ Add these after `dbgp mcp` in the command your agent runs: | Option | What it does | | --- | --- | -| `-no-eval` | Turns off everything that runs PHP code the agent writes. See [Look, don't touch](#look-dont-touch). | +| `-no-eval` | Turns off everything that runs PHP code written by the agent. See [Look, don't touch](#look-dont-touch). | | `-map LOCAL=REMOTE` | Maps a directory on this machine to where PHP sees it. Repeat it for several mappings. | | `-php-port PORT` | The port to listen on for PHP. Defaults to `9003`. | | `-idekey KEY` | Accepts only sessions with this IDE key, and turns away any other PHP that connects. | | `-listen` | Listens for PHP from the start, instead of waiting for the agent to ask. | +| `-mcp-port PORT` | With `dbgp mcp start`: the port agents reach the [background server](#sharing-one-dbgp-between-agents) on. Defaults to `9004`. | `dbgp mcp -h` lists them all. @@ -195,8 +196,8 @@ claude mcp add dbgp -- dbgp mcp -no-eval :::warning[It can still see everything] This limits what the agent can *do*, not what it can *see*: it still reads every -variable the script has, passwords and API keys included. And PHP still runs some -code when it is read: reading an object property that does not exist calls the +variable the script has, passwords and API keys included. And PHP may still run some +code reading values: reading an object property that does not exist calls the object's `__get()` method, if it has one. ::: @@ -221,7 +222,7 @@ own, and use the options it was started with. That gives you: mappings. Each agent has its own current session, and dbgp keeps listening until every agent that asked it to listen has stopped. -Agents reach it on port `9004`, on this machine only. Change the port with +Agents reach it on port `9004` by default, on this machine only. Change the port with `-mcp-port` when you start it. Only you can use it: agents connect with a token kept in a file that other users on the machine cannot read. From 2a2a6d4f43e0533023e2dd76dd67c0f8916dabc9 Mon Sep 17 00:00:00 2001 From: Carlos Granados Date: Mon, 2 Nov 2026 22:38:55 +0100 Subject: [PATCH 08/10] reword the -mcp-port option and the -no-eval warning --- docs/agentic-debugging/agents.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/agentic-debugging/agents.mdx b/docs/agentic-debugging/agents.mdx index 09ae67ef..6ba358e0 100644 --- a/docs/agentic-debugging/agents.mdx +++ b/docs/agentic-debugging/agents.mdx @@ -177,7 +177,7 @@ Add these after `dbgp mcp` in the command your agent runs: | `-php-port PORT` | The port to listen on for PHP. Defaults to `9003`. | | `-idekey KEY` | Accepts only sessions with this IDE key, and turns away any other PHP that connects. | | `-listen` | Listens for PHP from the start, instead of waiting for the agent to ask. | -| `-mcp-port PORT` | With `dbgp mcp start`: the port agents reach the [background server](#sharing-one-dbgp-between-agents) on. Defaults to `9004`. | +| `-mcp-port PORT` | The port agents connect to over MCP. Defaults to `9004`. | `dbgp mcp -h` lists them all. @@ -197,7 +197,7 @@ claude mcp add dbgp -- dbgp mcp -no-eval This limits what the agent can *do*, not what it can *see*: it still reads every variable the script has, passwords and API keys included. And PHP may still run some -code reading values: reading an object property that does not exist calls the +code when reading values: reading an object property that does not exist calls the object's `__get()` method, if it has one. ::: From 8bc88e119f066577ad9238ba46f1b664a0fb696b Mon Sep 17 00:00:00 2001 From: Carlos Granados Date: Tue, 3 Nov 2026 08:23:33 +0100 Subject: [PATCH 09/10] add the debugging from the terminal page --- docs/agentic-debugging/cli.mdx | 285 +++++++++++++++++++++++++++++++++ sidebars.js | 1 + 2 files changed, 286 insertions(+) create mode 100644 docs/agentic-debugging/cli.mdx diff --git a/docs/agentic-debugging/cli.mdx b/docs/agentic-debugging/cli.mdx new file mode 100644 index 00000000..8e8f3785 --- /dev/null +++ b/docs/agentic-debugging/cli.mdx @@ -0,0 +1,285 @@ +--- +title: Debugging from the terminal +description: Use DBGP Client as an interactive debugger in your terminal, to debug PHP scripts and web requests without an IDE. +--- + +`dbgp` on its own is an interactive debugger that runs in your terminal. It does +everything you would do in an IDE: set breakpoints, step through the code, and look +at the stack and the variables. You type commands at a prompt instead of clicking. + +That makes it handy wherever an IDE is not: on a server you reached over SSH, +inside a container, or for a quick look at a script without opening a project. + +## Start it + +Run `dbgp`, optionally with a breakpoint or two: + +```bash +dbgp -break src/Controller/HomeController.php:25 +``` + +dbgp starts listening for PHP right away, on port `9003`, and waits for your +commands. Then run your PHP code as usual, for example in another terminal: + +```bash +php app.php +``` + +The script connects to dbgp and stops at its start, waiting for you. Web requests +work the same way: load the page in your browser, or send the request with `curl`, +and it connects too. + +As with an IDE, PHP finds dbgp through +[`client_host` and `client_port`](../user-guide/connecting-to-a-client.md), which +default to `localhost` and `9003`. When PHP runs on the same machine, there is +nothing to set up. + +## A first session + +Here is a short script that adds up the items in a cart: + +```php title="cart.php" + 'Book', 'price' => 12.5, 'qty' => 2], + ['name' => 'Pen', 'price' => 1.2, 'qty' => '3'], +]; + +echo total($items, 5), "\n"; +``` + +Start dbgp with a breakpoint inside the loop, then run `php cart.php` in another +terminal. dbgp announces the session, and `run` takes it to the breakpoint, showing +the code around it: + +```text +$ dbgp -break cart.php:7 +Breakpoint 1: /home/you/shop/cart.php:7 +Listening for PHP on port 9003. Sessions are announced when PHP connects, +and commands that need one wait for it. Type help for commands. +(dbgp) run +Waiting for PHP to connect (Ctrl-C to cancel)... + +[session 1 connected: /home/you/shop/cart.php (selected)] +Stopped at /home/you/shop/cart.php:7 + 3 function total(array $items, float $discount): float + 4 { + 5 $sum = 0; + 6 foreach ($items as $item) { +=> 7 $sum += $item['price'] * $item['qty']; + 8 } + 9 + 10 return $sum - $discount; + 11 } +``` + +The prompt now shows the session and its state: session `1`, stopped at a +breakpoint. Look at how it got there, and at the variables: + +```text +(dbgp 1:break) stack +#0 total() at /home/you/shop/cart.php:7 +#1 {main}() at /home/you/shop/cart.php:18 +(dbgp 1:break) vars +$discount float = 5 +$item array = array[3] +$items array = array[2] +$sum int = 0 +(print NAME shows what an array or object contains) +(dbgp 1:break) print $item +$item array = array[3] + $item["name"] string = "Book" + $item["price"] float = 12.5 + $item["qty"] int = 2 +``` + +`next` steps over the line. Here that goes round the loop and back to line 7, for +the next item, with `$sum` updated: + +```text +(dbgp 1:break) next +Stopped at /home/you/shop/cart.php:7 +... +(dbgp 1:break) print $sum +$sum float = 25 +``` + +`out` runs to the end of the function and stops back in the code that called it. +`run` then runs the script to its end, `output` shows what it printed, and `stop` +ends the session: + +```text +(dbgp 1:break) out +Stopped at /home/you/shop/cart.php:18 +... +=> 18 echo total($items, 5), "\n"; +(dbgp 1:break) run +Script finished; output shows its output, stop ends the session. +(dbgp 1:stopping) output +23.6 +(dbgp 1:stopping) stop +Stopped session 1. +(dbgp 1:ended) +``` + +dbgp keeps listening, so you can run the script again and the next session starts +the same way. `quit` exits dbgp. + +## Breakpoints + +| Command | Stops | +| --- | --- | +| `break FILE:LINE` | At a line. | +| `break LINE` | At a line of the file the session is stopped in. | +| `break FILE:LINE if COND` | At a line, but only when the PHP expression `COND` is true. | +| `break call FUNC` | When the function or method `FUNC` is called. | +| `break return FUNC` | When the function or method `FUNC` returns. | +| `break exception CLASS` | When an exception of class `CLASS`, or a subclass of it, is thrown. | + +A relative `FILE` is taken from the directory you started dbgp in. `breaks` lists +the breakpoints with their numbers, and `delete ID` removes one. Breakpoints apply +to every session, including ones that connect later. + +A conditional breakpoint is the quickest way to stop on the one case you are +interested in, rather than every time round a loop: + +```text +(dbgp) break cart.php:7 if $item["name"] == "Pen" +Breakpoint 1: /home/you/shop/cart.php:7 if $item["name"] == "Pen" +``` + +To set breakpoints before PHP connects, either type them at the prompt or pass them +with `-break` when you start dbgp. Repeat `-break` for several. + +## Running and stepping + +| Command | What it does | +| --- | --- | +| `run` | Runs to the next breakpoint, or to the end of the script. | +| `step` | Steps into the next statement, going inside any function it calls. | +| `next` | Steps over the next statement, running any function it calls in one go. | +| `out` | Runs to the end of the current function, and stops in the code that called it. | + +While the script runs, these commands wait for it to stop. Press `Ctrl-C` to stop +waiting and get the prompt back: the script keeps running. + +When the script reaches its end, the session stays open so that you can still read +its output. `stop` then ends it. + +## Looking around + +| Command | What it shows | +| --- | --- | +| `stack` | The call stack, innermost first. | +| `vars [DEPTH [CONTEXT]]` | The variables of a stack frame: `0`, the default, is where the code stopped, `1` the function that called it, and so on. | +| `contexts` | The variable contexts `vars` can show: the local variables, the superglobals, and the constants you defined. | +| `print NAME` | A variable, and what an array or object contains, such as `print $user["name"]` or `print $order->items`. `-d DEPTH` reads it from another stack frame, and `-p PAGE` shows further pages of a large array or object. | +| `value NAME` | A variable's whole value, for long strings that `print` cuts short. Also takes `-d DEPTH`. | +| `source [[FILE:]LINE]` | The source around where the code stopped, or around another line or file. | +| `output` | What the script has printed since you last looked. | +| `notes` | The PHP warnings, notices and other errors the script has raised since you last looked. | + +## Changing things + +| Command | What it does | +| --- | --- | +| `eval CODE` | Evaluates a PHP expression where the code stopped, and shows the result. | +| `set NAME = EXPR` | Sets a variable to the value of a PHP expression. | + +`eval` is handy for checking an expression before you change the code: + +```text +(dbgp 1:break) eval $item["price"] * $item["qty"] +3.5999999999999996 (float) +``` + +Both run code in the script you are debugging, so they can change what it does +from there on. + +## Ending a session + +`stop` ends the script where it is. `detach` lets it run on to its end without the +debugger, which is what you want for a web request whose page you still want to +see. + +## Several sessions at once + +Every script or request that connects while dbgp is listening becomes a session. +dbgp announces each one as it connects, and selects the first, so commands act on +it. + +```text +[session 2 connected: /home/you/shop/public/index.php] +``` + +`sessions` lists them all, and `use ID` switches to another one. + +A session waits for you until you run, detach or stop it. PHP Debugger is always +on, so while dbgp listens, every request you make to your app connects and waits, +not just the one you meant to debug. When you have the session you want, `unlisten` +stops dbgp from taking new ones, and those requests run without the debugger again. +`listen` starts taking them again. + +## PHP in a container or on a server + +PHP has to connect to the machine dbgp runs on. Set `client_host` to an address that +reaches it, such as `host.docker.internal` from a Docker container. See +[Connecting to a client](../user-guide/connecting-to-a-client.md#when-the-code-runs-somewhere-else) +for the details. + +dbgp also needs to know where your project's files are inside the container, so +that breakpoints you set on your files land on the files PHP runs. Pass the mapping +as `LOCAL=REMOTE` with `-map` when you start dbgp: + +```bash +dbgp -map /home/you/shop=/var/www/html -break src/Cart.php:42 +``` + +or add it at the prompt with `map`. `maps` lists the mappings. + +You can also run dbgp on the server or in the container itself, next to PHP, over +SSH or with `docker exec`. Then PHP connects to `localhost` as usual, and no mapping +is needed. + +## Options + +| Option | What it does | +| --- | --- | +| `-break FILE:LINE` | Sets a breakpoint before PHP connects. Repeat it for several. | +| `-map LOCAL=REMOTE` | Maps a directory on this machine to where PHP sees it. Repeat it for several. | +| `-php-port PORT` | The port to listen on for PHP. Defaults to `9003`. | +| `-idekey KEY` | Accepts only sessions with this IDE key, and turns away any other PHP that connects. | +| `-history FILE` | Where to keep the command history. Defaults to `~/.dbgp_history`. Set it to an empty value to keep none. | +| `-version` | Prints the version and exits. | + +`dbgp -h` lists them all. + +## At the prompt + +The prompt has line editing, tab completion for commands, and a history you can +step through with the arrow keys, kept between runs. `help` lists every command. + +The most common commands have short aliases: + +| Alias | Command | +| --- | --- | +| `r` | `run` | +| `s` | `step` | +| `n` | `next` | +| `o` | `out` | +| `b` | `break` | +| `bt` | `stack` | +| `p` | `print` | +| `l` | `source` | +| `q`, `exit` | `quit` | diff --git a/sidebars.js b/sidebars.js index 616ae1ff..c3192c4d 100644 --- a/sidebars.js +++ b/sidebars.js @@ -51,6 +51,7 @@ const sidebars = { 'agentic-debugging/dbgp-client', 'agentic-debugging/installation', 'agentic-debugging/agents', + 'agentic-debugging/cli', ], }, { From c7bf68097669718cede9304adb57f52ca70e47a9 Mon Sep 17 00:00:00 2001 From: Carlos Granados Date: Tue, 3 Nov 2026 08:27:36 +0100 Subject: [PATCH 10/10] link the DBGP Client intro to the other agentic debugging pages --- docs/agentic-debugging/dbgp-client.mdx | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/agentic-debugging/dbgp-client.mdx b/docs/agentic-debugging/dbgp-client.mdx index b996c25d..c43ad55c 100644 --- a/docs/agentic-debugging/dbgp-client.mdx +++ b/docs/agentic-debugging/dbgp-client.mdx @@ -109,3 +109,9 @@ it: a VPN to debug PHP across a network you do not trust. ::: + +## Next steps + +- [Install DBGP Client](./installation.mdx) +- [Debug with your AI agent](./agents.mdx) +- [Debug from the terminal](./cli.mdx)