Latte: como usar o sistema de tipos?

Graças ao conhecimento do tipo de dados ou objeto que está em cada variável, é possível:

• O IDE sugerir corretamente
• A análise estática detetar erros

Dois pontos que aumentam fundamentalmente a qualidade e o conforto do desenvolvimento.

Como declarar tipos no lado do PHP?

Vamos passar os dados para o template como um objeto de uma classe que define todas as variáveis e seus tipos. Usando os novos recursos do PHP 7.4, poderia parecer assim:

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

Uso:

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

Adição: graças aos novos recursos do PHP 8, o exemplo pode ser escrito de forma ainda mais interessante assim:

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

Como declarar tipos no template?

Podemos agora associar a classe mencionada ao template. Basta indicar no início:

{templateType MailTemplate}

E com isso definimos que no template haverá um quarteto de variáveis $lang, $address, $subject e $price, incluindo os tipos correspondentes.

Uma alternativa é definir os tipos de variáveis individuais diretamente no template, ou seja, sem criar uma classe. Para isso, serve a tag {varType}:

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

Claro, ambos podem ser combinados. Crie uma classe, pois isso garante o autocompletar no lado do presenter, conecte-a ao template usando {templateType} e use {varType} para outras variáveis locais em blocos, etc. Podemos entender {varType} como análogo a /** @var type $variable */, que é um comentário que às vezes usamos no código PHP para instruir o IDE ou o analisador estático.

Agora também é possível indicar o tipo nas tags {var}, {default} ou {define}:

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

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

Nota: por razões históricas, era possível escrever variáveis nas tags {var} e {default} sem o dólar inicial (e com uma seta em vez do sinal de igual). Como isso cria ambiguidade sobre se é um tipo ou uma variável, essa sintaxe foi proibida e o Latte avisará se você a usar. Uma maneira simples de pesquisar seus templates para ver se você tem essa sintaxe antiga é procurar pelas expressões regulares /\{(var|default) [^$]/ e /\{(var|default) [^}]*=>/.

Como economizar trabalho?

Qual a maneira mais fácil de escrever uma classe de template ou tags {varType}? Deixe que sejam geradas para você. É exatamente para isso que existem as tags {templatePrint} e {varPrint}.

Se você colocar uma dessas tags em um template, em vez da renderização normal, será exibida uma proposta de código da classe ou, alternativamente, uma lista de tags {varPrint}. Em seguida, basta selecionar o código com um clique e copiá-lo para o projeto.

O nette/application 3.1 (em versão beta) inclui uma tag {templatePrint} sobrecarregada que gera código mais adequado para presenters.

A tag {varPrint} lista as variáveis locais que não são parâmetros do template. Se você quiser listar todas as variáveis, use {varPrint all}.

Autocompletar no IDE

A versão mais recente do plugin Latte para PhpStorm pode usar as tags mencionadas acima e, em seguida, fornecer sugestões com base nos tipos. O plugin também conhece os tipos de variáveis padrão, como $user, $presenter, $basePath, etc.

Análise estática

O objetivo é que todos os tipos declarados também possam ser usados para análise estática. Por exemplo, para que, usando o PHPStan, seja possível verificar templates tão facilmente quanto outros arquivos PHP.

Estamos trabalhando nisso e você verá em uma das próximas versões do Latte.