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 ...} 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.