Practici pentru dezvoltatori
****************************


Instalare .[#toc-installation]
==============================

Cel mai bun mod de a instala Latte este de a utiliza un Composer:

```shell
composer require latte/latte
```

Versiuni PHP acceptate (se aplică la cele mai recente versiuni Latte patch):

| versiune | compatibil cu PHP
|-----------------|-------------------
| Latte 3.0 | PHP 8.0 - 8.2


Cum se redă un șablon .[#toc-how-to-render-a-template]
======================================================

Cum se redă un șablon? Folosiți doar acest cod simplu:

```php
$latte = new Latte\Engine;
// director de cache
$latte->setTempDirectory('/path/to/tempdir');

$params = [ /* template variables */ ];
// sau $params = new TemplateParameters(/* ... */);

// redare la ieșire
$latte->render('template.latte', $params);
// sau redă în variabilă
$output = $latte->renderToString('template.latte', $params);
```

Parametrii pot fi array-uri sau chiar mai bine [obiecte |#Parameters as a class], care vor asigura verificarea tipului și sugestii în editor.

.[note]
Puteți găsi, de asemenea, exemple de utilizare în depozitul [Latte examples |https://github.com/nette-examples/latte].


Performanță și memorare în cache .[#toc-performance-and-caching]
================================================================

Șabloanele Latte sunt extrem de rapide, deoarece Latte le compilează direct în cod PHP și le stochează pe disc. Astfel, ele nu au niciun fel de costuri suplimentare în comparație cu șabloanele scrise în PHP pur.

Memoria cache este regenerată automat de fiecare dată când modificați fișierul sursă. Astfel, puteți edita comod șabloanele Latte în timpul dezvoltării și puteți vedea imediat modificările în browser. Puteți dezactiva această caracteristică într-un mediu de producție și economisi puțină performanță:

```php
$latte->setAutoRefresh(false);
```

Atunci când este implementat pe un server de producție, generarea inițială a cache-ului, în special pentru aplicațiile mari, poate dura, în mod normal, ceva timp. Latte are o prevenire încorporată împotriva "cache stampede":https://en.wikipedia.org/wiki/Cache_stampede.
Aceasta este o situație în care serverul primește un număr mare de solicitări simultane și, deoarece memoria cache a Latte nu există încă, toate acestea o vor genera în același timp. Ceea ce face ca CPU să crească brusc.
Latte este inteligent și, atunci când există mai multe cereri concurente, doar primul fir generează memoria cache, celelalte așteaptă și apoi o utilizează.


Parametrii ca o clasă .[#toc-parameters-as-a-class]
===================================================

Mai bine decât să transmiteți variabilele șablonului sub formă de array-uri este să creați o clasă. Obțineți o [notație sigură din punct de vedere al tipului |type-system], o [sugestie plăcută în IDE |recipes#Editors and IDE] și o modalitate de a [înregistra filtre |extending-latte#Filters Using the Class] și [funcții |extending-latte#Functions 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,
));
```


Dezactivarea scăpării automate a variabilelor .[#toc-disabling-auto-escaping-of-variable]
=========================================================================================

Dacă variabila conține un șir de caractere HTML, o puteți marca astfel încât Latte să nu o evadeze automat (și, prin urmare, dublu). Astfel, se evită necesitatea de a specifica `|noescape` în șablon.

Cea mai simplă metodă este să înfășurați șirul într-un obiect `Latte\Runtime\Html`:

```php
$params = [
	'articleBody' => new Latte\Runtime\Html($article->htmlBody),
];
```

De asemenea, Latte nu evadează toate obiectele care implementează interfața `Latte\HtmlStringable`. Astfel, vă puteți crea propria clasă a cărei metodă `__toString()` va returna codul HTML care nu va fi scăpat automat:

```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]
Metoda `__toString` trebuie să returneze HTML corect și să asigure scăparea parametrilor, altfel poate apărea o vulnerabilitate XSS!


Cum să extindeți Latte cu filtre, etichete etc. .[#toc-how-to-extend-latte-with-filters-tags-etc]
=================================================================================================

Cum să adăugați un filtru, o funcție, o etichetă etc. personalizat la Latte? Aflați în capitolul [Extinderea Latte |extending Latte].
Dacă doriți să refolosiți modificările în diferite proiecte sau dacă doriți să le partajați cu alții, ar trebui să [creați |creating-extension] apoi [o extensie |creating-extension].


Orice cod în șablon `{php ...}` .{toc: RawPhpExtension}
=======================================================

Doar expresiile PHP pot fi scrise în interiorul [`{do}` |tags#do] așa că nu puteți, de exemplu, să introduceți construcții precum `if ... else` sau instrucțiuni terminate cu punct și virgulă.

Cu toate acestea, puteți înregistra extensia `RawPhpExtension`, care adaugă eticheta `{php ...}`. Puteți folosi această extensie pentru a insera orice cod PHP. Aceasta nu face obiectul niciunei reguli de mod sandbox, astfel încât utilizarea este responsabilitatea autorului șablonului.

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


Verificarea codului generat .[#toc-checking-generated-code]{data-version:3.0.7}
===============================================================================

Latte compilează șabloanele în cod PHP. Bineînțeles, se asigură că codul generat este valid din punct de vedere sintactic. Cu toate acestea, atunci când se utilizează extensii de la terțe părți sau RawPhpExtension, Latte nu poate garanta corectitudinea fișierului generat.
De asemenea, în PHP, puteți scrie cod care este corect din punct de vedere sintactic, dar care este interzis (de exemplu, atribuirea unei valori variabilei $this) și care provoacă o eroare de compilare PHP.
Dacă scrieți o astfel de operațiune într-un șablon, aceasta va fi inclusă și în codul PHP generat. Deoarece există peste două sute de operații diferite interzise în PHP, Latte nu urmărește să le detecteze. PHP însuși le va semnala la redare, ceea ce, de obicei, nu reprezintă o problemă.

Cu toate acestea, există situații în care doriți să știți în timpul compilării șablonului că acesta nu conține erori de compilare PHP. Mai ales atunci când șabloanele pot fi editate de utilizatori sau când folosiți [Sandbox |Sandbox]. Într-un astfel de caz, dispuneți ca șabloanele să fie verificate în timpul compilării.
Puteți activa această funcționalitate folosind metoda Engine::enablePhpLint(). Deoarece trebuie să apeleze binarul PHP pentru verificare, treceți calea acestuia ca parametru:

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

try {
	$latte->compile('home.latte');
} catch (Latte\CompileException $e) {
	// prinde erori Latte și, de asemenea, erori de compilare în PHP
	echo 'Error: ' . $e->getMessage();
}
```


Local .[#toc-locale]{data-version:3.0.18}
=========================================

Latte vă permite să setați localele, care afectează formatarea numerelor, a datelor și sortarea. Aceasta este setată utilizând metoda `setLocale()`. Identificatorul locale urmează standardul IETF language tag, care utilizează extensia PHP `intl`. Acesta constă dintr-un cod de limbă și, eventual, un cod de țară, de exemplu, `en_US` pentru limba engleză în Statele Unite, `de_DE` pentru limba germană în Germania etc.

```php
$latte = new Latte\Engine;
$latte->setLocale('cs');
```

Setarea locale afectează filtrele [localDate |filters#localDate], [sort |filters#sort], [number |filters#number] și [bytes |filters#bytes].

.[note]
Necesită extensia PHP `intl`. Setarea din Latte nu afectează setarea locală globală din PHP.


Modul strict .[#toc-strict-mode]{data-version:3.0.8}
====================================================

În modul de analiză strictă, Latte verifică dacă lipsesc etichete HTML de închidere și, de asemenea, dezactivează utilizarea variabilei `$this`. Pentru a o activa:

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

Pentru a genera șabloane cu antetul `declare(strict_types=1)`, procedați după cum urmează:

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


Traducerea în șabloane .{toc: TranslatorExtension}
==================================================

Utilizați extensia `TranslatorExtension` pentru a adăuga [`{_...}` |tags#_], [`{translate}` |tags#translate] și să filtreze [`translate` |filters#translate] la șablon. Acestea sunt utilizate pentru a traduce valori sau părți ale șablonului în alte limbi. Parametrul este metoda (PHP callable) care efectuează traducerea:

```php
class MyTranslator
{
	public function __construct(private string $lang)
	{}

	public function translate(string $original): string
	{
		// creați $translated din $original în conformitate cu $this->lang
		return $translated;
	}
}

$translator = new MyTranslator($lang);
$extension = new Latte\Essential\TranslatorExtension(
	$translator->translate(...), // [$translator, 'translate'] în PHP 8.0
);
$latte->addExtension($extension);
```

Traducătorul este apelat în timpul execuției atunci când șablonul este redat. Cu toate acestea, Latte poate traduce toate textele statice în timpul compilării șablonului. Acest lucru economisește performanță, deoarece fiecare șir de caractere este tradus o singură dată, iar traducerea rezultată este scrisă în fișierul compilat. Astfel, se creează mai multe versiuni compilate ale șablonului în directorul cache, una pentru fiecare limbă. Pentru a face acest lucru, trebuie doar să specificați limba ca al doilea parametru:

```php
$extension = new Latte\Essential\TranslatorExtension(
	$translator->translate(...),
	$lang,
);
```

Prin text static înțelegem, de exemplu, `{_'hello'}` sau `{translate}hello{/translate}`. Textul nestatic, cum ar fi `{_$foo}`, va continua să fie tradus în timpul execuției.

Șablonul poate, de asemenea, să transmită parametrii suplimentari traducătorului prin intermediul `{_$original, foo: bar}` sau `{translate foo: bar}`, pe care acesta îi primește sub forma matricei `$params`:

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


Depanarea și Tracy .[#toc-debugging-and-tracy]
==============================================

Latte încearcă să facă dezvoltarea cât mai plăcută posibil. În scopuri de depanare, există trei etichete [`{dump}` |tags#dump], [`{debugbreak}` |tags#debugbreak] și [`{trace}` |tags#trace].

Veți obține cel mai mult confort dacă instalați instrumentul de depanare  excelent [Tracy |tracy:] și activați pluginul Latte:

```php
// permite Tracy
Tracy\Debugger::enable();

$latte = new Latte\Engine;
// activează extensia lui Tracy
$latte->addExtension(new Latte\Bridges\Tracy\TracyExtension);
```

Veți vedea acum toate erorile într-un ecran roșu îngrijit, inclusiv erorile din șabloane cu evidențierea rândurilor și coloanelor ([video |https://github.com/nette/tracy/releases/tag/v2.9.0]).
În același timp, în colțul din dreapta jos, în așa-numita Tracy Bar, apare o filă pentru Latte, unde puteți vedea clar toate șabloanele redate și relațiile dintre ele (inclusiv posibilitatea de a face clic în șablon sau în codul compilat), precum și variabilele:

[* latte-debugging.webp *]

Deoarece Latte compilează șabloanele în cod PHP lizibil, puteți să le parcurgeți în mod convenabil în IDE-ul dumneavoastră.


Linter: Validarea sintaxei șablonului .{toc: Linter}
====================================================

Instrumentul Linter vă va ajuta să treceți prin toate șabloanele și să verificați dacă există erori de sintaxă. Acesta se lansează din consolă:

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

Utilizați parametrul `--strict` pentru a activa [modul strict|#strict mode].

Dacă utilizați etichete personalizate, creați și Linterul personalizat, de exemplu `custom-latte-lint`:

```php
#!/usr/bin/env php
<?php

// introduceți calea reală către fișierul autoload.php
require __DIR__ . '/vendor/autoload.php';

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

$linter = new Latte\Tools\Linter;
$latte = $linter->getEngine();
// adăugați extensiile individuale aici
$latte->addExtension(/* ... */);

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

Alternativ, puteți transmite propriul obiect `Latte\Engine` către Linter:

```php
$latte = new Latte\Engine;
// aici configurăm obiectul $latte
$linter = new Latte\Tools\Linter(engine: $latte);
```


Încărcarea șabloanelor dintr-un șir de caractere .[#toc-loading-templates-from-a-string]
========================================================================================

Aveți nevoie să încărcați șabloane din șiruri de caractere în loc de fișiere, poate în scopuri de testare? [StringLoader |extending-latte#stringloader] vă va ajuta:

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

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


Manipulator de excepții .[#toc-exception-handler]
=================================================

Puteți defini propriul gestionar pentru excepțiile așteptate. Excepțiile ridicate în interiorul [`{try}` |tags#try] și în [sandbox |sandbox] sunt transmise către acesta.

```php
$loggingHandler = function (Throwable $e, Latte\Runtime\Template $template) use ($logger) {
	$logger->log($e);
};

$latte = new Latte\Engine;
$latte->setExceptionHandler($loggingHandler);
```


Căutarea automată a aspectului .[#toc-automatic-layout-lookup]
==============================================================

Utilizarea tag-ului [`{layout}` |template-inheritance#layout-inheritance], șablonul își determină șablonul părinte. De asemenea, este posibil ca aspectul să fie căutat automat, ceea ce va simplifica scrierea șabloanelor, deoarece acestea nu vor trebui să includă eticheta `{layout}`.

Acest lucru se realizează după cum urmează:

```php
$finder = function (Latte\Runtime\Template $template) {
	if (!$template->getReferenceType()) {
		// returnează calea către fișierul șablon părinte
		return 'automatic.layout.latte';
	}
};

$latte = new Latte\Engine;
$latte->addProvider('coreParentFinder', $finder);
```

În cazul în care șablonul nu trebuie să aibă un aspect, acesta va indica acest lucru cu ajutorul etichetei `{layout none}`.