Migrazione da Latte 3.0

Latte 3.1 porta diverse migliorie e novità che rendono i template più sicuri e più comodi da scrivere. La maggior parte delle modifiche è retrocompatibile, ma alcune richiedono attenzione durante la migrazione. Questa guida riassume le modifiche che rompono la compatibilità e come affrontarle.

Latte 3.1 richiede PHP 8.2 o successivo.

Attributi intelligenti e migrazione

La modifica più rilevante di Latte 3.1 è il nuovo comportamento degli attributi intelligenti. Riguarda il modo in cui vengono stampati i valori null e i valori booleani negli attributi data-.

1. Valori null: in precedenza title={$null} veniva stampato come title="". Ora l'attributo viene eliminato del tutto.
2. Attributi data-: in precedenza data-foo={=true} / data-foo={=false} venivano stampati come data-foo="1" / data-foo="". Ora vengono stampati come data-foo="true" / data-foo="false".

Per aiutarvi a individuare i punti in cui l'output della vostra applicazione è cambiato, Latte offre uno strumento di migrazione.

Avvisi di migrazione

Potete attivare gli avvisi di migrazione, che durante il rendering vi segnaleranno i punti in cui l'output differisce da quello di Latte 3.0.

$latte = new Latte\Engine;
$latte->setFeature(Latte\Feature::MigrationWarnings);

Una volta attivati, controllate i log della vostra applicazione o la barra di Tracy alla ricerca di E_USER_WARNING. Ogni avviso indicherà la riga e la colonna precise nel template.

Come risolvere gli avvisi:

Se il nuovo comportamento è quello giusto (per esempio volete che l'attributo vuoto sparisca), confermatelo con il filtro |accept per silenziare l'avviso:

<div title={$var|accept}></div>

Se invece volete mantenere l'attributo vuoto (per esempio title="") anziché eliminarlo, usate l'operatore di coalescenza null:

<div title={$var ?? ''}></div>

Oppure, se avete assolutamente bisogno del vecchio comportamento (per esempio "1" per true), convertite esplicitamente il valore in stringa:

<div data-foo={(string) $bool}></div>

Dopo aver risolto tutti gli avvisi:

Una volta risolti tutti gli avvisi, disattivate gli avvisi di migrazione e rimuovete tutti i filtri |accept dai vostri template, perché non servono più.

Tipi stretti

Latte 3.1 attiva per impostazione predefinita declare(strict_types=1) in tutti i template compilati. Questo migliora la sicurezza dei tipi, ma può provocare errori di tipo nelle espressioni PHP dei vostri template se contavate sulla tipizzazione debole.

Se non potete sistemare subito i tipi, potete disattivare questo comportamento:

$latte->setFeature(Latte\Feature::StrictTypes, false);

Costanti globali

Il parser dei template è stato migliorato per distinguere meglio tra semplici stringhe e costanti. Di conseguenza le costanti globali devono ora essere precedute da una barra rovesciata \.

{* modo vecchio (emette un avviso; in futuro sarà interpretato come la stringa 'PHP_VERSION') *}
{if PHP_VERSION > ...}

{* modo nuovo (interpretato correttamente come costante) *}
{if \PHP_VERSION > ...}

Questa modifica elimina le ambiguità e vi permette di usare più liberamente le stringhe senza apici.

Funzionalità rimosse e deprecate

Variabili riservate: le variabili che iniziano con $__ (doppio trattino basso) e la variabile $this sono riservate all'uso interno di Latte. Per impostazione predefinita usarle funziona ancora, ma emette un avviso di deprecazione; solo con l'analisi rigorosa attivata provoca un errore di compilazione. Le variabili interne $ʟ_… e $GLOBALS sono sempre vietate.

Operatore undefined-safe: l'operatore ??->, una funzionalità specifica di Latte nata prima di PHP 8, è stato rimosso. È un residuo storico. Usate l'operatore nullsafe standard di PHP ?->.

Filter loader Il metodo Engine::addFilterLoader() è stato deprecato e rimosso. Era un concetto incoerente, che non trovava riscontro in nessun'altra parte di Latte.

Formato della data La proprietà statica Latte\Runtime\Filters::$dateFormat è stata rimossa per evitare stato globale.

Novità

Durante la migrazione potete iniziare a godervi le nuove funzionalità:

• Attributi HTML intelligenti: passate array a class e style, gli attributi null spariscono da soli.
• Filtri nullsafe: usate {$var?|filter} per saltare il filtraggio dei valori null.
• n:elseif: ora potete usare n:elseif accanto a n:if e n:else.
• Sintassi semplificata: scrivete <div n:if={$cond}> senza apici.
• Filtro toggle: usate |toggle per controllare manualmente gli attributi booleani.