Практики за разработка

**********************

Инсталация

==========

Най-добрият начин да инсталирате Latte е с помощта на Composer:

```shell

composer require latte/latte

```

Поддържани версии на PHP (важи за последните минорни версии на Latte):

| версия | съвместима с PHP

|-----------------|-------------------

| Latte 3.0 | PHP 8.0 – 8.2

Как да рендираме шаблон

=======================

Как да рендираме шаблон? Достатъчен е този прост код:

```php

$latte = new Latte\Engine;

// директория за кеша

$latte->setTempDirectory('/path/to/tempdir');

$params = [ /* променливи на шаблона */ ];

// или $params = new TemplateParameters(/* ... */);

// рендиране към изхода

$latte->render('template.latte', $params);

// рендиране в променлива

$output = $latte->renderToString('template.latte', $params);

```

Параметрите могат да бъдат масив или още по-добре [обект |#Параметри като клас], който ще осигури проверка на типовете и подсказване в редакторите.

.[note]

Примери за употреба ще намерите също в хранилището [Latte examples |https://github.com/nette-examples/latte].

Производителност и кеш

======================

Шаблоните в Latte са изключително бързи, Latte ги компилира директно в PHP код и ги съхранява в кеш на диска. По този начин те нямат никакви допълнителни разходи в сравнение с шаблони, написани на чист PHP.

Кешът се регенерира автоматично всеки път, когато промените изходния файл. По време на разработката можете удобно да редактирате шаблоните в Latte и веднага да виждате промените в браузъра. Тази функция може да бъде изключена в продукционна среда, за да се спести малко производителност:

```php

$latte->setAutoRefresh(false);

```

При разгръщане на продукционен сървър първоначалното генериране на кеша, особено при по-големи приложения, може разбира се да отнеме малко време. Latte има вградена превенция срещу "cache stampede":https://en.wikipedia.org/wiki/Cache_stampede. Това е ситуация, при която се събират по-голям брой едновременни заявки, които стартират Latte, и тъй като кешът все още не съществува, всички биха започнали да го генерират едновременно. Което би натоварило неимоверно сървъра. Latte е умен и при повече едновременни заявки генерира кеша само първата нишка, останалите чакат и след това го използват.

Параметри като клас

===================

По-добре от предаването на променливи към шаблона като масив е да създадете клас. Така ще получите [типово безопасен запис|type-system], [приятно подсказване в IDE |recipes#Редактори и IDE] и път за [регистрация на филтри |custom-filters#Филтри използващи клас с атрибути] и [функции |custom-functions#Функции използващи клас с атрибути].

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

));

```

Изключване на автоматичното екраниране на променлива

====================================================

Ако променливата съдържа низ в HTML, можете да я маркирате така, че Latte да не я екранира автоматично (и следователно двойно). Така ще избегнете нуждата да посочвате в шаблона `|noescape`.

Най-лесният начин е да обвиете низа в обект `Latte\Runtime\Html`:

```php

$params = [

'articleBody' => new Latte\Runtime\Html($article->htmlBody),

];

```

Latte освен това не екранира всички обекти, които имплементират интерфейса `Latte\HtmlStringable`. Можете така да създадете собствен клас, чийто метод `__toString()` ще връща HTML код, който няма да се екранира автоматично:

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

Методът `__toString` трябва да връща коректен HTML и да осигури екраниране на параметрите, иначе може да възникне уязвимост XSS!

Как да разширим Latte с филтри, тагове и т.н.

=============================================

Как да добавим към Latte собствен филтър, функция, таг и т.н.? За това се говори в главата [разширяваме Latte |extending-latte]. Ако искате да използвате повторно своите модификации в различни проекти или да ги споделите с други, трябва да [създадете разширение |extending-latte#Latte Extension].

Произволен код в шаблона `{php ...}` .{toc: RawPhpExtension}

============================================================

Вътре в тага [`{do}` |tags#do] могат да се записват само PHP изрази, не можете например да вмъкнете конструкции като `if ... else` или стейтмънти, завършващи с точка и запетая.

Можете обаче да регистрирате разширението `RawPhpExtension`, което добавя тага `{php ...}`. С помощта на него може да се вмъква всякакъв PHP код. За него не важат никакви правила на sandbox режима, използването му е отговорност на автора на шаблона.

```php

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

```

Проверка на генерирания код .{data-version:3.0.7}

=================================================

Latte компилира шаблоните в PHP код. Разбира се, той се грижи генерираният код да бъде синтактично валиден. Въпреки това, при използване на разширения от трети страни или `RawPhpExtension`, Latte не може да гарантира коректността на генерирания файл. Също така в PHP може да се запише код, който макар и синтактично правилен, е забранен (например присвояване на стойност на променливата `$this`) и причинява PHP Compile Error. Ако запишете такава операция в шаблона, тя ще попадне и в генерирания PHP код. Тъй като в PHP съществуват около двеста различни забранени операции, Latte няма амбицията да ги открива. За тях ще предупреди едва самият PHP при рендиране, което обикновено не пречи на нищо.

Има обаче ситуации, когато искате да знаете още по време на компилацията на шаблона, че той не съдържа никакъв PHP Compile Error. Особено тогава, когато шаблоните могат да бъдат редактирани от потребители, или използвате [Sandbox]. В такъв случай оставете шаблоните да се проверяват още по време на компилацията. Тази функционалност се включва с метода `Engine::enablePhpLint()`. Тъй като за проверката е необходимо да се извика бинарният файл на PHP, предайте пътя до него като параметър:

```php

$latte = new Latte\Engine;

$latte->enablePhpLinter('/path/to/php');

try {

$latte->compile('home.latte');

} catch (Latte\CompileException $e) {

// улавя грешки в Latte, както и Compile Error в PHP

echo 'Error: ' . $e->getMessage();

}

```

Национална среда .{data-version:3.0.18}{toc: Locale}

====================================================

Latte позволява да се настрои национална среда, която влияе на форматирането на числа, дати и сортирането. Настройва се с помощта на метода `setLocale()`. Идентификаторът на средата се ръководи от стандарта IETF language tag, който използва разширението на PHP `intl`. Състои се от кода на езика и евентуално кода на страната, напр. `en_US` за английски в Съединените щати, `de_DE` за немски в Германия и т.н.

```php

$latte = new Latte\Engine;

$latte->setLocale('bg_BG');

```

Настройката на средата влияе на филтрите [localDate |filters#localDate], [sort |filters#sort], [number |filters#number] и [bytes |filters#bytes].

.[note]

Изисква PHP разширението `intl`. Настройката в Latte не влияе на глобалната настройка на locale в PHP.

Стриктен режим .{data-version:3.0.8}

====================================

В стриктен режим на парсиране Latte контролира дали не липсват затварящи HTML тагове и също забранява използването на променливата `$this`. Включвате го така:

```php

$latte = new Latte\Engine;

$latte->setStrictParsing();

```

Генерирането на шаблони с хедър `declare(strict_types=1)` включвате така:

```php

$latte = new Latte\Engine;

$latte->setStrictTypes();

```

Превод в шаблони .{toc: TranslatorExtension}

============================================

С помощта на разширението `TranslatorExtension` добавяте към шаблона тагове [`{_...}` |tags#], [`{translate}` |tags#translate] и филтър [`translate` |filters#translate]. Служат за превод на стойности или части от шаблона на други езици. Като параметър посочваме метод (PHP callable), извършващ превода:

```php

class MyTranslator

{

public function __construct(private string $lang)

{}

public function translate(string $original): string

{

// от $original създаваме $translated според $this->lang

return $translated;

}

}

$translator = new MyTranslator($lang);

$extension = new Latte\Essential\TranslatorExtension(

$translator->translate(...), // [$translator, 'translate'] в PHP 8.0

);

$latte->addExtension($extension);

```

Преводачът се извиква по време на изпълнение при рендиране на шаблона. Latte обаче може да превежда всички статични текстове още по време на компилацията на шаблона. Така се пести производителност, тъй като всеки низ се превежда само веднъж и резултатният превод се записва в компилираната форма. В директорията с кеша така възникват повече компилирани версии на шаблона, по една за всеки език. За това е достатъчно само да се посочи езикът като втори параметър:

```php

$extension = new Latte\Essential\TranslatorExtension(

$translator->translate(...),

$lang,

);

```

Статичен текст означава например `{_'hello'}` или `{translate}hello{/translate}`. Нестатичните текстове, като например `{_$foo}`, ще продължат да се превеждат по време на изпълнение.

На преводача могат от шаблона да се предават и допълнителни параметри с помощта на `{_$original, foo: bar}` или `{translate foo: bar}`, които той получава като масив `$params`:

```php

public function translate(string $original, ...$params): string

{

// $params['foo'] === 'bar'

}

```

Дебъгване и Tracy

=================

Latte се опитва да ви улесни разработката колкото е възможно повече. Директно за целите на дебъгването съществуват три тага [`{dump}` |tags#dump], [`{debugbreak}` |tags#debugbreak] и [`{trace}` |tags#trace].

Най-голям комфорт ще получите, ако още си инсталирате страхотния [инструмент за отстраняване на грешки Tracy|tracy:] и активирате добавката за Latte:

```php

// включва Tracy

Tracy\Debugger::enable();

$latte = new Latte\Engine;

// активира разширението за Tracy

$latte->addExtension(new Latte\Bridges\Tracy\TracyExtension);

```

Сега всички грешки ще се показват в прегледен червен екран, включително грешките в шаблоните с подчертаване на ред и колона ([видео|https://github.com/nette/tracy/releases/tag/v2.9.0]). Същевременно в долния десен ъгъл в т.нар. Tracy Bar ще се появи раздел за Latte, където са прегледно показани всички рендирани шаблони и техните взаимни връзки (включително възможността да се кликне към шаблона или компилирания код) и също променливите:

[* latte-debugging.webp *]

Тъй като Latte компилира шаблоните в прегледен PHP код, можете удобно да ги стъпвате във вашето IDE.

Linter: валидиране на синтаксиса на шаблони .{toc: Linter}

==========================================================

Да преминете през всички шаблони и да проверите дали не съдържат синтактични грешки, ще ви помогне инструментът Linter. Стартира се от конзолата:

```shell

vendor/bin/latte-lint <път>

```

С параметъра `--strict` активирате [#стриктен режим].

Ако използвате собствени тагове, създайте си и собствена версия на Linter, напр. `custom-latte-lint`:

```php

#!/usr/bin/env php

<?php

// въведете реалния път до файла autoload.php

require __DIR__ . '/vendor/autoload.php';

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

$linter = new Latte\Tools\Linter;

$latte = $linter->getEngine();

// тук добавете вашите индивидуални разширения

$latte->addExtension(/* ... */);

$ok = $linter->scanDirectory($path);

exit($ok ? 0 : 1);

```

Алтернативно можете да предадете собствен обект `Latte\Engine` на Linter:

```php

$latte = new Latte\Engine;

// тук конфигурираме обекта $latte

$linter = new Latte\Tools\Linter(engine: $latte);

```

Зареждане на шаблони от низ

===========================

Трябва ли ви да зареждате шаблони от низове вместо от файлове, например за целите на тестване? Ще ви помогне [StringLoader |loaders#StringLoader]:

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

=================

Можете да дефинирате собствен обслужващ handler за очаквани изключения. Ще му бъдат предадени изключенията, възникнали вътре в [`{try}` |tags#try] и в [sandbox|sandbox].

```php

$loggingHandler = function (Throwable $e, Latte\Runtime\Template $template) use ($logger) {

$logger->log($e);

};

$latte = new Latte\Engine;

$latte->setExceptionHandler($loggingHandler);

```

Автоматично намиране на лейаут

==============================

С помощта на тага [`{layout}` |template-inheritance#Наследяване на лейаут] шаблонът определя своя родителски шаблон. Възможно е също да се остави автоматичното намиране на лейаута, което ще опрости писането на шаблони, тъй като в тях няма да е необходимо да се посочва тагът `{layout}`.

Това се постига по следния начин:

```php

$finder = function (Latte\Runtime\Template $template) {

if (!$template->getReferenceType()) {

// връща пътя до файла с лейаута

return 'automatic.layout.latte';

}

};

$latte = new Latte\Engine;

$latte->addProvider('coreParentFinder', $finder);

```

Ако шаблонът не трябва да има лейаут, той го обявява с тага `{layout none}`.