Migración desde Latte 3.0
*************************

.[perex]
Latte 3.1 trae varias mejoras y cambios que hacen las plantillas más seguras y más cómodas de escribir. La mayoría de los cambios son retrocompatibles, pero algunos requieren atención durante la migración. Esta guía resume los cambios que rompen la compatibilidad y cómo afrontarlos.

Latte 3.1 requiere **PHP 8.2** o superior.


Atributos inteligentes y migración
==================================

El cambio más importante de Latte 3.1 es el nuevo comportamiento de los [atributos inteligentes |/html-attributes]. Afecta a cómo se renderizan los valores `null` y los valores booleanos en los atributos `data-`.

1.  **Valores `null`:** antes, `title={$null}` se renderizaba como `title=""`. Ahora el atributo se descarta por completo.
2.  **Atributos `data-`:** antes, `data-foo={=true}` / `data-foo={=false}` se renderizaba como `data-foo="1"` / `data-foo=""`. Ahora se renderiza como `data-foo="true"` / `data-foo="false"`.

Para ayudarle a localizar los puntos de su aplicación donde ha cambiado la salida, Latte ofrece una herramienta de migración.


Advertencias de migración
-------------------------

Puede activar las [advertencias de migración |/develop#Migration Warnings], que le avisarán durante el renderizado si la salida difiere de la de Latte 3.0.

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

Con ellas activadas, revise los registros de su aplicación o la barra de Tracy en busca de `E_USER_WARNING`. Cada advertencia señalará la línea y la columna concretas de la plantilla.

**Cómo resolver las advertencias:**

Si el nuevo comportamiento es el correcto (por ejemplo, quiere que el atributo vacío desaparezca), confírmelo con el filtro `|accept` para silenciar la advertencia:

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

Si quiere conservar el atributo como vacío (por ejemplo `title=""`) en lugar de descartarlo, use el operador de fusión de nulos:

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

O bien, si necesita estrictamente el comportamiento antiguo (por ejemplo `"1"` para `true`), convierta el valor a cadena de forma explícita:

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

**Cuando haya resuelto todas las advertencias:**

Una vez resueltas todas, desactive las advertencias de migración y **elimine todos** los filtros `|accept` de sus plantillas, ya que dejan de ser necesarios.


Tipos estrictos
===============

Latte 3.1 activa `declare(strict_types=1)` de forma predeterminada en todas las plantillas compiladas. Esto mejora la seguridad de tipos, pero puede provocar errores de tipo en las expresiones PHP de sus plantillas si dependía del tipado laxo.

Si no puede corregir los tipos de inmediato, puede desactivar este comportamiento:

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


Constantes globales
===================

El analizador de plantillas se ha mejorado para distinguir mejor entre cadenas simples y constantes. Por eso, las constantes globales deben ir ahora precedidas de una barra invertida `\`.

```latte
{* Forma antigua (lanza una advertencia; en el futuro se interpretará como la cadena 'PHP_VERSION') *}
{if PHP_VERSION > ...}

{* Forma nueva (se interpreta correctamente como constante) *}
{if \PHP_VERSION > ...}
```

Este cambio evita ambigüedades y le permite usar con más libertad las cadenas sin comillas.


Funciones eliminadas y obsoletas
================================

**Variables reservadas:** las variables que empiezan por `$__` (doble guion bajo) y la variable `$this` están reservadas para uso interno de Latte. De forma predeterminada, usarlas sigue funcionando, pero emite una advertencia de obsolescencia; solo con el análisis estricto activado provoca un error de compilación. Las variables internas `$ʟ_…` y `$GLOBALS` están siempre prohibidas.

**Operador undefined-safe:** se ha eliminado el operador `??->`, una función propia de Latte creada antes de PHP 8. Es una reliquia histórica. Use el operador nullsafe estándar de PHP `?->`.

**Cargador de filtros**
El método `Engine::addFilterLoader()` quedó obsoleto y se ha eliminado. Era un concepto incoherente que no aparece en ningún otro punto de Latte.

**Formato de fecha**
La propiedad estática `Latte\Runtime\Filters::$dateFormat` se ha eliminado para evitar el estado global.


Novedades
=========

Durante la migración ya puede empezar a disfrutar de las novedades:

- **Atributos HTML inteligentes:** pase arrays a `class` y `style`, con descarte automático de los atributos `null`.
- **Filtros nullsafe:** use `{$var?|filter}` para saltarse el filtrado de valores nulos.
- **`n:elseif`:** ahora puede usar `n:elseif` junto a `n:if` y `n:else`.
- **Sintaxis simplificada:** escriba `<div n:if={$cond}>` sin comillas.
- **Filtro toggle:** use `|toggle` para controlar manualmente los atributos booleanos.