Per-site Xdebug on Mac.

Xdebug is the most useful tool in PHP and also the most expensive to leave loaded. With step debugging enabled, every request pays for it, and a page that renders in 80ms can take noticeably longer. Leave it on globally and your whole local setup feels slow; turn it off globally and you're editing ini files and restarting PHP every time you want a breakpoint.

Bothy runs each site in its own php-fpm pool (see multiple PHP versions), which means Xdebug can be switched on for one site's pool without touching the others. The site you're debugging gets Xdebug; the rest don't notice.

• Installed on first use. The first time you enable Xdebug on a site, Bothy installs it for that site's PHP version. Nothing to pecl install.
• Port 9003 on 127.0.0.1. This is Xdebug 3's default, and what current PhpStorm and VS Code expect, so IDE defaults usually just work. (Xdebug 2 used 9000, which clashed with php-fpm's traditional port; if an old tutorial says 9000, that's why.)
• debug,develop mode. debug is step debugging. develop adds Xdebug's development helpers: more readable var_dump() output and stack traces on errors and warnings.

Files are served straight from your folders on your Mac, so the paths PHP reports are the paths your IDE has open. There are no path mappings to maintain, unlike debugging into a container or VM.

1. In Settings → PHP → Debug, check the Xdebug port is 9003 (the default in current versions).
2. Click Start Listening for PHP Debug Connections (the telephone icon in the toolbar).
3. Set a breakpoint and load the page at https://shop.test. On the first connection PhpStorm offers to create a server entry for shop.test; accept it. Because files are local, no path mappings are needed.

PhpStorm's general Xdebug documentation covers the rest; the Xdebug on Mac guide goes into more detail.

1. Install the PHP Debug extension (by Xdebug).
2. Add a launch configuration that listens on 9003. The extension's generated launch.json includes one called Listen for Xdebug:

   {
     "name": "Listen for Xdebug",
     "type": "php",
     "request": "launch",
     "port": 9003
   }

3. Start that configuration, set a breakpoint and load the site. Open the site's folder as the workspace so paths match without any pathMappings.

Cursor, Windsurf and other VS Code forks use the same extension.

• Is Xdebug on for this site? The toggle is per site, so check it's the site you're loading, not a sibling on the same PHP version.
• Is the IDE listening on 9003? Only one program can listen on that port; two IDEs open at once will fight over it.
• No trigger needed. Bothy sets xdebug.start_with_request=yes, so with Xdebug on for a site every request starts a session. If nothing arrives, the IDE isn't listening on 9003 or the path mappings are wrong.
• Check the PHP log for Xdebug's own connection messages: bothy logs shop --kind php.