Migrazione da Latte 3.0
***********************

.[perex]
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 |/html-attributes]. 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 |/develop#Avvisi di migrazione], che durante il rendering vi segnaleranno i punti in cui l'output differisce da quello di Latte 3.0.

```php
$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:

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

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

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

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

```latte
<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:

```php
$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 `\`.

```latte
{* 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.