Vytváření vlastních funkcí

Snadno přidejte do šablon Latte vlastní pomocné funkce. Volejte PHP logiku přímo ve výrazech pro výpočty, přístup ke službám nebo generování dynamického obsahu, což udrží vaše šablony čisté a výkonné.

Co jsou funkce?

Funkce v Latte vám umožňují rozšířit sadu funkcí, které lze volat v rámci výrazů v šablonách ({...}). Můžete si je představit jako vlastní PHP funkce dostupné pouze uvnitř vašich Latte šablon. To přináší několik výhod:

Pohodlí: Můžete definovat pomocnou logiku (jako výpočty, formátování nebo přístup k datům aplikace) a volat ji pomocí jednoduché, známé syntaxe funkcí přímo v šabloně, stejně jako byste volali strlen() nebo date() v PHP.

{var $userInitials = initials($userName)} {* např. 'J. D.' *}

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

Bez znečištění globálního prostoru: Na rozdíl od definování skutečné globální funkce v PHP existují funkce Latte pouze v kontextu vykreslování šablony. Nemusíte zatěžovat globální jmenný prostor PHP pomocníky, které jsou specifické jen pro šablony.

Integrace s logikou aplikace: PHP volatelný objekt stojící za funkcí Latte může být cokoli – anonymní funkce, statická metoda nebo instanční metoda. To znamená, že vaše funkce v šablonách mohou snadno přistupovat ke službám aplikace, databázím, konfiguraci nebo jakékoli jiné potřebné logice zachycením proměnných (v případě anonymních funkcí) nebo pomocí dependency injection (v případě objektů). Výše uvedený příklad hasPermission to jasně demonstruje, když pravděpodobně volá na pozadí autorizační službu.

Přepsání nativních funkcí (volitelně): Můžete dokonce definovat funkci Latte se stejným názvem jako nativní PHP funkce. V šabloně bude místo původní funkce volána vaše vlastní verze. To může být užitečné pro poskytnutí chování specifického pro šablonu nebo zajištění konzistentního zpracování (např. zajištění, že strlen bude vždy vícebytově bezpečná). Tuto funkci používejte opatrně, abyste předešli nedorozuměním.

Ve výchozím nastavení Latte umožňuje volání všech nativních PHP funkcí (pokud nejsou omezeny Sandboxem). Vlastní funkce rozšiřují tuto vestavěnou knihovnu o specifické potřeby vašeho projektu.

Pokud pouze transformujete jedinou hodnotu, může být vhodnější použít vlastní filtr.

Vytváření a registrace funkcí

Podobně jako u filtrů existuje několik způsobů, jak definovat a registrovat vlastní funkce.

Přímá registrace pomocí addFunction()

Nejjednodušší metodou je použití addFunction() na objektu Latte\Engine. Zadáte název funkce (jak se bude zobrazovat v šabloně) a odpovídající PHP volatelný objekt.

$latte = new Latte\Engine;

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

Použití v šabloně:

{var $userInitials = initials($userName)}

Argumenty funkce v šabloně jsou předávány přímo PHP volatelnému objektu ve stejném pořadí. PHP funkcionality jako typové nápovědy, výchozí hodnoty a variabilní parametry (...) fungují podle očekávání.

Registrace pomocí rozšíření

Pro lepší organizaci a znovupoužitelnost registrujte funkce v rámci Latte rozšíření. Tento přístup je doporučen pro složitější aplikace nebo sdílené knihovny.

namespace App\Latte;

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

class MyLatteExtension extends Extension
{
	public function __construct(
		// Předpokládáme, že služba Authorizator existuje
		private Authorizator $authorizator,
	) {
	}

	public function getFunctions(): array
	{
		// Registrace metod jako Latte funkcí
		return [
			'hasPermission' => $this->hasPermission(...),
		];
	}

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

// Registrace (předpokládáme, že $container obsahuje DIC)
$extension = $container->getByType(App\Latte\MyLatteExtension::class);
$latte = new Latte\Engine;
$latte->addExtension($extension);

Tento přístup názorně ukazuje, jak mohou být funkce definované v Latte podpořeny metodami objektů, které mohou mít své vlastní závislosti spravované kontejnerem pro dependency injection vaší aplikace nebo továrnou. To udržuje logiku vašich šablon propojenou s jádrem aplikace a zároveň zachovává přehlednou organizaci.

Funkce používající třídu s atributy

Stejně jako filtry, funkce mohou být definovány jako metody ve vaší třídě parametrů šablony pomocí atributu #[Latte\Attributes\TemplateFunction].

use Latte\Attributes\TemplateFunction;

class TemplateParameters
{
	public function __construct(
		public string $userName,
		// další parametry...
	) {}

	// Tato metoda bude dostupná jako {initials(...)} v šabloně
	#[TemplateFunction]
	public function initials(string $name): string
	{
		preg_match_all('#\b\w#u', $name, $m);
		return implode('. ', $m[0]) . '.';
	}
}

// Předání objektu do šablony
$params = new TemplateParameters(userName: 'John Doe', /* ... */);
$latte->render('template.latte', $params);

Latte automaticky objeví a zaregistruje metody označené tímto atributem, když je objekt parametrů předán do šablony. Název funkce v šabloně odpovídá názvu metody.

{* Použití funkce definované ve třídě parametrů *}
{var $inits = initials($userName)}

Kontextové funkce?

Na rozdíl od filtrů neexistuje přímý koncept „kontextových funkcí“, které by obdržely objekt podobný FilterInfo. Funkce pracují v rámci výrazů a typicky nepotřebují přímý přístup k kontextu vykreslování nebo informacím o typu obsahu stejným způsobem jako filtry aplikované na bloky.

verze: 3.0