Migration von Latte 3.0

Latte 3.1 bringt mehrere Verbesserungen und Änderungen, die Templates sicherer und bequemer zu schreiben machen. Die meisten Änderungen sind abwärtskompatibel, einige erfordern bei der Migration jedoch Aufmerksamkeit. Diese Anleitung fasst die BC Breaks zusammen und zeigt, wie Sie mit ihnen umgehen.

Latte 3.1 setzt PHP 8.2 oder neuer voraus.

Smarte Attribute und die Migration

Die bedeutendste Änderung in Latte 3.1 ist das neue Verhalten der Smarten Attribute. Es betrifft die Art, wie null-Werte und boolesche Werte in data--Attributen gerendert werden.

  1. null-Werte: Bisher wurde title={$null} als title="" gerendert. Nun entfällt das Attribut vollständig.
  2. data--Attribute: Bisher wurde data-foo={=true} / data-foo={=false} als data-foo="1" / data-foo="" gerendert. Nun wird es als data-foo="true" / data-foo="false" gerendert.

Damit Sie die Stellen finden, an denen sich die Ausgabe in Ihrer Anwendung geändert hat, stellt Latte ein Migrationswerkzeug bereit.

Migrationswarnungen

Sie können Migrationswarnungen aktivieren, die Sie beim Rendern darauf hinweisen, wenn sich die Ausgabe von Latte 3.0 unterscheidet.

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

Ist das aktiviert, achten Sie in den Logs Ihrer Anwendung oder in der Tracy Bar auf E_USER_WARNING. Jede Warnung verweist auf die konkrete Zeile und Spalte im Template.

Wie man Warnungen auflöst:

Ist das neue Verhalten richtig (Sie wollen zum Beispiel, dass das leere Attribut verschwindet), bestätigen Sie es mit dem Filter |accept, um die Warnung zu unterdrücken:

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

Wollen Sie das Attribut als leeres Attribut behalten (z. B. title=""), statt es entfallen zu lassen, verwenden Sie den Null-Koaleszenz-Operator:

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

Oder, wenn Sie unbedingt das alte Verhalten brauchen (z. B. "1" für true), wandeln Sie den Wert ausdrücklich in einen String um:

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

Wenn Sie alle Warnungen aufgelöst haben:

Sind alle Warnungen aufgelöst, schalten Sie die Migrationswarnungen ab und entfernen Sie alle |accept-Filter aus Ihren Templates, denn sie werden nicht mehr gebraucht.

Strict Types

Latte 3.1 aktiviert für alle kompilierten Templates standardmäßig declare(strict_types=1). Das verbessert die Typsicherheit, kann aber in PHP-Ausdrücken innerhalb Ihrer Templates zu Typfehlern führen, wenn Sie sich auf lose Typisierung verlassen haben.

Können Sie die Typen nicht sofort korrigieren, lässt sich dieses Verhalten abschalten:

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

Globale Konstanten

Der Parser der Templates wurde verbessert und unterscheidet nun besser zwischen einfachen Strings und Konstanten. Globalen Konstanten muss deshalb künftig ein Backslash \ vorangestellt werden.

{* Alte Schreibweise (wirft eine Warnung; künftig wird sie als der String 'PHP_VERSION' interpretiert) *}
{if PHP_VERSION > ...}

{* Neue Schreibweise (korrekt als Konstante interpretiert) *}
{if \PHP_VERSION > ...}

Diese Änderung verhindert Mehrdeutigkeiten und erlaubt Ihnen, Strings ohne Anführungszeichen freier zu verwenden.

Entfernte und veraltete Funktionen

Reservierte Variablen: Variablen, die mit $__ (doppeltem Unterstrich) beginnen, und die Variable $this sind für den internen Gebrauch von Latte reserviert. Standardmäßig funktioniert ihre Verwendung weiterhin, löst aber eine Deprecation-Warnung aus; erst bei aktiviertem strikten Parsing wirft sie einen Compile-Fehler. Die internen Variablen $ʟ_… und $GLOBALS sind immer verboten.

Undefined-safe-Operator: Der Operator ??->, eine Latte-eigene Erfindung aus der Zeit vor PHP 8, wurde entfernt. Er ist ein historisches Relikt. Verwenden Sie bitte den Standard-Nullsafe-Operator ?-> von PHP.

Filter-Loader Die Methode Engine::addFilterLoader() wurde für veraltet erklärt und entfernt. Sie war ein inkonsistentes Konzept, das es sonst nirgends in Latte gibt.

Datumsformat Die statische Property Latte\Runtime\Filters::$dateFormat wurde entfernt, um globalen Zustand zu vermeiden.

Neue Funktionen

Während der Migration können Sie die neuen Funktionen bereits genießen:

  • Smarte HTML-Attribute: Übergeben Sie Arrays an class und style, null-Attribute entfallen automatisch.
  • Nullsafe-Filter: Mit {$var?|filter} überspringen Sie das Filtern von null-Werten.
  • n:elseif: Sie können nun n:elseif neben n:if und n:else verwenden.
  • Vereinfachte Syntax: Schreiben Sie <div n:if={$cond}> ohne Anführungszeichen.
  • Filter toggle: Mit |toggle steuern Sie boolesche Attribute von Hand.
Version: 3.x