Skip to content

Commit fcb865c

Browse files
carlos-granadoscarlos-granados
committed
write the settings reference page
1 parent c26fff1 commit fcb865c

3 files changed

Lines changed: 310 additions & 10 deletions

File tree

‎docs/reference/configuration-file.md‎

Lines changed: 0 additions & 9 deletions
This file was deleted.

‎docs/reference/settings.md‎

Lines changed: 309 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,309 @@
1+
---
2+
title: Settings
3+
---
4+
5+
Every setting PHP Debugger supports, in alphabetical order.
6+
7+
All of them can also be written with an `xdebug.` prefix instead of
8+
`php_debugger.` — the two names share one value. Where both are set explicitly,
9+
`php_debugger.` wins.
10+
11+
Each setting says where it can be set:
12+
13+
- **Anywhere** — `php.ini`, a `conf.d` file, per-directory config, or at runtime
14+
with `ini_set()`.
15+
- **System and per-directory** — `php.ini` and per-directory config such as
16+
`.htaccess` or a vhost, but not at runtime.
17+
- **`php.ini` only** — read once at startup, so changing it later has no effect.
18+
19+
## `php_debugger.client_discovery_header`
20+
21+
| Type | Default | Set in |
22+
| --- | --- | --- |
23+
| String | `HTTP_X_FORWARDED_FOR,REMOTE_ADDR` | Anywhere |
24+
25+
The request headers consulted, in order, when
26+
[`discover_client_host`](#php_debuggerdiscover_client_host) is on. The first one
27+
present supplies the address; if it holds a comma-separated list, the first entry
28+
is used.
29+
30+
```ini
31+
php_debugger.client_discovery_header=HTTP_X_REAL_IP,REMOTE_ADDR
32+
```
33+
34+
## `php_debugger.client_host`
35+
36+
| Type | Default | Set in |
37+
| --- | --- | --- |
38+
| String | `localhost` | Anywhere |
39+
40+
The machine the debugger connects out to. The default works when your editor and
41+
your code run on the same machine; from inside a container it needs an address that
42+
reaches your host.
43+
44+
```ini
45+
php_debugger.client_host=host.docker.internal
46+
```
47+
48+
## `php_debugger.client_port`
49+
50+
| Type | Default | Set in |
51+
| --- | --- | --- |
52+
| Integer | `9003` | Anywhere |
53+
54+
The port your editor is listening on. Change it only if something else already has
55+
`9003`, and make your editor match.
56+
57+
```ini
58+
php_debugger.client_port=9004
59+
```
60+
61+
## `php_debugger.cloud_id`
62+
63+
| Type | Default | Set in |
64+
| --- | --- | --- |
65+
| String | empty | `php.ini` only |
66+
67+
Relays the session through Xdebug Cloud rather than connecting directly, for when
68+
the debugger cannot reach your machine at all. Setting it takes priority over
69+
`client_host`. See the [Xdebug Cloud documentation](https://xdebug.org/docs/cloud).
70+
71+
```ini
72+
php_debugger.cloud_id=your-id-here
73+
```
74+
75+
## `php_debugger.connect_timeout_ms`
76+
77+
| Type | Default | Set in |
78+
| --- | --- | --- |
79+
| Integer | `200` | Anywhere |
80+
81+
How long, in milliseconds, a single connection attempt may take. Every attempt that
82+
finds nothing listening costs the request this much, which is why the default is
83+
small.
84+
85+
```ini
86+
php_debugger.connect_timeout_ms=500
87+
```
88+
89+
## `php_debugger.control_socket`
90+
91+
| Type | Default | Set in |
92+
| --- | --- | --- |
93+
| String | `default` | Anywhere. Linux only |
94+
95+
Opens a per-process socket that lets an external tool inspect a running request or
96+
pause it. `default` and `time` both poll every 25ms; `no` turns it off. On a system
97+
without a usable TSC clock, `default` disables itself and `time` falls back to
98+
100ms.
99+
100+
```ini
101+
php_debugger.control_socket=no
102+
```
103+
104+
## `php_debugger.discover_client_host`
105+
106+
| Type | Default | Set in |
107+
| --- | --- | --- |
108+
| Boolean | `0` | Anywhere |
109+
110+
Works the client address out from the incoming HTTP request instead of using
111+
`client_host`. Only the host is discovered — the port is always `client_port` — and
112+
`client_host` is still used as a fallback.
113+
114+
Because the headers it reads are supplied by the request, only enable this behind a
115+
proxy you control.
116+
117+
```ini
118+
php_debugger.discover_client_host=1
119+
```
120+
121+
## `php_debugger.idekey`
122+
123+
| Type | Default | Set in |
124+
| --- | --- | --- |
125+
| String | empty | Anywhere |
126+
127+
An identifier sent to your editor when the session opens, so a client handling
128+
several sessions can tell them apart. Most setups never need it.
129+
130+
```ini
131+
php_debugger.idekey=my-project
132+
```
133+
134+
## `php_debugger.log`
135+
136+
| Type | Default | Set in |
137+
| --- | --- | --- |
138+
| String | empty | Anywhere |
139+
140+
The file where the debugger writes its own log. Appended to rather than truncated,
141+
and flushed line by line, so a crash does not cost you the last entry. Leave it
142+
unset outside of debugging: it grows without limit and records paths, trigger
143+
values and protocol traffic.
144+
145+
```ini
146+
php_debugger.log=/tmp/php-debugger.log
147+
```
148+
149+
## `php_debugger.log_level`
150+
151+
| Type | Default | Set in |
152+
| --- | --- | --- |
153+
| Integer | `7` | Anywhere |
154+
155+
How much is written to the log. A threshold — everything at or below the number is
156+
recorded.
157+
158+
| Value | Records |
159+
| --- | --- |
160+
| `0` | Critical failures only. |
161+
| `1` | Errors as well. |
162+
| `3` | Warnings as well. |
163+
| `5` | Every protocol message in both directions. |
164+
| `7` | Connections, sessions and breakpoint resolution. The default. |
165+
| `10` | Everything, including each trigger check and configuration decision. |
166+
167+
```ini
168+
php_debugger.log_level=10
169+
```
170+
171+
## `php_debugger.mode`
172+
173+
| Type | Default | Set in |
174+
| --- | --- | --- |
175+
| String | `debug` | `php.ini` only |
176+
177+
Whether the debugger does anything at all. Two values are accepted: `debug`, and
178+
`off` for no overhead rather than very little. Any other value is ignored: a
179+
message is logged and the mode stays `debug`.
180+
181+
```ini
182+
php_debugger.mode=off
183+
```
184+
185+
## `php_debugger.on_demand_debugging_enabled`
186+
187+
| Type | Default | Set in |
188+
| --- | --- | --- |
189+
| Boolean | `0` | `php.ini` only |
190+
191+
Allows the debugger to attach part-way through a request, which is what makes
192+
`php_debugger_break()` and `php_debugger_connect_to_client()` work when no session
193+
is running.
194+
195+
The cost is high: every request must be compiled with debugging instrumentation
196+
whether or not it ends up being debugged, which gives away roughly half of the
197+
near-zero overhead you would otherwise have. Leave it off unless you need it.
198+
199+
```ini
200+
php_debugger.on_demand_debugging_enabled=1
201+
```
202+
203+
## `php_debugger.path_mapping`
204+
205+
| Type | Default | Set in |
206+
| --- | --- | --- |
207+
| Boolean | `0` | Anywhere |
208+
209+
Enables server-side translation between the paths the running machine sees and the
210+
paths your editor knows. With it off, paths are passed through unchanged.
211+
212+
Most setups do not need this — mapping is normally configured in the editor, which
213+
is where to look first if breakpoints in a container are being ignored.
214+
215+
```ini
216+
php_debugger.path_mapping=1
217+
```
218+
219+
## `php_debugger.start_upon_error`
220+
221+
| Type | Default | Set in |
222+
| --- | --- | --- |
223+
| String | `default` | System and per-directory |
224+
225+
Whether an error should start a debugging session when none is running. Only `yes`
226+
enables it; `default` and `no` both leave it off. It also needs
227+
[`on_demand_debugging_enabled`](#php_debuggeron_demand_debugging_enabled), since
228+
starting mid-request is exactly what that setting permits.
229+
230+
```ini
231+
php_debugger.start_upon_error=yes
232+
```
233+
234+
## `php_debugger.start_with_request`
235+
236+
| Type | Default | Set in |
237+
| --- | --- | --- |
238+
| String | `yes` | System and per-directory |
239+
240+
When a session begins.
241+
242+
| Value | Meaning |
243+
| --- | --- |
244+
| `yes` | Every request starts one. The default. |
245+
| `no` | Never. |
246+
| `trigger` | Only when a trigger is present in the request. |
247+
248+
`yes` is the right choice here. `trigger` exists to keep a heavyweight debugger out
249+
of the way, which is not a problem this one has.
250+
251+
```ini
252+
php_debugger.start_with_request=trigger
253+
```
254+
255+
## `php_debugger.trigger_value`
256+
257+
| Type | Default | Set in |
258+
| --- | --- | --- |
259+
| String | empty | System and per-directory |
260+
261+
Turns the trigger into a shared secret: with a value set, a trigger only counts if
262+
it matches, and one that does not is refused and logged. Several secrets can be
263+
accepted at once by separating them with commas.
264+
265+
Only relevant when `start_with_request` is `trigger`.
266+
267+
```ini
268+
php_debugger.trigger_value=letmein,alsofine
269+
```
270+
271+
## `php_debugger.var_display_max_children`
272+
273+
| Type | Default | Set in |
274+
| --- | --- | --- |
275+
| Integer | `128` | Anywhere |
276+
277+
How many elements of an array or object are sent in one go. Your editor can raise
278+
this for its own session, and usually does, in which case its value wins.
279+
280+
```ini
281+
php_debugger.var_display_max_children=256
282+
```
283+
284+
## `php_debugger.var_display_max_data`
285+
286+
| Type | Default | Set in |
287+
| --- | --- | --- |
288+
| Integer | `512` | Anywhere |
289+
290+
How many bytes of a string are sent before it is truncated. Also overridable by
291+
your editor.
292+
293+
```ini
294+
php_debugger.var_display_max_data=2048
295+
```
296+
297+
## `php_debugger.var_display_max_depth`
298+
299+
| Type | Default | Set in |
300+
| --- | --- | --- |
301+
| Integer | `3` | Anywhere |
302+
303+
How many levels deep into a nested structure are sent in one go. Expanding a node
304+
in your editor fetches the next layer, so this is a batch size rather than a limit
305+
on what you can reach. Also overridable by your editor.
306+
307+
```ini
308+
php_debugger.var_display_max_depth=5
309+
```

‎sidebars.js‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -47,9 +47,9 @@ const sidebars = {
4747
label: 'Reference',
4848
collapsed: false,
4949
items: [
50+
'reference/settings',
5051
'reference/cli-options',
5152
'reference/environment-variables',
52-
'reference/configuration-file',
5353
'reference/debug-protocol',
5454
],
5555
},

0 commit comments

Comments
 (0)