Vývojářské postupy
Jak vykreslit šablonu
Jak vykreslit šablonu? Stačí k tomu tento jednoduchý kód:
$latte = new Latte\Engine;
// adresář pro cache
$latte->setTempDirectory('/path/to/tempdir');
$params = [ /* proměnné šablony */ ];
// or $params = new TemplateParameters(/* ... */);
// kresli na výstup
$latte->render('template.latte', $params);
// kresli do proměnné
$output = $latte->renderToString('template.latte', $params);
Parametry mohou být pole nebo ještě lépe objekt, který zajistí typovou kontrolu a napovídání v editorech.
Instalace
Nejlepší způsob, jak nainstalovat Latte, je pomocí Composeru:
composer require latte/latte
Podporované verze PHP (platí pro poslední setinkové verze Latte):
verze | kompatibilní s PHP |
---|---|
Latte 3.0 | PHP 8.0 – 8.1 |
Latte 2.8 – 2.11 | PHP 7.1 – 8.1 |
Výkon a cache
Šablony v Latte jsou rychlé, Latte je totiž kompiluje do PHP kódu a ukládá do cache na disk. Cache se automaticky regeneruje pokaždé, když změníte zdrojový soubor. Což můžete v produkčním prostředí vypnout a ušetřit tím malinko výkonu:
$latte->setAutoRefresh(false);
Při nasazení na produkčním serveru může prvotní vygenerování cache, zejména u rozsáhlejších aplikací, pochopitelně chviličku trvat. Latte má vestavěnou prevenci před cache stampede. Jde o situaci, kdy se sejde větší počet souběžných požadavků, které spustí Latte, a protože cache ještě neexistuje, začaly by ji všechny generovat současně. Což by neúměrně zatížilo server. Latte je chytré a při více souběžných požadavcích generuje cache pouze první vlákno, ostatní čekají a následně ji využíjí.
Parametry jako třída
Lepší než předávat proměnné do šablony jako pole je vytvořit si třídu. Získáte tak typově bezpečný zápis, příjemné napovídání v IDE a cestu pro registraci filtrů a funkcí.
class MailTemplateParameters
{
public function __construct(
public string $lang,
public Address $address,
public string $subject,
public array $items,
public ?float $price = null,
) {}
}
$latte->render('mail.latte', new MailTemplateParameters(
lang: $this->lang,
subject: $title,
price: $this->getPrice(),
items: [],
address: $userAddress,
));
Zákaz escapování parametru
Pokud parametr obsahuje řetězec v HTML, který už se nemá escapovat, zabalte jej do objektu
Latte\Runtime\Html
:
$params = [
'article_body' => new Latte\Runtime\Html($article->html_body),
];
Latte neescapuje nejen tyto objekty, ale všechny objekty implementující rozhraní Latte\HtmlStringable
.
Jak rozšířit Latte o filtry, značky atd.
Jak do Latte přidat vlastní filtr, funkci, značku atd? O tom pojednává kapitola rozšiřujeme Latte. Pokud chcete své úpravy znovu použít v různých projektech nebo je sdílet s ostatními, měli byste vytvořit rozšíření.
Libovolný kód v šabloně {php ...}
Uvnitř značky {do}
lze zapisovat pouze PHP výrazy, nemůžete tak třeba vložit
konstrukce jako if ... else
nebo statementy ukončené středníkem.
Můžete si však zaregistrovat rozšíření RawPhpExtension
, které přidá značku {php ...}
,
kterou lze vkládat jakýkoliv PHP kód na zodpovědnost autora šablony.
$latte->addExtension(new Latte\Essential\RawPhpExtension);
Překládání v šablonách
Pomocí rozšíření TranslatorExtension
přidáte do šablony značky {_...}
, {translate}
a filtr translate
. Slouží k překládání hodnot nebo částí šablony do jiných
jazyků. Překladačem je libovolný PHP callable:
$translator = function (string $original): string {
// tady z $original vytvoříme $translated
return $translated;
};
$latte->addExtension(new Latte\Essential\TranslatorExtension($translator));
Latte dokonce umí všechny statické texty přeložit už během kompilace šablony. V adresáři s cache tak vznikne více zkompilovaných verzí jedné šablony, jedna pro každý jazyk. K tomu stačí pouze uvést jazyk jako druhý parametr:
$latte->addExtension(new Latte\Essential\TranslatorExtension($translator, $lang));
Debuggování a Tracy
Latte se vám snaží vývoj co nejvíce zpříjemnit. Přímo pro účely debugování existuje trojice značek {dump}
, {debugbreak}
a {trace}
.
Největší komfort získáte, když ještě si nainstalujete skvělý ladicí nástroj Tracy a aktivujete doplněk pro Latte:
// zapne Tracy
Tracy\Debugger::enable();
// aktivuje doplněk
Latte\Bridges\Tracy\BlueScreenPanel::initialize();
Nyní se vám budou všechny chyby zobrazovat v přehledné červené obrazovce, včetně chyb v šablonách se zvýrazněním řádku a sloupce (video). Zároveň v pravém dolním rohu v tzv. Tracy Baru se objeví záložka pro Latte, kde jsou přehledně vidět všechny vykreslované šablony a jejich vzájemné vztahy (včetně možnosti se do šablony nebo zkompilovaného kódu prokliknout) a také proměnné:

Linter: validace syntaxe šablon
Projít všechny šablony a zkontrolovat, zda neobsahují syntaktické chyby, vám pomůže nástroj Linter. Spouští se z konzole:
vendor/bin/latte-lint <cesta>
Pokud používáte vlastní značky, vytvořte si také vlastní verzi Linteru, např. custom-latte-lint
:
#!/usr/bin/env php
<?php
// zadejte skutečnou cestu k soubor autoload.php
require __DIR__ . '/vendor/autoload.php';
$linter = new Latte\Tools\Linter($engine);
$linter->scanDirectory($path);
$engine = new Latte\Engine;
// tady zaregistruje jednotlivá rozšíření
$engine->addExtension(/* ... */);
$path = $argv[1];
$linter = new Latte\Tools\Linter(engine: $engine);
$ok = $linter->scanDirectory($path);
exit($ok ? 0 : 1);
Načítání šablon z řetězce
Potřebujete načítat šablony z řetězců místo souborů, třeba pro účely testování? Pomůže vám StringLoader:
$latte->setLoader(new Latte\Loaders\StringLoader([
'main.file' => '{include other.file}',
'other.file' => '{if true} {$var} {/if}',
]));
$latte->render('main.file', $params);
Exception handler
Můžete si definovat vlastní obslužný handler pro očekávané výjimky. Předají se mu výjimky vzniklé uvnitř {try}
a v sandboxu.
$loggingHandler = function (Throwable $e, Latte\Runtime\Template $template) use ($logger) {
$logger->log($e);
};
$latte = new Latte\Engine;
$latte->setExceptionHandler($loggingHandler);
Automatické dohledávání layoutu
Pomocí značky {layout}
šablona určuje svou
rodičovskou šablonu. Je taky možné nechat dohledávat layout automaticky, což zjednoduší psaní šablon, neboť v nich
nebude nutné značku {layout}
uvádět.
Dosáhne se toho následujícím způsobem:
$finder = function (Latte\Runtime\Template $template) {
if (!$template->getReferenceType()) {
// vrací cestu k souboru s layoutem
return 'automatic.layout.latte';
}
};
$latte = new Latte\Engine;
$latte->addProvider('coreParentFinder', $finder);
Pokud šablona nemá mít layout, oznámí to značkou {layout none}
.