Skip to content

Commit 6d74122

Browse files
carlos-granadoscarlos-granados
authored
Merge pull request #28 from php-debugger/vs-code
write the vs code integration page
2 parents 53c4376 + 524d9db commit 6d74122

2 files changed

Lines changed: 146 additions & 8 deletions

File tree

‎docs/integrations/phpstorm.md‎

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -40,10 +40,12 @@ If you change it there, change
4040
[`php_debugger.client_port`](../reference/settings.md#php_debuggerclient_port) to
4141
match.
4242

43-
When your code runs in a container, the other half of the setup is path mapping —
44-
telling PhpStorm which local directory corresponds to the path the debugger
45-
reports. That is configured under **Settings | PHP | Servers**, and it is the usual
46-
reason breakpoints in a container are ignored.
43+
Whenever the paths the debugger reports are not the paths on your own machine, the
44+
other half of the setup is path mapping — telling PhpStorm which local directory
45+
corresponds to which remote one. A container is the common case, but so is a VM, a
46+
remote host, or any mount whose root differs from your project. That is configured
47+
under **Settings | PHP | Servers**, and it is the usual reason breakpoints are
48+
ignored.
4749

4850
Over HTTP that is all you need — PhpStorm matches the connection to a server entry
4951
by the URL that was requested. On the command line there is no URL to match on, so

‎docs/integrations/vs-code.md‎

Lines changed: 140 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -2,8 +2,144 @@
22
title: VS Code
33
---
44

5-
Debug PHP in Visual Studio Code using the PHP Debug extension — configuration and troubleshooting.
5+
VS Code has no PHP debugging of its own, so there is one thing to install: the
6+
**PHP Debug** extension, which is the piece that speaks the protocol. Once it is
7+
there, its defaults already match ours — it listens on port `9003`, which is where
8+
the debugger connects.
69

7-
:::note
8-
This page is a work in progress — full documentation is coming soon.
9-
:::
10+
This page follows the [User Guide](../user-guide/starting-the-debugger.md) section
11+
by section, saying what each one looks like in VS Code.
12+
13+
**Extension:** [PHP Debug on the Marketplace](https://marketplace.visualstudio.com/items?itemName=xdebug.php-debug)
14+
· [source and settings reference](https://github.com/xdebug/vscode-php-debug)
15+
16+
## Starting the debugger
17+
18+
[Guide: Starting the Debugger](../user-guide/starting-the-debugger.md)
19+
20+
There is nothing to start on our side. In VS Code, open the **Run and Debug** view,
21+
add a PHP configuration if you have not already, and start the one called **Listen
22+
for Xdebug**. That is the switch: start it when you want to debug, stop it when you
23+
are finished.
24+
25+
The configuration it generates needs no changes to work here:
26+
27+
```json
28+
{
29+
"name": "Listen for Xdebug",
30+
"type": "php",
31+
"request": "launch",
32+
"port": 9003
33+
}
34+
```
35+
36+
Its `stopOnEntry` option breaks at the first line of every script. That is
37+
occasionally useful and usually not what you want, especially here, where every
38+
request arrives.
39+
40+
**VS Code docs:** [Start a debugging session](https://code.visualstudio.com/docs/debugtest/debugging#_start-a-debugging-session)
41+
42+
## Connecting to a client
43+
44+
[Guide: Connecting to a Client](../user-guide/connecting-to-a-client.md)
45+
46+
VS Code's debug port is the `port` setting in your launch configuration, and
47+
defaults to `9003`. If you change it there, change
48+
[`php_debugger.client_port`](../reference/settings.md#php_debuggerclient_port) to
49+
match.
50+
51+
Whenever the paths the debugger reports are not the paths on your own machine, add
52+
`pathMappings` so VS Code can turn one into the other. A container is the common
53+
case, but so is a VM, a remote host, or any mount whose root differs from your
54+
workspace. It is written server path first:
55+
56+
```json
57+
"pathMappings": {
58+
"/var/www/html": "${workspaceFolder}"
59+
}
60+
```
61+
62+
Getting this wrong is the usual reason breakpoints are ignored: the session
63+
connects, and nothing ever stops.
64+
65+
## Breakpoints
66+
67+
[Guide: Breakpoints](../user-guide/breakpoints.md)
68+
69+
Click the gutter beside a line to set one. Right-click for a condition or a hit
70+
count, and use the **Breakpoints** panel for the full list, including exception
71+
breakpoints and function breakpoints by name.
72+
73+
VS Code also has **logpoints** — a breakpoint that prints a message instead of
74+
stopping. It is a comfortable middle ground when you want to watch a value go past
75+
without pausing on every iteration.
76+
77+
**VS Code docs:** [Breakpoints](https://code.visualstudio.com/docs/debugtest/debugging#_breakpoints)
78+
79+
## Step debugging
80+
81+
[Guide: Step Debugging](../user-guide/step-debugging.md)
82+
83+
The debug toolbar carries the four actions the guide describes — Continue, Step
84+
Over, Step Into and Step Out — and **Run to Cursor** is on the editor's context
85+
menu.
86+
87+
One default worth knowing: the extension's `skipFiles` is set to `**/vendor/**`, so
88+
stepping walks over your dependencies rather than into them. That is usually what
89+
you want, and it is the first thing to check when a step seems to skip past
90+
something it should have entered.
91+
92+
**VS Code docs:** [Debug actions](https://code.visualstudio.com/docs/debugtest/debugging#_debug-actions)
93+
94+
## Inspect variables
95+
96+
[Guide: Inspect Variables](../user-guide/inspect-variables.md)
97+
98+
The **Variables** panel shows what is in scope and the **Call Stack** panel shows
99+
the frames. Selecting a frame repoints the variables panel at that frame, which is
100+
the habit worth forming.
101+
102+
Hovering a variable in the editor shows its value without going to the panel at
103+
all.
104+
105+
**VS Code docs:** [Data inspection](https://code.visualstudio.com/docs/debugtest/debugging#_data-inspection)
106+
107+
## Watches and edits
108+
109+
[Guide: Watches and Edits](../user-guide/watches-and-edits.md)
110+
111+
The **Watch** panel holds expressions re-evaluated at every stop, and the **Debug
112+
Console** handles one-off evaluation. Both run real PHP inside the paused request,
113+
so the guide's warnings about side effects apply exactly as written.
114+
115+
To change a value, double-click it in the Variables panel, or choose **Set Value**
116+
from its context menu.
117+
118+
**VS Code docs:** [Debug Console](https://code.visualstudio.com/docs/debugtest/debugging#_debug-console-repl)
119+
120+
## Logging
121+
122+
[Guide: Logging](../user-guide/logging.md)
123+
124+
The **Debug Console** carries your script's output, and PHP's warnings and notices
125+
appear there as the request produces them. Nothing needs enabling on our side.
126+
127+
The extension's own `log` option is a different thing: setting it to `true` prints
128+
every protocol message between VS Code and the debugger into the same console.
129+
That is the editor-side equivalent of our
130+
[log level 5](../reference/settings.md#php_debuggerlog_level), and it is for
131+
diagnosing the conversation rather than your code.
132+
133+
## Troubleshooting
134+
135+
[Guide: Troubleshooting](../user-guide/troubleshooting.md)
136+
137+
If a session never arrives, check the two things that are VS Code's rather than
138+
ours: that the **Listen for Xdebug** configuration is actually running, and that
139+
`pathMappings` matches where the code really lives. Our
140+
[troubleshooting page](../user-guide/troubleshooting.md) covers the debugger side,
141+
and the debug log at its default level will tell you whether a connection was
142+
attempted and where to.
143+
144+
Turning on the extension's `log` option at the same time gives you both halves of
145+
the conversation, which is usually enough to see which end is confused.

0 commit comments

Comments
 (0)