Setup Xdebug in Cursor, VS Code & PhpStorm on macOS (Port 9003)

1-Click Xdebug 3 Setup on Native macOS PHP

Unlike Docker setups where client_host must point to host.docker.internal and complex pathMappings break breakpoints, Stratos runs PHP natively on macOS. Breakpoints map directly to your local filesystem paths on 127.0.0.1:9003.

Step 1: Enable Xdebug in Stratos

1. Open Stratos → Settings → PHP Extensions.
2. Toggle Xdebug ON for your active PHP version (8.1–8.5).
3. Stratos automatically writes the Xdebug 3 directives and restarts the corresponding PHP-FPM pool:

zend_extension=xdebug.so
xdebug.mode=develop,debug
xdebug.start_with_request=yes
xdebug.client_port=9003
xdebug.client_host=127.0.0.1
xdebug.idekey=PHPSTORM

Step 2: Configure Cursor or VS Code

1. Install the PHP Debug extension (xdebug.php-debug) from the Extensions marketplace in Cursor or VS Code.
2. Create or update .vscode/launch.json in your project root:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Listen for Xdebug (Stratos 9003)",
      "type": "php",
      "request": "launch",
      "port": 9003,
      "hostname": "127.0.0.1"
    }
  ]
}

Press F5 in Cursor or VS Code, set a breakpoint in a Laravel controller or route, and reload https://your-app.test.

Step 3: Configure PhpStorm

1. Go to Settings → PHP → Debug and verify Xdebug port is 9003 and Can accept external connections is checked.
2. Click the Start Listening for PHP Debug Connections telephone icon in the PhpStorm toolbar.
3. Reload your .test site—PhpStorm catches the request automatically with idekey=PHPSTORM.

Troubleshooting Breakpoints Not Hitting

• Confirm another process (like Docker/PHP-FPM leftover) is not bound to port 9003 with lsof -i :9003.
• For performance-sensitive runs when not debugging, toggle Xdebug OFF in Stratos or use the built-in SPX Profiler (?SPX_KEY=dev&SPX_UI_URI=/) for CPU and memory flame graphs with near-zero idle overhead.

Full Xdebug & SPX Reference → Pair with Cursor Local AI MCP →