Gyakorlatok fejlesztőknek
Telepítés
A Latte telepítésének legjobb módja a Composer használata:
composer require latte/latte
Támogatott PHP-verziók (a legújabb javított Latte-verziókra vonatkozik):
verzió | kompatibilis a PHP-vel |
---|---|
Latte 3.0 | PHP 8.0 – 8.2 |
Latte 2.11 | PHP 7.1 – 8.2 |
Latte 2.8 – 2.10 | PHP 7.1 – 8.1 |
Sablonok renderelése
Hogyan kell renderelni egy sablont? Csak használja ezt az egyszerű kódot:
$latte = new Latte\Engine;
// cache könyvtár
$latte->setTempDirectory('/path/to/tempdir');
$params = [ /* sablonváltozók */ ];
// vagy $params = new TemplateParameters(/* ... */);
// renderelés a kimenetre
$latte->render('template.latte', $params);
// vagy renderelés változóba
$output = $latte->renderToString('template.latte', $params);
A paraméterek lehetnek tömbök vagy még jobb objektumok, amelyek típusellenőrzést és javaslatot biztosítanak a szerkesztőben.
Használati példákat is talál a Latte examples tárolóban.
Teljesítmény és gyorsítótárazás
A Latte sablonok rendkívül gyorsak, mivel a Latte közvetlenül PHP kóddá fordítja őket, és a lemezen gyorsítótárba helyezi őket. Így a tisztán PHP nyelven írt sablonokhoz képest nincs extra többletköltségük.
A gyorsítótár automatikusan újratermelődik minden alkalommal, amikor megváltoztatja a forrásfájlt. Így a fejlesztés során kényelmesen szerkesztheti a Latte sablonokat, és a változásokat azonnal láthatja a böngészőben. Termelési környezetben kikapcsolhatja ezt a funkciót, és ezzel egy kis teljesítményt takaríthat meg:
$latte->setAutoRefresh(false);
Termelőszerverre telepítve a kezdeti gyorsítótár-generálás, különösen a nagyobb alkalmazások esetében, érthető módon eltarthat egy ideig. A Latte beépített megelőzéssel rendelkezik a cache stampede ellen. Ez az a helyzet, amikor a szerver nagyszámú egyidejű kérést kap, és mivel a Latte gyorsítótár még nem létezik, ezek mind egyszerre generálnák azt. Ami felpörgeti a CPU-t. A Latte okos, és több egyidejű kérés esetén csak az első szál generálja a cache-t, a többiek várnak, majd használják azt.
Paraméterek mint osztály
Jobb, mintha a változókat tömbként adnánk át a sablonhoz, ha egy osztályt hozunk létre. Így típusbiztos jelölést, szép javaslatot kapunk az IDE-ben, és lehetőségünk van szűrők és függvények regisztrálására.
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,
));
A változó automatikus kikerülésének letiltása
Ha a változó HTML karakterláncot tartalmaz, akkor megjelölheti, hogy a Latte automatikusan (és ezért duplán) ne lépjen
ki belőle. Ezzel elkerülhető a |noescape
megadása a sablonban.
A legegyszerűbb, ha a karakterláncot egy Latte\Runtime\Html
objektumba csomagoljuk:
$params = [
'articleBody' => new Latte\Runtime\Html($article->htmlBody),
];
A Latte nem lép ki minden olyan objektumot, amely megvalósítja a Latte\HtmlStringable
interfészt. Így
létrehozhatsz egy saját osztályt, amelynek __toString()
metódusa olyan HTML kódot ad vissza, amely nem lesz
automatikusan eszkábálva:
class Emphasis extends Latte\HtmlStringable
{
public function __construct(
private string $str,
) {
}
public function __toString(): string
{
return '<em>' . htmlspecialchars($this->str) . '</em>';
}
}
$params = [
'foo' => new Emphasis('hello'),
];
A __toString
metódusnak helyes HTML-t kell visszaadnia, és biztosítania kell a paraméterek
eszkábálását, különben XSS sebezhetőség léphet fel!
Hogyan bővítsük a Latte-t szűrőkkel, címkékkel stb.
Hogyan adhatunk hozzá egyéni szűrőt, funkciót, címkét stb. a Latte-hoz? Megtudhatja a Latte bővítése című fejezetben. Ha a módosításait különböző projektekben szeretné újra felhasználni, vagy ha meg akarja osztani másokkal, akkor hozzon létre egy kiterjesztést.
Bármilyen kód a sablonban {php ...}
Csak PHP kifejezéseket lehet írni a {do}
taget, így
például nem lehet olyan konstrukciókat beilleszteni, mint a if ... else
vagy a pontosvesszővel végződő
utasítások.
Regisztrálhatja azonban a RawPhpExtension
bővítményt, amely hozzáadja a {php ...}
taget, amely a
sablon szerzőjének felelősségére bármilyen PHP-kód beillesztésére használható.
$latte->addExtension(new Latte\Essential\RawPhpExtension);
Fordítás a sablonokban
A TranslatorExtension
kiterjesztés használatával {_...}
, {translate}
és szűrje translate
a sablonhoz. Ezek a sablon értékeinek vagy
részeinek más nyelvekre történő lefordítására szolgálnak. A paraméter az a metódus (PHP hívható), amely a
fordítást elvégzi:
class MyTranslator
{
public function __construct(private string $lang)
{}
public function translate(string $original): string
{
// $translated létrehozása $originalból a $this->langnak megfelelően
return $translated;
}
}
$translator = new MyTranslator($lang);
$extension = new Latte\Essential\TranslatorExtension(
$translator->translate(...), // [$translator, 'translate'] a PHP 8.0-ban
);
$latte->addExtension($extension);
A fordítót a sablon megjelenítésekor, futásidőben hívja meg a rendszer. A Latte azonban minden statikus szöveget le tud fordítani a sablon összeállítása során. Ez teljesítményt takarít meg, mivel minden karakterláncot csak egyszer fordít le, és az így kapott fordítás a lefordított fájlba kerül. Ez a sablon több lefordított változatát hozza létre a gyorsítótárban, egyet-egyet minden nyelvhez. Ehhez csak a nyelvet kell megadni második paraméterként:
$extension = new Latte\Essential\TranslatorExtension(
$translator->translate(...),
$lang,
);
Statikus szöveg alatt például a {_'hello'}
vagy a {translate}hello{/translate}
szöveget értjük.
A nem statikus szövegek, például a {_$foo}
, futásidőben továbbra is le lesznek fordítva.
A sablon további paramétereket is átadhat a fordítónak a {_$original, foo: bar}
vagy a
{translate foo: bar}
oldalon keresztül, amelyeket a $params
tömbként kap meg:
public function translate(string $original, ...$params): string
{
// $params['foo'] === 'bar'
}
Hibakeresés és Tracy
Latte igyekszik a fejlesztést a lehető legkellemesebbé tenni. A hibakereséshez három címke áll rendelkezésre {dump}
, {debugbreak}
és {trace}
.
A legnagyobb kényelmet akkor kapja, ha telepíti a nagyszerű hibakereső eszközt Tracy és aktiválja a Latte plugint:
// lehetővé teszi Tracy
Tracy\Debugger::enable();
$latte = new Latte\Engine;
// aktiválja Tracy mellékét
$latte->addExtension(new Latte\Bridges\Tracy\TracyExtension);
Mostantól minden hibát egy takaros piros képernyőn fogsz látni, beleértve a sablonok hibáit is, sor- és oszlopkiemeléssel (videó). Ugyanakkor a jobb alsó sarokban, az úgynevezett Tracy Barban megjelenik a Latte fülecske, ahol jól látható az összes renderelt sablon és azok kapcsolatai (beleértve a sablonba vagy a fordított kódba való kattintás lehetőségét), valamint a változók:

Mivel a Latte a sablonokat olvasható PHP-kóddá fordítja le, kényelmesen lépkedhetsz rajtuk az IDE-ben.
Linter: A sablon szintaxisának validálása
A Linter eszköz segít átnézni az összes sablont, és ellenőrizni a szintaxis hibákat. A konzolról indítható:
vendor/bin/latte-lint <path>
Ha egyéni címkéket használ, hozza létre az egyéni Lintert is, például custom-latte-lint
:
#!/usr/bin/env php
<?php
// adja meg az autoload.php fájl tényleges elérési útvonalát
require __DIR__ . '/vendor/autoload.php';
$linter = new Latte\Tools\Linter($engine);
$linter->scanDirectory($path);
$engine = new Latte\Engine;
// itt regisztrálja az egyes kiterjesztéseket
$engine->addExtension(/* ... */);
$path = $argv[1];
$linter = new Latte\Tools\Linter(engine: $engine);
$ok = $linter->scanDirectory($path);
exit($ok ? 0 : 1);
Sablonok betöltése egy karakterláncból
Fájlok helyett karakterláncokból kell sablonokat betöltenie, esetleg tesztelési céllal? A StringLoader segít Önnek:
$latte->setLoader(new Latte\Loaders\StringLoader([
'main.file' => '{include other.file}',
'other.file' => '{if true} {$var} {/if}',
]));
$latte->render('main.file', $params);
Exception Handler
Saját kezelőt definiálhat a várható kivételekhez. Az alábbiakban felvetett kivételek {try}
és a homokozóban keletkeznek, átadódnak neki.
$loggingHandler = function (Throwable $e, Latte\Runtime\Template $template) use ($logger) {
$logger->log($e);
};
$latte = new Latte\Engine;
$latte->setExceptionHandler($loggingHandler);
Automatikus elrendezés keresés
A címke használata {layout}
, a sablon meghatározza a
szülő sablonját. Lehetőség van arra is, hogy az elrendezést automatikusan keressük, ami egyszerűsíti a sablonok
írását, mivel nem kell tartalmazniuk a {layout}
taget.
Ez a következőképpen érhető el:
$finder = function (Latte\Runtime\Template $template) {
if (!$template->getReferenceType()) {
// a szülő sablon fájl elérési útvonalát adja vissza
return 'automatic.layout.latte';
}
};
$latte = new Latte\Engine;
$latte->addProvider('coreParentFinder', $finder);
Ha a sablon nem rendelkezik elrendezéssel, akkor ezt a {layout none}
címkével jelzi.