Skip to content

Commit 325902d

Browse files
Luc45Luc45
authored
Merge pull request #81 from woocommerce/26-04/qit-env-xdebug
Add Xdebug documentation
2 parents 358dc11 + e8cd641 commit 325902d

6 files changed

Lines changed: 197 additions & 0 deletions

File tree

‎docs/configuration/environments.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -131,6 +131,10 @@ Environments can extend other environments to reduce duplication:
131131
"extends": "base",
132132
"object_cache": true
133133
},
134+
"debug": {
135+
"extends": "base",
136+
"xdebug": true
137+
},
134138
"staging": {
135139
"extends": "base",
136140
"wp": "rc",

‎docs/configuration/qit-json.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -113,6 +113,7 @@ Define reusable WordPress/PHP/WooCommerce combinations:
113113
| `plugins` | Additional plugins | See below |
114114
| `themes` | Additional themes | Similar to plugins |
115115
| `object_cache` | Enable Redis | `true`, `false` |
116+
| `xdebug` | Enable [Xdebug](/docs/environment/xdebug) | `true`, `"profile"`, `"debug,develop"` |
116117
| `php_extensions` | PHP extensions | `["imagick", "redis"]` |
117118
| `volumes` | Docker volume mappings | `["/local/path:/container/path"]` |
118119
| `envs` | Environment variables | `{"WP_DEBUG": "true"}` |

‎docs/environment/development-workflow.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -185,6 +185,10 @@ This will:
185185

186186
## Debugging Failed Tests
187187

188+
### PHP step debugging with Xdebug
189+
190+
For PHP-level debugging (breakpoints, variable inspection, profiling), see the [Xdebug guide](./xdebug.md). Start an environment with `qit env:up --xdebug` and your IDE will catch breakpoints on every request.
191+
188192
### Getting Context from Failed Tests
189193

190194
When tests fail, get AI-friendly context:

‎docs/environment/introduction.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -48,6 +48,16 @@ qit env:up \
4848

4949
This command creates an environment running PHP 8.3, the latest release candidate of WordPress, and includes Gutenberg and Contact Form 7 plugins by default.
5050

51+
### Debugging with Xdebug
52+
53+
Enable step debugging, profiling, or tracing with a single flag:
54+
55+
```qitbash
56+
qit env:up --xdebug
57+
```
58+
59+
See [Xdebug debugging](./xdebug.md) for IDE setup, profiling, and all available modes.
60+
5161
## Using configuration files
5262

5363
Create a `qit.json` file in your project directory:

‎docs/environment/xdebug.md‎

Lines changed: 177 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,177 @@
1+
---
2+
description: "Guide to PHP debugging in QIT environments with Xdebug. Covers step debugging (breakpoints, variable inspection), profiling (cachegrind), and tracing. Explains --xdebug flag usage, IDE setup for PhpStorm and VS Code, path mappings, output directory for profile/trace files, qit.json configuration, and advanced options (port override via XDEBUG_CONFIG, custom ini via --volume)."
3+
---
4+
5+
# Xdebug debugging
6+
7+
## Introduction
8+
9+
QIT environments include Xdebug pre-installed but disabled by default. The `--xdebug` flag activates it on demand with zero configuration, enabling:
10+
11+
- **Step debugging** — set breakpoints, inspect variables, step through code
12+
- **Profiling** — generate cachegrind files to find performance bottlenecks
13+
- **Tracing** — log every function call for execution flow analysis
14+
15+
## Quick start
16+
17+
```qitbash
18+
qit env:up --xdebug
19+
```
20+
21+
This starts an environment with Xdebug in **debug** mode (step debugging). Your IDE can connect on port **9003** to set breakpoints and inspect PHP execution.
22+
23+
Verify it's working:
24+
25+
```bash
26+
docker exec <php_container> php -i | grep xdebug.mode
27+
# xdebug.mode => debug => debug
28+
```
29+
30+
The PHP container name is shown as `qit_env_php_<env_id>` in the environment output.
31+
32+
## Modes
33+
34+
### Debug (default)
35+
36+
Step debugging with breakpoints and variable inspection:
37+
38+
```qitbash
39+
qit env:up --xdebug
40+
```
41+
42+
### Profile
43+
44+
Generate cachegrind files for performance analysis:
45+
46+
```qitbash
47+
qit env:up --xdebug=profile
48+
```
49+
50+
Cachegrind files are saved to the **output directory** shown in the environment summary. Open them with [KCachegrind](https://kcachegrind.github.io/), [QCacheGrind](https://sourceforge.net/projects/qcachegrindwin/), or PhpStorm's built-in profiler.
51+
52+
### Trace
53+
54+
Log every function call with parameters and return values:
55+
56+
```qitbash
57+
qit env:up --xdebug=trace
58+
```
59+
60+
Trace files are saved to the same output directory.
61+
62+
### Combined modes
63+
64+
Combine modes with commas:
65+
66+
```qitbash
67+
qit env:up --xdebug=debug,develop
68+
```
69+
70+
The `develop` mode enhances `var_dump()` output and error pages — useful alongside step debugging.
71+
72+
## IDE setup
73+
74+
When `--xdebug` is used, the environment summary shows path mappings:
75+
76+
```
77+
Xdebug: Enabled (mode=debug, port=9003)
78+
Output dir: /path/to/temporary-envs/e2e-qitenvXXX/xdebug-output
79+
Path mappings (host -> container):
80+
/home/user/my-plugin -> /var/www/html/wp-content/plugins/my-plugin
81+
```
82+
83+
### PhpStorm
84+
85+
1. Go to **Settings → PHP → Debug** and set Xdebug port to **9003**
86+
2. Go to **Settings → PHP → Servers**, add a server:
87+
- Host: `localhost`
88+
- Port: the nginx port from the environment output
89+
- Debugger: Xdebug
90+
- Check **Use path mappings** and map your local plugin directory to its container path (shown in the environment output)
91+
3. Click **Start Listening for PHP Debug Connections** (phone icon in toolbar)
92+
4. Set a breakpoint and trigger a page load — PhpStorm will catch it
93+
94+
### VS Code
95+
96+
1. Install the [PHP Debug extension](https://marketplace.visualstudio.com/items?itemName=xdebug.php-debug)
97+
2. Create `.vscode/launch.json`:
98+
99+
```json
100+
{
101+
"version": "0.2.0",
102+
"configurations": [
103+
{
104+
"name": "Listen for Xdebug",
105+
"type": "php",
106+
"request": "launch",
107+
"port": 9003,
108+
"pathMappings": {
109+
"/var/www/html/wp-content/plugins/my-plugin": "${workspaceFolder}"
110+
}
111+
}
112+
]
113+
}
114+
```
115+
116+
3. Replace the path mapping with the paths shown in your environment output
117+
4. Start debugging (F5), set a breakpoint, trigger a page load
118+
119+
## Output directory
120+
121+
When Xdebug is enabled in any mode, an output directory is automatically mounted:
122+
123+
- **Container path:** `/tmp/xdebug-output`
124+
- **Host path:** shown in the environment summary as `Output dir`
125+
126+
This is where cachegrind files (profile mode) and trace files (trace mode) are written. The directory persists on the host after the environment is stopped, so you can analyze results after tearing down.
127+
128+
## Configuration via qit.json
129+
130+
Add Xdebug to your environment configuration:
131+
132+
```json
133+
{
134+
"environments": {
135+
"default": {
136+
"php": "8.3",
137+
"xdebug": true
138+
},
139+
"profiling": {
140+
"extends": "default",
141+
"xdebug": "profile"
142+
}
143+
}
144+
}
145+
```
146+
147+
- `"xdebug": true` — shorthand for debug mode
148+
- `"xdebug": "profile"` — specific mode
149+
- `"xdebug": "debug,develop"` — combined modes
150+
151+
CLI flags override the config: `qit env:up --xdebug=trace` overrides `"xdebug": true` in qit.json.
152+
153+
## Advanced
154+
155+
### Custom port
156+
157+
The default Xdebug port is 9003. To use a different port, pass the `XDEBUG_CONFIG` environment variable (which Xdebug reads natively):
158+
159+
```qitbash
160+
qit env:up --xdebug --env XDEBUG_CONFIG="client_port=9004"
161+
```
162+
163+
### Custom PHP configuration
164+
165+
To override any PHP or Xdebug setting, mount a custom ini file:
166+
167+
```qitbash
168+
qit env:up --xdebug --volume /path/to/my-xdebug.ini:/usr/local/etc/php/conf.d/zzz-custom.ini
169+
```
170+
171+
The `zzz-` prefix ensures it loads last and overrides all other ini files.
172+
173+
## Performance
174+
175+
Xdebug is **pre-installed in the Docker image but disabled by default** (`xdebug.mode=off`). When disabled, there is zero measurable performance overhead — it's safe for CI and production-like testing.
176+
177+
The `--xdebug` flag writes an ini override to enable the requested mode and restarts PHP-FPM. Without the flag, Xdebug never activates.

‎sidebars.js‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -102,6 +102,7 @@ const sidebars = {
102102
items: [
103103
'environment/introduction',
104104
'environment/development-workflow',
105+
'environment/xdebug',
105106
'environment/tunnel',
106107
'environment/persistent-tunnel',
107108
'environment/environment-variables',

0 commit comments

Comments
 (0)