write the settings reference page

[carlos-granados]

First page of the Reference section. Renames the configuration-file placeholder to settings and writes it, listing every setting alphabetically with type, default, where it can be set, an explanation and an ini example.

Placed first in Reference, ahead of CLI Options.

Read from origin/main, not the local checkout. The working copy sits on a feature branch whose xdebug.c differs from main, including four settings main has that the branch does not.

24 settings exist on main; 19 are documented. The page's headings were diffed against every "php_debugger.*" string in origin/main:xdebug.c — exact match before the five below were dropped, and confirmed alphabetical. Note that start_with_request, start_upon_error and control_socket use PHP_INI_ENTRY_EX rather than STD_PHP_INI_ENTRY, so a naive grep misses them.

The five omitted are registered and stored but never read anywhere in src/ — file_link_format, filename_format, max_nesting_level, output_dir and use_compression. They belong to features this project does not have. They are left undocumented rather than described as inert.

Also settled from the source:

• both prefixes share one value, and php_debugger. wins only when explicitly set
• start_upon_error is enabled by yes alone; default and no both mean off
• an unrecognised mode is logged and falls back to debug (xdebug.c:510), confirmed by running php -d php_debugger.mode=bogus, which still reports the step debugger as enabled

[github-actions]

PR Preview Action v1.8.1
Preview removed because the pull request was closed.
2026-09-09 07:37 UTC