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 (бета версия) включва претоварен таг {templatePrint}, който генерира код, който е по-подходящ за презентатори.

Тагът {varPrint} изброява локални променливи, които не са параметри на шаблона. Ако искате да изброите всички променливи, използвайте {varPrint all}.

Допълване на кода в IDE

Последната версия на приставката PhpStorm Latte може да се възползва от горните тагове и след това да предлага на базата на типовете. Плъгинът също така познава типовете на стандартните променливи, като например $user, $presenter, $basePath и т.н.

Статичен анализ

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

Работим по това и ще го видите в някоя от следващите версии на Latte.