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

  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, 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.
wersja: 3.x