> MapRequestHeader e controller attributes: la DX di Symfony 8.1

Il problema del boilerplate nei controller Symfony

Ogni controller in un'applicazione Symfony ripete le stesse operazioni: estrarre dati dalla richiesta HTTP, validarli, controllare i permessi, delegare al service layer, costruire la risposta. Gran parte di questo codice e infrastrutturale, non di business — e identico (o quasi) in ogni azione di ogni controller dell'applicazione.

Symfony ha affrontato questo problema progressivamente. Symfony 6.3 ha introdotto #[MapRequestPayload] e #[MapQueryString] per la deserializzazione automatica del body e dei query parameter. Symfony 7 ha aggiunto miglioramenti alla validazione integrata. Symfony 8.1 porta il concetto ancora piu avanti con nuovi attributi che coprono gli header HTTP e la logica di autorizzazione.

MapRequestHeader in dettaglio

Il nuovo attributo #[MapRequestHeader] completa la famiglia degli attributi di mapping che Symfony mette a disposizione nei controller. Il suo funzionamento e coerente con gli altri attributi della famiglia: un parametro del metodo controller viene decorato con l'attributo, e Symfony si occupa di estrarre, convertire e validare il dato dalla richiesta HTTP.

Sintassi e utilizzo pratico

L'utilizzo e diretto e intuitivo. Un parametro del metodo controller decorato con #[MapRequestHeader] riceve automaticamente il valore dell'header HTTP corrispondente. Il nome dell'header viene derivato dal nome del parametro, con conversione automatica da camelCase a kebab-case con prefisso standard.

• Mapping diretto: #[MapRequestHeader] string $apiKey mappa l'header Api-Key. Niente piu $request->headers->get('Api-Key') nel body del metodo.
• Nome custom: #[MapRequestHeader(name: 'X-Custom-Token')] string $token permette di specificare il nome esatto dell'header quando non segue la convenzione standard.
• Conversione di tipo: il tipo del parametro guida la conversione. int $rateLimit converte automaticamente il valore dell'header in intero. ?string $optional gestisce header assenti.
• Array di valori: array $acceptLanguage gestisce header con valori multipli separati da virgola, splittandoli automaticamente in un array.

Validazione degli header

Gli header mappati possono essere validati con gli stessi constraint di validazione usati per qualsiasi altro dato in Symfony. Si possono applicare constraint come #[Assert\NotBlank], #[Assert\Length(max: 255)] o #[Assert\Regex] direttamente sul parametro del controller. Un header che non supera la validazione genera una risposta 400 Bad Request con dettagli sull'errore, senza che il controller debba gestire manualmente la validazione.

Miglioramenti a IsGranted con espressioni

L'attributo #[IsGranted] in Symfony 8.1 guadagna il supporto alla variabile this nelle espressioni. Questo e un cambiamento apparentemente piccolo ma con implicazioni significative per la gestione delle autorizzazioni.

Prima di Symfony 8.1

Per regole di autorizzazione che dipendevano dallo stato del controller (ad esempio, un tenant corrente iniettato nel costruttore), serviva un security voter custom: una classe separata, registrata come servizio, che implementava l'interfaccia VoterInterface. Per logiche semplici, il costo in termini di codice e complessita era sproporzionato rispetto al problema risolto.

Con Symfony 8.1

La variabile this nelle espressioni permette di accedere a metodi e proprieta del controller direttamente nell'espressione di autorizzazione. Pattern comuni come verificare che l'utente appartenga allo stesso tenant della risorsa, o che abbia un ruolo specifico nel contesto dell'organizzazione corrente, si risolvono con un'espressione inline senza classi aggiuntive.

MapRequestPayload con gruppi di validazione dinamici

L'attributo #[MapRequestPayload] in Symfony 8.1 accetta espressioni per i gruppi di validazione. Questo risolve un problema comune: validare lo stesso DTO con regole diverse in contesti diversi.

• Validazione per ruolo: un admin puo inviare campi che un utente normale non puo. I gruppi di validazione dinamici applicano le constraint corrette in base al ruolo, senza logica nel controller.
• Validazione per contesto: creazione vs aggiornamento dello stesso oggetto possono avere regole diverse. L'espressione determina il gruppo a runtime.
• Validazione per header: combinando con #[MapRequestHeader], si possono applicare regole di validazione diverse in base alla versione dell'API dichiarata nell'header.

Opzioni per dati vuoti in MapQueryString e MapRequestPayload

Symfony 8.1 introduce opzioni dedicate per gestire i casi edge dei dati vuoti. Cosa succede quando un query string e presente ma vuoto? O quando il body della richiesta e un oggetto JSON vuoto? Prima di Symfony 8.1, questi scenari richiedevano gestione manuale. Ora le opzioni acceptEmptyBody e il valore di default per query string vuoti sono configurabili direttamente nell'attributo.

Il pattern emergente: controller come dichiarazione di intenti

Guardando l'evoluzione degli attributi controller da Symfony 6.3 a Symfony 8.1, emerge un pattern chiaro. Il controller sta diventando una dichiarazione di intenti piuttosto che un'implementazione procedurale. Gli attributi descrivono cosa il controller deve ricevere (payload, query, header), come validarlo (constraint, gruppi), chi puo accedervi (IsGranted, espressioni) e cosa restituire.

Il framework si occupa dell'esecuzione. Il controller si concentra sull'orchestrazione della business logic. Per chi sviluppa API REST con Symfony, questo approccio riduce drasticamente il codice infrastrutturale e rende i controller piu leggibili, testabili e manutenibili. Come sviluppatore freelance PHP, apprezzo particolarmente questo trend perche rende il codice auto-documentante — un nuovo sviluppatore che legge il controller capisce immediatamente cosa fa, senza dover navigare service class e configuration file.