add skill for markdown

also move some files around

docs/debug-api-vscode-docker.md

@@ -8,7 +8,21 @@ Queste istruzioni permettono di fare debug delle API PHP servite con Docker dire
 - Visual Studio Code
 - Estensione PHP per VS Code
 
-## 1. Avvia il container
+## 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:
 
@@ -22,52 +36,56 @@ Il server PHP sarà disponibile su:
 http://localhost:8000
 ```
 
-## 2. Avvia il debug in VS Code
+## 3. Avvia il debug in VS Code
 
-Apri la sezione Run and Debug e seleziona la configurazione:
+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
 
-```text
-Debug PHP in Docker
-```
+## 4. Imposta un breakpoint e testa
 
-Poi premi F5.
+1. Aggiungi un breakpoint in un controller, ad esempio:
 
-## 3. Imposta un breakpoint
+    ```text
+    src/Api/Controllers/V1/UsersController.php
+    ```
 
-Aggiungi un breakpoint in un controller, ad esempio in:
+2. Richiama un endpoint tramite browser:
 
-```text
-src/Api/Controllers/V1/UsersController.php
-```
+   ```text
+    http://localhost:8000/api/users
+    ```
 
-Quindi richiama un endpoint come:
+3. Oppure usa curl con il trigger Xdebug:
 
-```text
-http://localhost:8000/api/users
-```
+    ```bash
+    curl -H "XDEBUG_TRIGGER: 1" http://localhost:8000/api/users
+    ```
 
-## 4. Se il debugger non parte
+Il debugger dovrebbe fermarsi sul breakpoint e permetterti di ispezionare le variabili.
 
-Prova a inviare la richiesta con il trigger Xdebug:
+## 5. Risoluzione dei problemi
 
-```bash
-curl -H "XDEBUG_TRIGGER: 1" http://localhost:8000/api/users
-```
+### VS Code non si ferma sul breakpoint
 
-## 5. Configurazione attesa
+- 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 progetto contiene già:
+### Il container non si avvia
 
-- un Dockerfile PHP con Xdebug
-- un file docker-compose.yml
-- una configurazione di avvio VS Code in .vscode/launch.json
+- 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
 
-## 6. Nota importante
+### "Failed to fetch" dalle richieste del frontend
 
-Il server PHP viene eseguito con:
+- 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`
 
-```bash
-php -S 0.0.0.0:8000 -t public public/index.php
-```
+## Note
 
-Questa modalità è adatta per il debug delle API HTTP del progetto.
+- 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