# API Server - Regole e Skill Set

Queste regole definiscono il comportamento per tutti gli sviluppi futuri su questa repository, al fine di mantenere l'architettura pulita e scalabile.

1. **Dependency Injection Obbligatoria (IoC)**
   Non utilizzare mai chiamate a metodi statici per accedere a servizi o configurazioni (es. evitare `Config::get()` o `HttpClient::get()`). 
   Tutte le dipendenze devono essere iniettate tramite costruttore. Il container in `bootstrap.php` provvederà all'autowiring automatico.

2. **Namespace e Struttura dei Controller**
   Tutti i nuovi Controller devono essere posizionati all'interno della cartella relativa alla loro versione (es. `src/Api/Controllers/V1/`) e devono avere il namespace corretto (es. `namespace Api\Controllers\V1;`). Questo permette al `Router` di mapparli automaticamente partendo dalle route versionate (es. `/v1/risorsa`).

3. **Risposte HTTP Standard**
   Non utilizzare mai funzioni di output diretto (come `echo`, `print` o `header()`) all'interno dei Controller.
   Usa sempre l'oggetto `Response` (iniettato come parametro o generato internamente) e chiama il metodo `$res->json($payload, $statusCode)` per uniformare l'output.

4. **Gestione Errori e Sicurezza**
   Non includere mai stack trace o dettagli sensibili (segreti, stringhe di connessione) nelle risposte JSON d'errore o nei log generici.
   Lascia che le eccezioni vengano catturate dal Global Exception Handler o usa il `LoggerInterface` per tracciare i problemi a livello server.

5. **Validazione dell'Input**
   Assicurati sempre di validare l'input proveniente da `$req->body()` o dai parametri URL prima di processarlo con la business logic applicativa. (Consigliato l'uso di DTO).

6. **Routing API e prefissi di versione**
   Le route devono essere registrate senza il prefisso `/api` e senza il prefisso di versione (es. usare `/users` invece di `/api/users` o `/api/v1/users`). Il router deve normalizzare i percorsi in ingresso rimuovendo il prefisso `/api` prima di confrontarli con le route registrate, così richieste come `/api/users` e `/api/v1/users` continuano a funzionare.

---

# Debug API PHP con VS Code e Docker

Questa sezione descrive la procedura per fare debug delle API PHP servite da Docker in questa repository.

## Passaggi

1. Avvia il container Docker dalla root del progetto:
   ```bash
   docker compose up --build
   ```

2. Apri Visual Studio Code e vai su "Run and Debug".

3. Seleziona la configurazione:
   ```text
   Debug PHP in Docker
   ```

4. Premi F5 per avviare il debugger.

5. Imposta un breakpoint in un controller, ad esempio in:
   ```text
   src/Api/Controllers/V1/UsersController.php
   ```

6. Richiama l’endpoint tramite browser o curl:
   ```bash
   curl -H "XDEBUG_TRIGGER: 1" http://localhost:8000/api/users
   ```

## Nota

Il container deve esporre:
- porta `8000` per HTTP
- porta `9003` per Xdebug

Il progetto contiene già i file necessari per il debug:
- `.docker/php/Dockerfile`
- `docker-compose.yml`
- `.vscode/launch.json`
- `.vscode/settings.json`

## Problemi comuni

- Se VS Code non si ferma sul breakpoint, verifica che Xdebug sia abilitato nel container e che la configurazione `client_host` punti a `host.docker.internal`.
- Se il container non si avvia, controlla che Docker Desktop sia in esecuzione.