elixforms-web-services/.agents/AGENTS.md

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:

   docker compose up --build
   

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

3. Seleziona la configurazione:

   Debug PHP in Docker
   

4. Premi F5 per avviare il debugger.

5. Imposta un breakpoint in un controller, ad esempio in:

   src/Api/Controllers/V1/UsersController.php
   

6. Richiama l’endpoint tramite browser o curl:

   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.