Debug delle API PHP in VS Code con Docker

Queste istruzioni permettono di fare debug delle API PHP servite con Docker direttamente da Visual Studio Code.

Prerequisiti

Docker Desktop installato e in esecuzione
Visual Studio Code
Estensione PHP per VS Code

1. Configurazione del progetto

Il progetto contiene già i file necessari per il debug:

.docker/php/Dockerfile - container PHP con Xdebug
docker-compose.yml - configurazione Docker
.vscode/launch.json - configurazione di avvio VS Code

Il servizio usa:

porta 8000 per HTTP
porta host 9013 per la connessione in uscita di Xdebug verso VS Code

2. Avvia il container

Dalla root del progetto esegui:

docker compose up --build

Il server PHP sarà disponibile su:

http://localhost:8000

3. Avvia il debug in VS Code

Apri la sezione Run and Debug in VS Code (Ctrl+Shift+D)
Seleziona la configurazione: API - Listen for Xdebug
Premi F5 per avviare il debugger

4. Imposta un breakpoint e testa

Aggiungi un breakpoint in un controller, ad esempio:
```
src/Api/Controllers/V1/UsersController.php
```
Richiama un endpoint tramite browser:
```
 http://localhost:8000/api/users
```
Esegui la stessa richiesta con curl:
```
curl http://localhost:8000/api/users
```
xdebug.start_with_request=yes avvia il tentativo di connessione per ogni richiesta, quindi non serve aggiungere XDEBUG_TRIGGER.

Il debugger dovrebbe fermarsi sul breakpoint e permetterti di ispezionare le variabili.

5. Risoluzione dei problemi

VS Code non si ferma sul breakpoint

Verifica che Xdebug sia abilitato nel container
Controlla che xdebug.client_host in .docker/php/xdebug.ini punti a host.docker.internal
Verifica che la porta 9013 sia disponibile e non bloccata dal firewall

Il container non si avvia

Assicurati che Docker Desktop sia in esecuzione
Verifica che la porta HTTP 8000 non sia già in uso
Controlla i log di Docker per errori specifici

"Failed to fetch" dalle richieste del frontend

Verifica che il frontend abbia il CORS correttamente configurato
Controlla che allowed_origins in config/config.php includa l'origine del frontend
Testa con l'endpoint di diagnostica /cors-check

Diagnostica avanzata dei breakpoint

Il log Xdebug è scritto nel container in /tmp/xdebug.log. Per analizzare anche la registrazione e la risoluzione dei breakpoint, imposta temporaneamente xdebug.log_level=10 in .docker/php/xdebug.ini, riavvia il container e usa:

docker exec elixforms-ws tail -f /tmp/xdebug.log

Al termine ripristina xdebug.log_level=7, perché il livello 10 produce molti dettagli per ogni riga eseguita.

Note

La procedura di debug influisce solo sulla sessione VS Code, il server continua a funzionare normalmente
È possibile debug con i breakpoint condizionali per limitare i fermi
Usa la console di debug di VS Code per eseguire comandi PHP durante il debug

3.1 KiB Raw Blame History