# Debugging with XDebug in Docker

The PHP 7.4 and 8.3 Docker images include **XDebug 3**. This guide explains how to enable it and attach your IDE.

## Enabling XDebug

By default XDebug is **off** so the app is not slowed down.

- **Option A — env when starting:**  
  `XDEBUG_MODE=debug docker compose --profile php74 up`  
  or set in `.env`: `XDEBUG_MODE=debug`

- **Option B — trigger by request:**  
  XDebug is configured with `start_with_request=trigger`. Use your IDE’s “Start listening for PHP Debug connections” and then trigger a request (e.g. with a browser extension like “Xdebug helper” or a query param). No need to set `XDEBUG_MODE` for every request.

After changing `XDEBUG_MODE`, restart the app container.

## IDE configuration

### Port

XDebug connects back to your machine on port **9003** (DBGp). Your IDE must listen on **9003**.

### PHPStorm

1. **Settings → PHP → Debug:**  
   - Xdebug: Debug port **9003**.  
   - “Can accept external connections” checked if needed.

2. **Settings → PHP → Servers:**  
   - Add a server with name matching your project.  
   - Host: `localhost` (or your host).  
   - Port: `8080` (php74) or `8081` (php83).  
   - Use path mappings: project root → `/var/www/html` in the container.

3. **Run → Start Listening for PHP Debug Connections** (phone icon).

4. Open `http://localhost:8080/report.php` (or 8081 for php83); execution should stop at breakpoints.

### VS Code

1. Install the **PHP Debug** extension (e.g. “PHP Debug” by Xdebug / Felix Becker).

2. Add to `.vscode/launch.json`:

```json
{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Listen for Xdebug (Docker)",
      "type": "php",
      "request": "launch",
      "port": 9003,
      "pathMappings": {
        "/var/www/html": "${workspaceFolder}"
      }
    }
  ]
}
```

3. Start debugging (“Run and Debug” → “Listen for Xdebug (Docker)”).

4. Load `http://localhost:8080/...` or `http://localhost:8081/...`; breakpoints should hit.

## Host for XDebug (Docker → host)

The containers use **`host.docker.internal`** as the IDE host (works on Docker Desktop for Mac/Windows). On Linux, if that hostname is not available, set in the Dockerfile or at runtime:

- `xdebug.client_host=host.docker.internal`  
  or your host’s IP (e.g. `172.17.0.1` or the IP of your machine on the Docker network).

## Summary

| Item        | Value                    |
| ----------- | ------------------------ |
| XDebug port | 9003                      |
| Client host | host.docker.internal      |
| Trigger     | trigger (or set XDEBUG_MODE=debug) |
| Path in container | /var/www/html        |