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.

Migracja z Latte 3.0

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. Wpływa ono na to, jak renderowane są wartości null i wartości logiczne w atrybutach data-.

Wartości null: Wcześniej title={$null} renderowało się jako title="". Teraz atrybut jest całkowicie pomijany.
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, które podczas renderowania ostrzegą Cię, gdy wynik różni się od Latte 3.0.

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

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

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

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

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

<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ć:

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

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