fix xdebug

docs/debug-api-vscode-docker.md

@@ -15,12 +15,11 @@ 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:
+Il servizio usa:
 
 - **porta `8000`** per HTTP
-- **porta `9003`** per Xdebug
+- **porta host `9013`** per la connessione in uscita di Xdebug verso VS Code
 
 ## 2. Avvia il container
 
@@ -39,7 +38,7 @@ 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**
+2. Seleziona la configurazione: **API - Listen for Xdebug**
 3. Premi **F5** per avviare il debugger
 
 ## 4. Imposta un breakpoint e testa
@@ -56,12 +55,15 @@ http://localhost:8000
     http://localhost:8000/api/users
     ```
 
-3. Oppure usa curl con il trigger Xdebug:
+3. Esegui la stessa richiesta con curl:
 
     ```bash
-    curl -H "XDEBUG_TRIGGER: 1" http://localhost:8000/api/users
+    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
@@ -69,13 +71,14 @@ Il debugger dovrebbe fermarsi sul breakpoint e permetterti di ispezionare le var
 ### 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
+- 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 le porte 8000 e 9003 non siano già in uso
+- 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
@@ -84,6 +87,19 @@ Il debugger dovrebbe fermarsi sul breakpoint e permetterti di ispezionare le var
 - 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:
+
+```bash
+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