elixforms-web-services/docs/debug-api-vscode-docker.md

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
• .vscode/settings.json - impostazioni VS Code

Il container espone:

• porta 8000 per HTTP
• porta 9003 per Xdebug

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

1. Apri la sezione Run and Debug in VS Code (Ctrl+Shift+D)
2. Seleziona la configurazione: Debug PHP in Docker
3. Premi F5 per avviare il debugger

4. Imposta un breakpoint e testa

1. Aggiungi un breakpoint in un controller, ad esempio:

   src/Api/Controllers/V1/UsersController.php
   

2. Richiama un endpoint tramite browser:

    http://localhost:8000/api/users
   

3. Oppure usa curl con il trigger Xdebug:

   curl -H "XDEBUG_TRIGGER: 1" http://localhost:8000/api/users
   

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 la configurazione client_host nel Dockerfile punti a host.docker.internal
• Verifica che la porta 9003 sia disponibile e non bloccata dal firewall

Il container non si avvia

• Assicurati che Docker Desktop sia in esecuzione
• Verifica che le porte 8000 e 9003 non siano 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

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