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

Инсталация

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

composer require latte/latte

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

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

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

$latte = new Latte\Engine;
// директория за кеша
$latte->setTempDirectory('/path/to/tempdir');

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

// рендиране към изхода
$latte->render('template.latte', $params);
// рендиране в променлива
$output = $latte->renderToString('template.latte', $params);

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

Примери за употреба ще намерите също в хранилището Latte examples.

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

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

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

$latte->setAutoRefresh(false);

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

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

По-добре от предаването на променливи към шаблона като масив е да създадете клас. Така ще получите типово безопасен запис, приятно подсказване в IDE и път за регистрация на филтри и функции.

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:

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

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

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

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

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

Как да добавим към Latte собствен филтър, функция, таг и т.н.? За това се говори в главата разширяваме Latte. Ако искате да използвате повторно своите модификации в различни проекти или да ги споделите с други, трябва да създадете разширение.

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

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

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

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

Проверка на генерирания код

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

Има обаче ситуации, когато искате да знаете още по време на компилацията на шаблона, че той не съдържа никакъв PHP Compile Error. Особено тогава, когато шаблоните могат да бъдат редактирани от потребители, или използвате Sandbox. В такъв случай оставете шаблоните да се проверяват още по време на компилацията. Тази функционалност се включва с метода Engine::enablePhpLint(). Тъй като за проверката е необходимо да се извика бинарният файл на 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();
}

Национална среда

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

$latte = new Latte\Engine;
$latte->setLocale('bg_BG');

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

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

Стриктен режим

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

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

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

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

Превод в шаблони

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

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 обаче може да превежда всички статични текстове още по време на компилацията на шаблона. Така се пести производителност, тъй като всеки низ се превежда само веднъж и резултатният превод се записва в компилираната форма. В директорията с кеша така възникват повече компилирани версии на шаблона, по една за всеки език. За това е достатъчно само да се посочи езикът като втори параметър:

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

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

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

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

Дебъгване и Tracy

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

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

// включва Tracy
Tracy\Debugger::enable();

$latte = new Latte\Engine;
// активира разширението за Tracy
$latte->addExtension(new Latte\Bridges\Tracy\TracyExtension);

Сега всички грешки ще се показват в прегледен червен екран, включително грешките в шаблоните с подчертаване на ред и колона (видео). Същевременно в долния десен ъгъл в т.нар. Tracy Bar ще се появи раздел за Latte, където са прегледно показани всички рендирани шаблони и техните взаимни връзки (включително възможността да се кликне към шаблона или компилирания код) и също променливите:

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

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

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

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

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

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

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

$latte = new Latte\Engine;
// тук конфигурираме обекта $latte
$linter = new Latte\Tools\Linter(engine: $latte);

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

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

$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} и в sandbox.

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

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

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

С помощта на тага {layout} шаблонът определя своя родителски шаблон. Възможно е също да се остави автоматичното намиране на лейаута, което ще опрости писането на шаблони, тъй като в тях няма да е необходимо да се посочва тагът {layout}.

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

$finder = function (Latte\Runtime\Template $template) {
	if (!$template->getReferenceType()) {
		// връща пътя до файла с лейаута
		return 'automatic.layout.latte';
	}
};

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

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