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):

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 ...} címkét. Ezzel bármilyen PHP-kódot beilleszthet. Nem vonatkoznak rá a sandbox mód szabályai, így használata a sablon szerzőjének felelőssége.

$latte->addExtension(new Latte\Essential\RawPhpExtension);

Generált kód ellenőrzése

A Latte a sablonokat PHP kóddá fordítja. Természetesen biztosítja, hogy a generált kód szintaktikailag érvényes legyen. Azonban harmadik féltől származó kiterjesztések vagy a RawPhpExtension használata esetén a Latte nem tudja garantálni a generált fájl helyességét. Emellett a PHP-ben írhat olyan kódot is, amely szintaktikailag helyes, de tiltott (például értéket rendel a $this változóhoz), és PHP Compile Error-t okoz. Ha ilyen műveletet ír egy sablonba, akkor az a generált PHP-kódban is benne lesz. Mivel a PHP-ban több mint kétszáz különböző tiltott művelet létezik, a Latte nem törekszik ezek felismerésére. A PHP maga jelzi őket rendereléskor, ami általában nem jelent problémát.

Vannak azonban olyan helyzetek, amikor a sablon fordítása során tudni szeretné, hogy az nem tartalmaz-e PHP Compile Errors-t (PHP fordítási hibát). Különösen akkor, ha a sablonokat a felhasználók szerkeszthetik, vagy ha Sandboxot használ. Ilyen esetben ellenőrizze a sablonokat a fordítás során. Ezt a funkciót az Engine::enablePhpLint() metódus segítségével aktiválhatja. Mivel az ellenőrzéshez meg kell hívnia a PHP binárisát, adja meg annak elérési útját paraméterként:

$latte = new Latte\Engine;
$latte->enablePhpLinter('/path/to/php');

try {
	$latte->compile('home.latte');
} catch (Latte\CompileException $e) {
	// elkapja a Latte hibákat és a Compile Error-t a PHP-ban
	echo 'Error: ' . $e->getMessage();
}

Szigorú üzemmód

Szigorú elemzési módban a Latte ellenőrzi a hiányzó záró HTML-címkéket, és letiltja a $this változó használatát. Bekapcsolásához:

$latte = new Latte\Engine;
$latte->setStrictParsing();

A declare(strict_types=1) fejléccel rendelkező sablonok generálásához tegye a következőket:

$latte = new Latte\Engine;
$latte->setStrictTypes();

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>

A --strict paraméterrel aktiválhatja a szigorú üzemmódot.

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';

$path = $argv[1] ?? '.';

$linter = new Latte\Tools\Linter;
$latte = $linter->getEngine();
// itt adja hozzá az egyéni kiterjesztéseket
$latte->addExtension(/* ... */);

$ok = $linter->scanDirectory($path);
exit($ok ? 0 : 1);

Alternatívaként átadhatja saját Latte\Engine objektumát is a Linter-nek:

$latte = new Latte\Engine;
// itt konfiguráljuk a $latte objektumot
$linter = new Latte\Tools\Linter(engine: $latte);

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.