Latte: как использовать систему типов?

Знание того, к какому типу данных или объектов относится каждая переменная, позволяет

• IDE корректно автозаполнять
• статический анализ для обнаружения ошибок

Два момента, которые значительно повышают качество и удобство разработки.

Как объявлять типы на стороне PHP?

Мы будем передавать данные в шаблон как объект класса, в котором определены все переменные и их типы. Используя новые возможности PHP 7.4, это может выглядеть следующим образом:

class MailTemplate
{
	public string $lang = 'cs';
	public Address $address;
	public string $subject;
	public ?float $price = null;
}

Использование:

$template = new MailTemplate;
$template->price = $this->getPrice();
...
$latte->render('mail.latte', $template);

Дополнение: благодаря новым возможностям PHP 8, пример может быть написан более интересным образом:

class MailTemplate
{
	public function __construct(
		public string $lang = 'cs',
		public Address $address,
		public string $subject,
		public ?float $price = null,
	) {}
}

$latte->render('mail.latte', new MailTemplate(
	lang: $this->lang,
	subject: $title,
	price: $this->getPrice(),
	address: $userAddress,
));

Как объявить типы в шаблоне?

Теперь мы можем связать этот класс с шаблоном. Нам просто нужно указать его в самом начале:

{templateType MailTemplate}

И этим мы определили, что шаблон будет содержать квартет переменных $lang, $address, $subject и $price, включая их соответствующие типы.

Альтернативой является определение типов каждой переменной непосредственно в шаблоне, т.е. без создания класса. Для этого используется тег {varType}:

{varType string $lang}
{varType Address $address}

Конечно, оба варианта можно комбинировать. Создайте класс, так как это обеспечит завершение на стороне ведущего, свяжите его с шаблоном с помощью {templateType} и используйте {varType} для других локальных переменных в блоках и т.д. Это можно понять как аналогию /** @var type $variable */, который является комментарием, который мы иногда используем в PHP-коде для указания IDE или инструменту статического анализа.

Также тип может быть указан в {var}, {default} или {define}:

{var Model\Page $page = $items['page']}

{define form, string $name}
	...
{/define}

Примечание: по историческим причинам в тегах {var} и {default} можно было писать переменные без ведущего знака доллара. Поскольку это создает двусмысленность, тип это или переменная, этот синтаксис устарел, и Latte будет предупреждать вас, когда вы будете его использовать.

Как вы упрощаете свою работу?

Как максимально упростить написание шаблонного класса или {varType}? Сгенерировать их. Именно это и делает пара тегов {templatePrint} и {varPrint}.

Если вы поместите один из этих тегов в шаблон, то вместо обычного рендеринга будет отображаться код класса или шаблона. Затем просто выделите и скопируйте код в свой проект.

Nette/application 3.1 (beta) включает перегруженный тег {templatePrint}, который генерирует код, более подходящий для презентаторов.

Тег {varPrint} перечисляет локальные переменные, которые не являются параметрами шаблона. Если вы хотите перечислить все переменные, используйте {varPrint all}.

Завершение кода IDE

Последняя версия плагина PhpStorm Latte может использовать вышеуказанные теги и затем предлагать на основе типов. Плагин также знает типы стандартных переменных, таких как $user, $presenter, $basePath и т.д.

Статический анализ

Конечная цель состоит в том, чтобы все объявленные типы также можно было использовать для статического анализа. Например, использовать PHPStan для проверки шаблонов так же легко, как и других файлов PHP.

Мы работаем над этим, и вы увидите это в одной из следующих версий Latte.