Latte: Wie benutzt man das Typensystem?

Zu wissen, welcher Daten- oder Objekttyp jede Variable ist, erlaubt der

• IDE korrektes Autocomplete
• statische Analyse zur Fehlererkennung

Zwei Punkte, die die Qualität und den Komfort der Entwicklung erheblich verbessern.

Wie deklariert man Typen auf der PHP-Seite?

Wir übergeben die Daten an die Vorlage als Objekt einer Klasse, die alle Variablen und ihre Typen definiert. Mit den neuen Funktionen von PHP 7.4 könnte das wie folgt aussehen:

class MailTemplate
{
	public string $lang = 'cs';
	public Address $address;
	public string $subject;
	public ?float $price = null;
}

Verwendung:

$template = new MailTemplate;
$template->price = $this->getPrice();
...
$latte->render('mail.latte', $template);

Nachtrag: Dank der neuen Funktionen von PHP 8 kann das Beispiel interessanter geschrieben werden, wie hier:

class MailTemplate
{
	public function __construct(
		public string $lang = 'cs',
		public Address $address,
		public string $subject,
		public ?float $price = null,
	) {}
}

$latte->render('mail.latte', new MailTemplate(
	lang: $this->lang,
	subject: $title,
	price: $this->getPrice(),
	address: $userAddress,
));

Wie deklariert man Typen in einer Vorlage?

Jetzt können wir diese Klasse mit der Vorlage verknüpfen. Wir müssen sie nur am Anfang der Vorlage angeben:

{templateType MailTemplate}

Damit haben wir festgelegt, dass die Vorlage ein Quartett von Variablen $lang, $address, $subject und $price einschließlich ihrer jeweiligen Typen enthalten wird.

Die Alternative ist, die Typen der einzelnen Variablen direkt in der Vorlage zu definieren, d.h. ohne eine Klasse zu erstellen. Zu diesem Zweck wird das Tag {varType} verwendet:

{varType string $lang}
{varType Address $address}

Natürlich kann beides kombiniert werden. Erstellen Sie eine Klasse, da dies die Vervollständigung auf der Seite des Präsentators sicherstellt, verknüpfen Sie sie mit der Vorlage mit {templateType} und verwenden Sie {varType} für andere lokale Variablen in Blöcken usw. Dies kann als Analogie zu /** @var type $variable */ verstanden werden, einem Kommentar, den wir manchmal in PHP-Code verwenden, um die IDE oder ein statisches Analysetool anzuweisen.

Auch der Typ kann in {var}, {default} oder {define} angegeben werden:

{var Model\Page $page = $items['page']}

{define form, string $name}
	...
{/define}

Hinweis: Aus historischen Gründen war es möglich, Variablen in den Tags {var} und {default} ohne das führende Dollarzeichen zu schreiben. Da dies zu Unklarheiten führt, ob es sich um einen Typ oder eine Variable handelt, ist diese Syntax veraltet und Latte wird Sie warnen, wenn Sie sie verwenden.

Wie können Sie Ihre Arbeit vereinfachen?

Wie kann man eine Vorlagenklasse oder {varType} so einfach wie möglich schreiben? Lassen Sie sie generieren. Das ist genau das, was die beiden Tags {templatePrint} und {varPrint} tun.

Wenn Sie eines dieser Tags in einer Vorlage platzieren, wird der Code der Klasse oder Vorlage anstelle der normalen Darstellung angezeigt. Wählen Sie dann einfach den Code aus und kopieren Sie ihn in Ihr Projekt.

Nette/application 3.1 (beta) enthält ein überladenes Tag {templatePrint}, das Code erzeugt, der besser für Präsentatoren geeignet ist.

Der Tag {varPrint} listet lokale Variablen auf, die keine Template-Parameter sind. Wenn Sie alle Variablen auflisten möchten, verwenden Sie {varPrint all}.

IDE-Code-Vervollständigung

Die neueste Version des PhpStorm Latte-Plugins kann die oben genannten Tags nutzen und dann Vorschläge auf der Grundlage der Typen machen. Das Plugin kennt auch die Typen von Standardvariablen wie $user, $presenter, $basePath, etc.

Statische Analyse

Das Endziel ist, dass alle deklarierten Typen auch für die statische Analyse verwendet werden können. Zum Beispiel, um PHPStan zu benutzen, um Templates genauso einfach zu überprüfen wie andere PHP-Dateien.

Wir arbeiten daran und Sie werden es in einer der nächsten Versionen von Latte sehen.