Skip to content

xdebug.md

Latest commit

 

History

History
126 lines (86 loc) · 3.25 KB

xdebug.md

File metadata and controls

126 lines (86 loc) · 3.25 KB
Raw

Xdebug

Xdebug is the PHP debugger expected by the VS Code extension already installed by this setup.

Keep Xdebug disabled by default for normal PHP and Composer work. Enable it only when debugging, profiling, or collecting Xdebug-specific diagnostics.

Xdebug configuration loaded by Homebrew PHP

Installation

Install Xdebug for the active Homebrew PHP version:

pecl install xdebug

Find the active PHP configuration directory:

php --ini
php -i | grep '^extension_dir'

Homebrew PHP configuration commonly lives under:

$(brew --prefix)/etc/php/<version>/conf.d

Disabled by default

Keep a disabled config available, but do not load it automatically:

; xdebug.ini.disabled
zend_extension=xdebug
xdebug.mode=debug,develop
xdebug.start_with_request=yes
xdebug.client_host=127.0.0.1
xdebug.client_port=9003

In this setup you do not edit these files by hand. MacDevSetup ships a helper that manages them for you:

mac php xdebug status    # show whether Xdebug is enabled or disabled
mac php xdebug enable     # activate Xdebug for a debugging session
mac php xdebug disable    # deactivate it again

mac php xdebug status showing a disabled config with the extension installed

The helper keeps 99-xdebug.ini.disabled as the reusable disabled template (created automatically on first run). enable copies it to 99-xdebug.ini in the active Homebrew PHP conf.d directory; disable removes that copy. The template is never moved or symlinked, so it always stays available. Restart the relevant PHP process (or symfony server:stop && symfony server:start) after toggling.

VS Code workflow

The recommended VS Code extensions include xdebug.php-debug.

Use port 9003, which is the Xdebug 3 default. In project workspaces, keep debug settings in the project's .vscode/launch.json rather than the global MacDevSetup VS Code settings.

For web debugging:

  1. Enable Xdebug in the PHP runtime used by the project.
  2. Start "Listen for Xdebug" in VS Code.
  3. Trigger the HTTP request, CLI command, or test that should break.

OrbStack and Docker

For PHP running inside containers, configure Xdebug in the container image or compose override, not in the host Homebrew PHP config.

Use the host name exposed by the container runtime when 127.0.0.1 does not point back to the Mac host. Keep container-specific path mappings in the project workspace.

Coverage boundary

Use Xdebug for debugging and profiling. Use PCOV for fast coverage when the project adopts it. Do not enable Xdebug coverage and PCOV in the same run.

Validation

Check whether Xdebug is loaded:

mac php xdebug status
php -v
php --ri xdebug

Check the active mode:

php -r 'echo ini_get("xdebug.mode"), PHP_EOL;'

Rollback

Deactivate the active config without uninstalling the extension:

mac php xdebug disable

Remove the extension entirely from the active PHP runtime:

pecl uninstall xdebug

Restart the relevant PHP process (or symfony server:stop && symfony server:start) so the change takes effect.

← Docs index · Project README