Eigene Funktionen erstellen

Fügen Sie Latte-Templates mühelos eigene Hilfsfunktionen hinzu. Rufen Sie PHP-Logik direkt in Ausdrücken auf, um zu rechnen, auf Services zuzugreifen oder dynamische Inhalte zu erzeugen – und halten Sie Ihre Templates dabei sauber und leistungsfähig.

Was sind Funktionen?

Latte-Funktionen erlauben es Ihnen, den Satz an Funktionen zu erweitern, die sich in Template-Ausdrücken ({...}) aufrufen lassen. Stellen Sie sich sie als eigene PHP-Funktionen vor, die nur innerhalb Ihrer Latte-Templates verfügbar sind. Das bringt mehrere Vorteile:

Bequemlichkeit: Sie können Hilfslogik definieren (etwa Berechnungen, Formatierungen oder den Zugriff auf Anwendungsdaten) und sie mit einer einfachen, vertrauten Funktionssyntax direkt im Template aufrufen – genau so, wie Sie in PHP strlen() oder date() aufrufen würden.

{var $userInitials = initials($userName)} {* z. B. 'J. D.' *}

{if hasPermission('article', 'edit')}
    <a href="...">Bearbeiten</a>
{/if}

Keine Verschmutzung des globalen Namensraums: Anders als bei einer echten globalen Funktion in PHP existieren Latte-Funktionen nur im Kontext des Renderings von Templates. Sie müssen den globalen PHP-Namespace nicht mit template-spezifischen Helfern vollstopfen.

Verzahnung mit der Anwendungslogik: Das PHP-Callable hinter einer Latte-Funktion kann alles sein – eine Closure, eine statische Methode oder eine Instanzmethode. Ihre Template-Funktionen können damit mühelos auf Services der Anwendung, Datenbanken, Konfiguration oder jede andere nötige Logik zugreifen, indem sie Variablen einfangen (bei Closures) oder über Dependency Injection (bei Objekten). Das Beispiel hasPermission oben zeigt das anschaulich – im Hintergrund ruft es vermutlich einen Autorisierungs-Service auf.

Native Funktionen überschreiben (optional): Sie können sogar eine Latte-Funktion mit demselben Namen wie eine native PHP-Funktion definieren. Im Template wird dann Ihre eigene Variante aufgerufen. Das kann nützlich sein, um template-spezifisches Verhalten bereitzustellen oder einheitliche Behandlung sicherzustellen (etwa strlen immer multibyte-sicher zu machen). Verwenden Sie diese Möglichkeit mit Bedacht, um Verwirrung zu vermeiden.

Standardmäßig erlaubt Latte den Aufruf aller nativen PHP-Funktionen (sofern es nicht die Sandbox einschränkt). Eigene Funktionen ergänzen diese eingebaute Bibliothek um die besonderen Bedürfnisse Ihres Projekts.

Wenn Sie einen einzelnen Wert umwandeln, ist ein eigener Filter womöglich idiomatischer.

Funktionen erstellen und registrieren

Ähnlich wie bei Filtern gibt es mehrere Wege, eigene Funktionen zu definieren und zu registrieren.

Direkte Registrierung über addFunction()

Der einfachste Weg ist die Methode addFunction() am Objekt Latte\Engine. Sie geben den Namen der Funktion an (so, wie er im Template erscheinen soll) und das zugehörige PHP-Callable.

$latte = new Latte\Engine;

// Einfache Hilfsfunktion
$latte->addFunction('initials', function (string $name): string {
	preg_match_all('#\b\w#u', $name, $m);
	return implode('. ', $m[0]) . '.';
});

Verwendung im Template:

{var $userInitials = initials($userName)}

Die Argumente der Funktion werden im Template in derselben Reihenfolge direkt an das PHP-Callable übergeben. PHP-Möglichkeiten wie Typdeklarationen, Standardwerte und variadische Parameter (...) funktionieren wie erwartet.

Registrierung über eine Extension

Für bessere Organisation und Wiederverwendbarkeit registrieren Sie Funktionen innerhalb einer Latte-Extension. Das ist der empfohlene Weg für nichttriviale Anwendungen oder gemeinsam genutzte Bibliotheken.

namespace App\Templating;

use Latte\Extension;
use Nette\Security\Authorizator;

class MyLatteExtension extends Extension
{
	public function __construct(
		// wir setzen voraus, dass der Service Authorizator existiert
		private Authorizator $authorizator,
	) {
	}

	public function getFunctions(): array
	{
		// Methoden als Latte-Funktionen registrieren
		return [
			'hasPermission' => $this->hasPermission(...),
		];
	}

	public function hasPermission(string $resource, string $action): bool
	{
		return $this->authorizator->isAllowed($resource, $action);
	}
}

// Registrierung (wir setzen voraus, dass $container den DIC hält)
$extension = $container->getByType(MyLatteExtension::class);
$latte = new Latte\Engine;
$latte->addExtension($extension);

Dieser Ansatz zeigt anschaulich, wie in Latte definierte Funktionen von Methoden eines Objekts getragen werden können, die ihrerseits eigene Abhängigkeiten haben dürfen, verwaltet vom Dependency-Injection-Container oder einer Factory Ihrer Anwendung. So bleibt die Logik Ihrer Templates mit dem Kern Ihrer Anwendung verbunden und zugleich gut organisiert.

Funktionen über eine Klasse mit Attributen

Genau wie Filter lassen sich Funktionen als Methoden in Ihrer Klasse mit Template-Parametern definieren, gekennzeichnet mit dem Attribut #[Latte\Attributes\TemplateFunction].

use Latte\Attributes\TemplateFunction;

class TemplateParameters
{
	public function __construct(
		public string $userName,
		// weitere Parameter...
	) {}

	// Diese Methode steht im Template als {initials(...)} zur Verfügung
	#[TemplateFunction]
	public function initials(string $name): string
	{
		preg_match_all('#\b\w#u', $name, $m);
		return implode('. ', $m[0]) . '.';
	}
}

// Das Objekt an das Template übergeben
$params = new TemplateParameters(userName: 'John Doe', /* ... */);
$latte->render('template.latte', $params);

Latte findet und registriert die mit diesem Attribut gekennzeichneten Methoden automatisch, sobald das Objekt mit den Parametern an das Template übergeben wird. Der Name der Funktion im Template entspricht dem Methodennamen.

{* Die in der Parameterklasse definierte Funktion verwenden *}
{var $inits = initials($userName)}

Kontextabhängige Funktionen?

Anders als Filter erhalten Funktionen kein Objekt FilterInfo. Eine Funktion kann jedoch Zugriff auf den Kontext des Templates bekommen: Ist ihr erster Parameter mit dem Typ Latte\Runtime\Template deklariert, übergibt Latte ihr automatisch das aktuelle Template-Objekt. Genau so sind die eingebauten Funktionen hasBlock() und hasTemplate() umgesetzt.

Version: 3.x