# 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:

```bash
docker compose up --build
```

Il server PHP sarà disponibile su:

```text
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: **API - Listen for Xdebug**
3. Premi **F5** per avviare il debugger

## 4. Imposta un breakpoint e testa

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

    ```text
    src/Api/Controllers/V1/UsersController.php
    ```

2. Richiama un endpoint tramite browser:

   ```text
    http://localhost:8000/api/users
    ```

3. Esegui la stessa richiesta con curl:

    ```bash
    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:

```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
- È 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