Migracja z Latte 3.0
********************

.[perex]
Latte 3.1 przynosi kilka ulepszeń i zmian, dzięki którym pisanie szablonów jest bezpieczniejsze i wygodniejsze. Większość zmian jest wstecznie zgodna, ale niektóre wymagają uwagi przy migracji. Ten przewodnik podsumowuje zmiany łamiące zgodność i sposoby radzenia sobie z nimi.

Latte 3.1 wymaga **PHP 8.2** lub nowszego.


Smart atrybuty a migracja
=========================

Najistotniejszą zmianą w Latte 3.1 jest nowe zachowanie [smart atrybutów |/html-attributes]. Wpływa ono na to, jak renderowane są wartości `null` i wartości logiczne w atrybutach `data-`.

1.  **Wartości `null`:** Wcześniej `title={$null}` renderowało się jako `title=""`. Teraz atrybut jest całkowicie pomijany.
2.  **Atrybuty `data-`:** Wcześniej `data-foo={=true}` / `data-foo={=false}` renderowało się jako `data-foo="1"` / `data-foo=""`. Teraz renderuje się jako `data-foo="true"` / `data-foo="false"`.

Aby pomóc Ci znaleźć miejsca, w których wynik w Twojej aplikacji się zmienił, Latte udostępnia narzędzie migracyjne.


Ostrzeżenia migracyjne
----------------------

Możesz włączyć [ostrzeżenia migracyjne |/develop#Ostrzeżenia migracyjne], które podczas renderowania ostrzegą Cię, gdy wynik różni się od Latte 3.0.

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

Po włączeniu sprawdzaj logi aplikacji albo pasek Tracy pod kątem `E_USER_WARNING`. Każde ostrzeżenie wskaże konkretny wiersz i kolumnę w szablonie.

**Jak rozwiązywać ostrzeżenia:**

Jeśli nowe zachowanie jest poprawne (np. chcesz, aby pusty atrybut zniknął), potwierdź to filtrem `|accept`, aby wyciszyć ostrzeżenie:

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

Jeśli chcesz zachować atrybut jako pusty (np. `title=""`) zamiast go pomijać, użyj operatora łączenia z null:

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

A jeśli koniecznie potrzebujesz starego zachowania (np. `"1"` dla `true`), rzutuj wartość jawnie na string:

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

**Gdy rozwiążesz wszystkie ostrzeżenia:**

Po rozwiązaniu wszystkich ostrzeżeń wyłącz ostrzeżenia migracyjne i **usuń wszystkie** filtry `|accept` z szablonów, bo nie są już potrzebne.


Ścisłe typy
===========

Latte 3.1 domyślnie włącza `declare(strict_types=1)` dla wszystkich kompilowanych szablonów. Poprawia to bezpieczeństwo typów, ale może powodować błędy typów w wyrażeniach PHP wewnątrz szablonów, jeśli polegałeś na luźnym typowaniu.

Jeśli nie możesz od razu poprawić typów, możesz to zachowanie wyłączyć:

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


Stałe globalne
==============

Parser szablonów został ulepszony tak, aby lepiej odróżniać zwykłe łańcuchy od stałych. W efekcie stałe globalne muszą być teraz poprzedzone odwrotnym ukośnikiem `\`.

```latte
{* Stary sposób (zgłasza ostrzeżenie; w przyszłości będzie interpretowany jako łańcuch 'PHP_VERSION') *}
{if PHP_VERSION > ...}

{* Nowy sposób (poprawnie interpretowany jako stała) *}
{if \PHP_VERSION > ...}
```

Ta zmiana zapobiega niejednoznaczności i pozwala swobodniej używać łańcuchów bez cudzysłowów.


Usunięte i przestarzałe funkcje
===============================

**Zarezerwowane zmienne:** Zmienne zaczynające się od `$__` (podwójne podkreślenie) oraz zmienna `$this` są zarezerwowane do wewnętrznego użytku Latte. Domyślnie ich użycie nadal działa, ale wywołuje ostrzeżenie o przestarzałości; dopiero przy włączonym ścisłym parsowaniu zgłasza błąd kompilacji. Wewnętrzne zmienne `$ʟ_…` i `$GLOBALS` są zabronione zawsze.

**Operator bezpieczny dla niezdefiniowanych:** Operator `??->`, który był funkcją specyficzną dla Latte, powstałą przed PHP 8, został usunięty. To relikt historyczny. Używaj standardowego operatora nullsafe PHP `?->`.

**Loader filtrów**
Metoda `Engine::addFilterLoader()` została oznaczona jako przestarzała i usunięta. Była niespójną koncepcją, niewystępującą nigdzie indziej w Latte.

**Format daty**
Statyczna właściwość `Latte\Runtime\Filters::$dateFormat` została usunięta, aby uniknąć stanu globalnego.


Nowe funkcje
============

Podczas migracji możesz zacząć korzystać z nowości:

- **Smart atrybuty HTML:** przekazuj tablice do `class` i `style`, automatyczne pomijanie atrybutów `null`.
- **Filtry nullsafe:** użyj `{$var?|filter}`, aby pominąć filtrowanie wartości null.
- **`n:elseif`:** możesz teraz używać `n:elseif` obok `n:if` i `n:else`.
- **Uproszczona składnia:** pisz `<div n:if={$cond}>` bez cudzysłowów.
- **Filtr toggle:** użyj `|toggle` do ręcznej kontroli nad atrybutami logicznymi.