From fed5b5d9ddfcb956ec9c86c1b37149cc3317aaa9 Mon Sep 17 00:00:00 2001 From: Carlos Granados Date: Sun, 13 Sep 2026 20:18:15 +0200 Subject: [PATCH 1/3] write the phpstorm integration page --- docs/integrations/phpstorm.md | 139 +++++++++++++++++++++++++++++++++- 1 file changed, 135 insertions(+), 4 deletions(-) diff --git a/docs/integrations/phpstorm.md b/docs/integrations/phpstorm.md index eef4c90f..7b6810e8 100644 --- a/docs/integrations/phpstorm.md +++ b/docs/integrations/phpstorm.md @@ -2,8 +2,139 @@ title: PhpStorm --- -PhpStorm has first-class DBGp support: listen for connections and debug with zero extra plugins. +PhpStorm needs no plugin and no special configuration to work with PHP Debugger. It +already speaks the protocol, and its defaults already match ours — it listens on +port `9003`, which is where the debugger connects. -:::note -This page is a work in progress — full documentation is coming soon. -::: +This page follows the [User Guide](../user-guide/starting-the-debugger.md) section +by section, saying what each one looks like in PhpStorm. Each links on to +JetBrains' own documentation, which is the authority on the editor side. + +## Starting the debugger + +[Guide: Starting the Debugger](../user-guide/starting-the-debugger.md) + +There is nothing to start. The debugger is available on every request, so the only +switch is PhpStorm's: **Run | Start Listening for PHP Debug Connections**, or the +telephone icon in the toolbar. Turn it on when you want to debug and off when you +are finished. + +This is what JetBrains call zero-configuration debugging, and it is the mode to +use — you do not need a run configuration, a server entry, or a browser extension +to trigger a session. + +One setting worth knowing about: **Settings | PHP | Debug | Break at first line in +PHP scripts**. With it on, PhpStorm stops at the first line of every request it +receives. That is occasionally useful and usually not what you want, especially +here, where every request arrives. + +→ [Zero-configuration debugging](https://www.jetbrains.com/help/phpstorm/zero-configuration-debugging.html) +· [Start a PHP debugging session](https://www.jetbrains.com/help/phpstorm/php-debugging-session.html) + +## Connecting to a client + +[Guide: Connecting to a Client](../user-guide/connecting-to-a-client.md) + +PhpStorm's debug port lives at **Settings | PHP | Debug**, and defaults to `9003`. +If you change it there, change +[`php_debugger.client_port`](../reference/settings.md#php_debuggerclient_port) to +match. + +When your code runs in a container, the other half of the setup is path mapping — +telling PhpStorm which local directory corresponds to the path the debugger +reports. That is configured under **Settings | PHP | Servers**, and it is the usual +reason breakpoints in a container are ignored. + +Over HTTP that is all you need — PhpStorm matches the connection to a server entry +by the URL that was requested. On the command line there is no URL to match on, so +you have to say which entry applies. Set `PHP_IDE_CONFIG` in the environment the +script runs in, naming the server exactly as it is named in that dialog: + +```bash +PHP_IDE_CONFIG="serverName=myapp" +``` + +Leaving it out, or misspelling the name, looks exactly like a mapping problem: the +session connects and the breakpoints are ignored. The +[Docker](../getting-started/docker.mdx) page sets it alongside the debugger's own +settings. + +→ [Configure Xdebug](https://www.jetbrains.com/help/phpstorm/configuring-xdebug.html) + +## Breakpoints + +[Guide: Breakpoints](../user-guide/breakpoints.md) + +Click the gutter beside a line to set one. Right-click it for a condition or a hit +count, and use **Run | View Breakpoints** for the full list, including exception +breakpoints and breakpoints on a function by name. + +PhpStorm's **Mute Breakpoints** button disables them all at once without deleting +them. It is handy mid-session, but muted breakpoints are still breakpoints as far as +the debugger is concerned — for the overhead to go away they have to be removed. + +→ [Breakpoints](https://www.jetbrains.com/help/phpstorm/using-breakpoints.html) + +## Step debugging + +[Guide: Step Debugging](../user-guide/step-debugging.md) + +The Debug tool window has the four actions the guide describes — Step Into, Step +Over, Step Out and Resume — plus **Run to Cursor**, which PhpStorm implements as a +temporary breakpoint just as the guide explains. + +When a step seems to skip past something, the cause is usually PhpStorm rather than +the debugger. Two settings pages decide what it steps into: **Debugger | Stepping**, +which can skip library scripts and any scripts you list, and **PHP | Debug | Step +Filters**, which can skip magic methods, constructors and named methods. **Force +Step Into** ignores both for a single step. + +→ [Step through the program](https://www.jetbrains.com/help/phpstorm/stepping-through-the-program.html) + +## Inspect variables + +[Guide: Inspect Variables](../user-guide/inspect-variables.md) + +The Debug tool window shows the call stack on one side and variables on the other. +Selecting a frame in the stack repoints the variables pane at that frame, which is +the part worth getting into the habit of using. + +PhpStorm also shows values inline, greyed out beside the code itself, which often +saves going to the panel at all. + +→ [Examine a suspended program](https://www.jetbrains.com/help/phpstorm/examining-suspended-program.html) + +## Watches and edits + +[Guide: Watches and Edits](../user-guide/watches-and-edits.md) + +Watches live in their own pane in the Debug tool window, and **Evaluate Expression** +handles the one-off case. Both run real PHP in the paused request, so the guide's +warnings about side effects apply exactly as written. + +To change a value, double-click it in the variables pane, or use **Set Value** from +its context menu. + +→ [Evaluate expressions](https://www.jetbrains.com/help/phpstorm/evaluating-expressions.html) + +## Logging + +[Guide: Logging](../user-guide/logging.md) + +The Console tab of the Debug tool window carries your script's output, and PHP's +warnings and notices appear there as the request produces them. Nothing needs +enabling on our side; PhpStorm asks for both when the session opens. + +→ [Debug tool window: Console](https://www.jetbrains.com/help/phpstorm/debug-tool-window-console.html) + +## Troubleshooting + +[Guide: Troubleshooting](../user-guide/troubleshooting.md) + +If a session never arrives, check the two things that are PhpStorm's rather than +ours: that it is actually listening, and that path mappings are right for where the +code runs. Our [troubleshooting page](../user-guide/troubleshooting.md) covers the +debugger side, and the debug log at the default level will tell you whether a +connection was attempted and where to. + +→ [Troubleshooting PHP debugging](https://www.jetbrains.com/help/phpstorm/troubleshooting-php-debugging.html) From d1563f10016cc2e6369f7aacf52974375eef0dc5 Mon Sep 17 00:00:00 2001 From: Carlos Granados Date: Sun, 13 Sep 2026 20:25:07 +0200 Subject: [PATCH 2/3] mark external links with an arrow --- docs/integrations/phpstorm.md | 16 ++++++++-------- src/css/custom.css | 13 +++++++++++++ 2 files changed, 21 insertions(+), 8 deletions(-) diff --git a/docs/integrations/phpstorm.md b/docs/integrations/phpstorm.md index 7b6810e8..5e46c3d4 100644 --- a/docs/integrations/phpstorm.md +++ b/docs/integrations/phpstorm.md @@ -28,7 +28,7 @@ PHP scripts**. With it on, PhpStorm stops at the first line of every request it receives. That is occasionally useful and usually not what you want, especially here, where every request arrives. -→ [Zero-configuration debugging](https://www.jetbrains.com/help/phpstorm/zero-configuration-debugging.html) +[Zero-configuration debugging](https://www.jetbrains.com/help/phpstorm/zero-configuration-debugging.html) · [Start a PHP debugging session](https://www.jetbrains.com/help/phpstorm/php-debugging-session.html) ## Connecting to a client @@ -59,7 +59,7 @@ session connects and the breakpoints are ignored. The [Docker](../getting-started/docker.mdx) page sets it alongside the debugger's own settings. -→ [Configure Xdebug](https://www.jetbrains.com/help/phpstorm/configuring-xdebug.html) +[Configure Xdebug](https://www.jetbrains.com/help/phpstorm/configuring-xdebug.html) ## Breakpoints @@ -73,7 +73,7 @@ PhpStorm's **Mute Breakpoints** button disables them all at once without deletin them. It is handy mid-session, but muted breakpoints are still breakpoints as far as the debugger is concerned — for the overhead to go away they have to be removed. -→ [Breakpoints](https://www.jetbrains.com/help/phpstorm/using-breakpoints.html) +[Breakpoints](https://www.jetbrains.com/help/phpstorm/using-breakpoints.html) ## Step debugging @@ -89,7 +89,7 @@ which can skip library scripts and any scripts you list, and **PHP | Debug | Ste Filters**, which can skip magic methods, constructors and named methods. **Force Step Into** ignores both for a single step. -→ [Step through the program](https://www.jetbrains.com/help/phpstorm/stepping-through-the-program.html) +[Step through the program](https://www.jetbrains.com/help/phpstorm/stepping-through-the-program.html) ## Inspect variables @@ -102,7 +102,7 @@ the part worth getting into the habit of using. PhpStorm also shows values inline, greyed out beside the code itself, which often saves going to the panel at all. -→ [Examine a suspended program](https://www.jetbrains.com/help/phpstorm/examining-suspended-program.html) +[Examine a suspended program](https://www.jetbrains.com/help/phpstorm/examining-suspended-program.html) ## Watches and edits @@ -115,7 +115,7 @@ warnings about side effects apply exactly as written. To change a value, double-click it in the variables pane, or use **Set Value** from its context menu. -→ [Evaluate expressions](https://www.jetbrains.com/help/phpstorm/evaluating-expressions.html) +[Evaluate expressions](https://www.jetbrains.com/help/phpstorm/evaluating-expressions.html) ## Logging @@ -125,7 +125,7 @@ The Console tab of the Debug tool window carries your script's output, and PHP's warnings and notices appear there as the request produces them. Nothing needs enabling on our side; PhpStorm asks for both when the session opens. -→ [Debug tool window: Console](https://www.jetbrains.com/help/phpstorm/debug-tool-window-console.html) +[Debug tool window: Console](https://www.jetbrains.com/help/phpstorm/debug-tool-window-console.html) ## Troubleshooting @@ -137,4 +137,4 @@ code runs. Our [troubleshooting page](../user-guide/troubleshooting.md) covers t debugger side, and the debug log at the default level will tell you whether a connection was attempted and where to. -→ [Troubleshooting PHP debugging](https://www.jetbrains.com/help/phpstorm/troubleshooting-php-debugging.html) +[Troubleshooting PHP debugging](https://www.jetbrains.com/help/phpstorm/troubleshooting-php-debugging.html) diff --git a/src/css/custom.css b/src/css/custom.css index 3a60cbe7..1bd87108 100644 --- a/src/css/custom.css +++ b/src/css/custom.css @@ -197,3 +197,16 @@ article a { .theme-admonition-info [class*='admonitionIcon'] svg { fill: var(--ifm-color-primary); } + +/* Mark links that leave the site. Internal links are written relative, so the + protocol prefix is a reliable test. The marker sits inside the link so it + inherits colour and underline, and is hidden from assistive technology -- + screen readers announce the destination from the href already. */ +.markdown a[href^='http']::after { + content: '\2197'; + display: inline-block; + margin-left: 0.15em; + font-size: 0.85em; + line-height: 1; + vertical-align: baseline; +} From 8d483b00e8a1771d8427bb087c39fd5bd6aeb070 Mon Sep 17 00:00:00 2001 From: Carlos Granados Date: Sun, 13 Sep 2026 20:34:22 +0200 Subject: [PATCH 3/3] make external links clearly distinct --- docs/integrations/phpstorm.md | 16 ++++++++-------- src/css/custom.css | 13 +++++++++---- 2 files changed, 17 insertions(+), 12 deletions(-) diff --git a/docs/integrations/phpstorm.md b/docs/integrations/phpstorm.md index 5e46c3d4..afe23387 100644 --- a/docs/integrations/phpstorm.md +++ b/docs/integrations/phpstorm.md @@ -28,7 +28,7 @@ PHP scripts**. With it on, PhpStorm stops at the first line of every request it receives. That is occasionally useful and usually not what you want, especially here, where every request arrives. -[Zero-configuration debugging](https://www.jetbrains.com/help/phpstorm/zero-configuration-debugging.html) +**JetBrains docs:** [Zero-configuration debugging](https://www.jetbrains.com/help/phpstorm/zero-configuration-debugging.html) · [Start a PHP debugging session](https://www.jetbrains.com/help/phpstorm/php-debugging-session.html) ## Connecting to a client @@ -59,7 +59,7 @@ session connects and the breakpoints are ignored. The [Docker](../getting-started/docker.mdx) page sets it alongside the debugger's own settings. -[Configure Xdebug](https://www.jetbrains.com/help/phpstorm/configuring-xdebug.html) +**JetBrains docs:** [Configure Xdebug](https://www.jetbrains.com/help/phpstorm/configuring-xdebug.html) ## Breakpoints @@ -73,7 +73,7 @@ PhpStorm's **Mute Breakpoints** button disables them all at once without deletin them. It is handy mid-session, but muted breakpoints are still breakpoints as far as the debugger is concerned — for the overhead to go away they have to be removed. -[Breakpoints](https://www.jetbrains.com/help/phpstorm/using-breakpoints.html) +**JetBrains docs:** [Breakpoints](https://www.jetbrains.com/help/phpstorm/using-breakpoints.html) ## Step debugging @@ -89,7 +89,7 @@ which can skip library scripts and any scripts you list, and **PHP | Debug | Ste Filters**, which can skip magic methods, constructors and named methods. **Force Step Into** ignores both for a single step. -[Step through the program](https://www.jetbrains.com/help/phpstorm/stepping-through-the-program.html) +**JetBrains docs:** [Step through the program](https://www.jetbrains.com/help/phpstorm/stepping-through-the-program.html) ## Inspect variables @@ -102,7 +102,7 @@ the part worth getting into the habit of using. PhpStorm also shows values inline, greyed out beside the code itself, which often saves going to the panel at all. -[Examine a suspended program](https://www.jetbrains.com/help/phpstorm/examining-suspended-program.html) +**JetBrains docs:** [Examine a suspended program](https://www.jetbrains.com/help/phpstorm/examining-suspended-program.html) ## Watches and edits @@ -115,7 +115,7 @@ warnings about side effects apply exactly as written. To change a value, double-click it in the variables pane, or use **Set Value** from its context menu. -[Evaluate expressions](https://www.jetbrains.com/help/phpstorm/evaluating-expressions.html) +**JetBrains docs:** [Evaluate expressions](https://www.jetbrains.com/help/phpstorm/evaluating-expressions.html) ## Logging @@ -125,7 +125,7 @@ The Console tab of the Debug tool window carries your script's output, and PHP's warnings and notices appear there as the request produces them. Nothing needs enabling on our side; PhpStorm asks for both when the session opens. -[Debug tool window: Console](https://www.jetbrains.com/help/phpstorm/debug-tool-window-console.html) +**JetBrains docs:** [Debug tool window: Console](https://www.jetbrains.com/help/phpstorm/debug-tool-window-console.html) ## Troubleshooting @@ -137,4 +137,4 @@ code runs. Our [troubleshooting page](../user-guide/troubleshooting.md) covers t debugger side, and the debug log at the default level will tell you whether a connection was attempted and where to. -[Troubleshooting PHP debugging](https://www.jetbrains.com/help/phpstorm/troubleshooting-php-debugging.html) +**JetBrains docs:** [Troubleshooting PHP debugging](https://www.jetbrains.com/help/phpstorm/troubleshooting-php-debugging.html) diff --git a/src/css/custom.css b/src/css/custom.css index 1bd87108..2ec2c28c 100644 --- a/src/css/custom.css +++ b/src/css/custom.css @@ -205,8 +205,13 @@ article a { .markdown a[href^='http']::after { content: '\2197'; display: inline-block; - margin-left: 0.15em; - font-size: 0.85em; - line-height: 1; - vertical-align: baseline; + margin-left: 0.25em; + padding: 0 0.25em; + border: 1px solid currentColor; + border-radius: 0.25em; + font-size: 0.7em; + font-weight: 700; + line-height: 1.5; + vertical-align: 0.15em; + opacity: 0.75; }