Gyakorlatok fejlesztőknek
*************************


Telepítés .[#toc-installation]
==============================

A Latte telepítésének legjobb módja a Composer használata:

```shell
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


Sablonok renderelése .[#toc-how-to-render-a-template]
=====================================================

Hogyan kell renderelni egy sablont? Csak használja ezt az egyszerű kódot:

```php
$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 |#Parameters as a class], amelyek típusellenőrzést és javaslatot biztosítanak a szerkesztőben.

.[note]
Használati példákat is talál a [Latte examples |https://github.com/nette-examples/latte] tárolóban.


Teljesítmény és gyorsítótárazás .[#toc-performance-and-caching]
===============================================================

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:

```php
$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":https://en.wikipedia.org/wiki/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 .[#toc-parameters-as-a-class]
======================================================

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 |type-system], [szép javaslatot |recipes#Editors and IDE] kapunk az [IDE-ben |recipes#Editors and IDE], és lehetőségünk van [szűrők |extending-latte#Filters Using the Class] és [függvények |extending-latte#Functions Using the Class] [regisztrálására |extending-latte#Filters Using the Class].

```php
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 .[#toc-disabling-auto-escaping-of-variable]
=========================================================================================

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:

```php
$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:

```php
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'),
];
```

.[warning]
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. .[#toc-how-to-extend-latte-with-filters-tags-etc]
=====================================================================================================

Hogyan adhatunk hozzá egyéni szűrőt, funkciót, címkét stb. a Latte-hoz? Megtudhatja a [Latte bővítése |extending Latte] 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 |creating-extension].


Bármilyen kód a sablonban `{php ...}` .{toc: RawPhpExtension}
=============================================================

Csak PHP kifejezéseket lehet írni a [`{do}` |tags#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.

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


Generált kód ellenőrzése .[#toc-checking-generated-code]{data-version:3.0.7}
============================================================================

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 |Sandbox] 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:

```php
$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 .[#toc-strict-mode]{data-version:3.0.8}
=======================================================

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:

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

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

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


Fordítás a sablonokban .{toc: TranslatorExtension}
==================================================

A `TranslatorExtension` kiterjesztés használatával [`{_...}` |tags#_], [`{translate}` |tags#translate] és szűrje [`translate` |filters#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:

```php
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:

```php
$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:

```php
public function translate(string $original, ...$params): string
{
	// $params['foo'] === 'bar'
}
```


Hibakeresés és Tracy .[#toc-debugging-and-tracy]
================================================

Latte igyekszik a fejlesztést a lehető legkellemesebbé tenni. A hibakereséshez három címke áll rendelkezésre [`{dump}` |tags#dump], [`{debugbreak}` |tags#debugbreak] és [`{trace}` |tags#trace].

A legnagyobb kényelmet akkor kapja, ha telepíti a nagyszerű [hibakereső eszközt Tracy |tracy:] és aktiválja a Latte plugint:

```php
// 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ó |https://github.com/nette/tracy/releases/tag/v2.9.0]).
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:

[* latte-debugging.webp *]

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 .{toc: Linter}
========================================================

A Linter eszköz segít átnézni az összes sablont, és ellenőrizni a szintaxis hibákat. A konzolról indítható:

```shell
vendor/bin/latte-lint <path>
```

A `--strict` paraméterrel aktiválhatja a [szigorú üzemmódot|#strict mode].

Ha egyéni címkéket használ, hozza létre az egyéni Lintert is, például `custom-latte-lint`:

```php
#!/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:

```php
$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 .[#toc-loading-templates-from-a-string]
==============================================================================

Fájlok helyett karakterláncokból kell sablonokat betöltenie, esetleg tesztelési céllal? A [StringLoader |extending-latte#stringloader] segít Önnek:

```php
$latte->setLoader(new Latte\Loaders\StringLoader([
	'main.file' => '{include other.file}',
	'other.file' => '{if true} {$var} {/if}',
]));

$latte->render('main.file', $params);
```


Exception Handler .[#toc-exception-handler]
===========================================

Saját kezelőt definiálhat a várható kivételekhez. Az alábbiakban felvetett kivételek [`{try}` |tags#try] és a [homokozóban |sandbox] keletkeznek, átadódnak neki.

```php
$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 .[#toc-automatic-layout-lookup]
==============================================================

A címke használata [`{layout}` |template-inheritance#layout-inheritance], 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:

```php
$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.