Novità in Twig 4.0: un nuovo sistema di macro (Symfony Blog)

Le macro sono vecchie quanto Twig stesso. Sembrano funzioni, le chiami come funzioni e per più di quindici anni hanno rifiutato silenziosamente di comportarsi come funzioni: ogni argomento è opzionale, gli argomenti extra spariscono in una variabile magica e un errore di battitura in un argomento con nome viene ignorato in silenzio. Twig 4.0 mette fine al trattamento speciale: le macro diventano membri a pieno titolo della famiglia callable, con la stessa gestione degli argomenti di funzioni e filtri. Lascia che ti mostri cosa cambia per i tuoi template.

Prendi l'helper per form di cui quasi ogni progetto ha una variante:

Ora, sii onesto: quante di queste chiamate hai mandato in produzione almeno una volta?

Nessuna di queste genera un errore. Tutte producono HTML corrotto che devi individuare a occhio, spesso in produzione. In parte è colpa mia: le macro sono state permissive fin dalla prima versione di Twig, e la permissività aveva anche un certo fascino: una macro non si lamentava mai, restituiva sempre qualcosa. Ma qualcosa è raramente ciò che vuoi da un form helper, e il prezzo si vede in ogni macro in circolazione: corpi costellati di filtri |default() perché non ci si può fidare della presenza di alcun argomento.

Le funzioni e i filtri sono sempre stati severi riguardo ai loro argomenti; le macro erano le uniche callable di Twig che accettavano qualsiasi cosa. Twig 4.0 colma questo divario.

In Twig 4.0, un argomento di macro funziona come un argomento di funzione PHP: è obbligatorio a meno che non dichiari un valore predefinito.

Per mantenere un argomento opzionale, assegnagli un valore predefinito esplicito (= null riproduce il vecchio comportamento). La firma ora dice tutto: leggere la definizione basta per sapere quali argomenti devi passare e quali puoi omettere. E poiché i valori predefiniti vivono nella firma, il corpo non ha più bisogno di chiamate difensive a |default().

Oggi ogni macro è implicitamente variadica: gli argomenti extra vengono raccolti in una variabile riservata varargs che nessuna firma menziona; o sai che esiste o non lo sai. Twig 4.0 sostituisce questa magia con un opt-in esplicito, usando la stessa notazione ... di PHP:

L'argomento variadico raccoglie sia gli argomenti posizionali extra sia quelli con nome extra, il che rende naturale scrivere pattern come l'helper per attributi HTML visto sopra. Deve essere l'ultimo argomento e scegli tu il nome, così la firma documenta che la macro accetta una lista di argomenti aperta. Una macro che non dichiara un argomento variadico rifiuta gli argomenti extra, come fa una funzione.

La sintassi esplicita funziona già in Twig 3.29, quindi puoi adottarla oggi; una macro che fa affidamento sulla variabile implicita varargs continua a funzionare così com'è una volta che dichiara ...varargs.

Fare riferimento a una macro e chiamarla sono sempre state confuse insieme: Twig chiama silenziosamente una macro referenziata senza parentesi e accetta parentesi in punti dove non viene chiamato nulla. Twig 4.0 separa i due usi. Chiamare una macro richiede le parentesi:

E verificare se una macro esiste le rifiuta, perché il test defined ispeziona la macro stessa, non la chiama:

Con una risoluzione rigorosa, ogni errore di chiamata che prima corrompeva il tuo output ora fallisce con un messaggio preciso:

• Value for argument "name" is required for macro "input".
• Unknown argument "sise" for macro "input".
• Too many arguments for macro "input".
• Argument "name" is defined twice for macro "input".

Questa è la stessa esperienza che già ottieni quando chiami male una funzione o un filtro; un errore di battitura ora emerge durante lo sviluppo invece di finire in produzione come attributo vuoto. Anche le definizioni ricevono la stessa pulizia: i nomi delle macro diventano case-sensitive in 4.0, quindi chiamare forms.Input() non risolve più la macro input; definire la stessa macro due volte nello stesso template, che oggi tiene silenziosamente l'ultima definizione, diventa un errore di sintassi; e un tag macro deve ora stare alla radice di un template, non annidato dentro un if o un altro tag.

Il rinnovamento non arriva da solo.

Nomi di macro dinamici, aggiunti in Twig 3.28: la macro da chiamare può ora essere calcolata a runtime avvolgendo un'espressione tra parentesi dopo l'operatore punto:

Deprecare una macro: questa non è una novità, ma completa la cassetta degli attrezzi. Le librerie di macro condivise possono far evolvere la loro API allo stesso modo delle librerie PHP, posizionando il tag deprecated all'inizio del corpo di una macro; un avviso di deprecazione viene attivato ogni volta che la macro viene chiamata:

Come al solito, Twig 3.29 attiva una deprecazione per ogni chiamata e definizione di macro che si romperà in 4.0. Tutte le correzioni funzionano su 3.29, quindi un'applicazione che viene eseguita senza deprecazioni è pronta per Twig 4.0, dove le macro finalmente si comportano come le funzioni a cui sono sempre somigliate.