replace configuration page with starting the debugger guide

[carlos-granados]

Removes the Configuration page and adds Starting the Debugger as the first page of the User Guide.

It opens by recommending the defaults, then covers the cases where you want something else: php_debugger.mode, the start_with_request values, on-demand debugging, and triggers. It closes with the two habits that keep overhead low — remove breakpoints when done, disconnect when you stop.

Verified against the running extension

Every behaviour described was checked on a freshly pulled 0.3.0 image rather than read from source alone:

• mode accepts debug and off; a removed mode logs an error and falls back, and PHP still runs.
• start_with_request accepts yes (default), no, trigger.
• With no and on-demand off, connecting mid-request returns false. Enabling on_demand_debugging_enabled makes it work, and logs that OPcache is bypassed for every request.
• Triggers are checked as XDEBUG_TRIGGER → PHP_DEBUGGER_TRIGGER → XDEBUG_SESSION → PHP_DEBUGGER_SESSION, each looked up in the environment, then $_GET, $_POST, $_COOKIE. With no trigger_value any value activates; with one set, a mismatch is refused and logged. Comma-separated multi-secret confirmed in source.

The page it replaces was wrong

The old Configuration page claimed start_with_request defaults to trigger (it is yes) and client_host to 127.0.0.1 (it is localhost).

Known gap

The page names php_debugger_connect_to_client() and php_debugger_break(). Neither exists in 0.3.0 — only php_debugger_info is defined as an alias, confirmed at runtime and in php_xdebug.stub.php. Documented on the understanding that the aliases are coming; until then those two calls would fatal.

The three pages that linked to Configuration now point elsewhere. The Reference section still has Configuration File and Environment Variables placeholders.

[github-actions]

PR Preview Action v1.8.1
Preview removed because the pull request was closed.
2026-08-25 16:43 UTC