Practici pentru dezvoltatori

Instalare

Cel mai bun mod de a instala Latte este de a utiliza un Composer:

composer require latte/latte

Versiuni PHP acceptate (se aplică la cele mai recente versiuni Latte patch):

Cum se redă un șablon

Cum se redă un șablon? Folosiți doar acest cod simplu:

$latte = new Latte\Engine;
// director de cache
$latte->setTempDirectory('/path/to/tempdir');

$params = [ /* template variables */ ];
// sau $params = new TemplateParameters(/* ... */);

// redare la ieșire
$latte->render('template.latte', $params);
// sau redă în variabilă
$output = $latte->renderToString('template.latte', $params);

Parametrii pot fi array-uri sau chiar mai bine obiecte, care vor asigura verificarea tipului și sugestii în editor.

Puteți găsi, de asemenea, exemple de utilizare în depozitul Latte examples.

Performanță și memorare în cache

Șabloanele Latte sunt extrem de rapide, deoarece Latte le compilează direct în cod PHP și le stochează pe disc. Astfel, ele nu au niciun fel de costuri suplimentare în comparație cu șabloanele scrise în PHP pur.

Memoria cache este regenerată automat de fiecare dată când modificați fișierul sursă. Astfel, puteți edita comod șabloanele Latte în timpul dezvoltării și puteți vedea imediat modificările în browser. Puteți dezactiva această caracteristică într-un mediu de producție și economisi puțină performanță:

$latte->setAutoRefresh(false);

Atunci când este implementat pe un server de producție, generarea inițială a cache-ului, în special pentru aplicațiile mari, poate dura, în mod normal, ceva timp. Latte are o prevenire încorporată împotriva cache stampede. Aceasta este o situație în care serverul primește un număr mare de solicitări simultane și, deoarece memoria cache a Latte nu există încă, toate acestea o vor genera în același timp. Ceea ce face ca CPU să crească brusc. Latte este inteligent și, atunci când există mai multe cereri concurente, doar primul fir generează memoria cache, celelalte așteaptă și apoi o utilizează.

Parametrii ca o clasă

Mai bine decât să transmiteți variabilele șablonului sub formă de array-uri este să creați o clasă. Obțineți o notație sigură din punct de vedere al tipului, o sugestie plăcută în IDE și o modalitate de a înregistra filtre și funcții.

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

Dezactivarea scăpării automate a variabilelor

Dacă variabila conține un șir de caractere HTML, o puteți marca astfel încât Latte să nu o evadeze automat (și, prin urmare, dublu). Astfel, se evită necesitatea de a specifica |noescape în șablon.

Cea mai simplă metodă este să înfășurați șirul într-un obiect Latte\Runtime\Html:

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

De asemenea, Latte nu evadează toate obiectele care implementează interfața Latte\HtmlStringable. Astfel, vă puteți crea propria clasă a cărei metodă __toString() va returna codul HTML care nu va fi scăpat automat:

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

Metoda __toString trebuie să returneze HTML corect și să asigure scăparea parametrilor, altfel poate apărea o vulnerabilitate XSS!

Cum să extindeți Latte cu filtre, etichete etc.

Cum să adăugați un filtru, o funcție, o etichetă etc. personalizat la Latte? Aflați în capitolul Extinderea Latte. Dacă doriți să refolosiți modificările în diferite proiecte sau dacă doriți să le partajați cu alții, ar trebui să creați apoi o extensie.

Orice cod în șablon {php ...}

Doar expresiile PHP pot fi scrise în interiorul {do} așa că nu puteți, de exemplu, să introduceți construcții precum if ... else sau instrucțiuni terminate cu punct și virgulă.

Cu toate acestea, puteți înregistra extensia RawPhpExtension, care adaugă eticheta {php ...}. Puteți folosi această extensie pentru a insera orice cod PHP. Aceasta nu face obiectul niciunei reguli de mod sandbox, astfel încât utilizarea este responsabilitatea autorului șablonului.

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

Verificarea codului generat

Latte compilează șabloanele în cod PHP. Bineînțeles, se asigură că codul generat este valid din punct de vedere sintactic. Cu toate acestea, atunci când se utilizează extensii de la terțe părți sau RawPhpExtension, Latte nu poate garanta corectitudinea fișierului generat. De asemenea, în PHP, puteți scrie cod care este corect din punct de vedere sintactic, dar care este interzis (de exemplu, atribuirea unei valori variabilei $this) și care provoacă o eroare de compilare PHP. Dacă scrieți o astfel de operațiune într-un șablon, aceasta va fi inclusă și în codul PHP generat. Deoarece există peste două sute de operații diferite interzise în PHP, Latte nu urmărește să le detecteze. PHP însuși le va semnala la redare, ceea ce, de obicei, nu reprezintă o problemă.

Cu toate acestea, există situații în care doriți să știți în timpul compilării șablonului că acesta nu conține erori de compilare PHP. Mai ales atunci când șabloanele pot fi editate de utilizatori sau când folosiți Sandbox. Într-un astfel de caz, dispuneți ca șabloanele să fie verificate în timpul compilării. Puteți activa această funcționalitate folosind metoda Engine::enablePhpLint(). Deoarece trebuie să apeleze binarul PHP pentru verificare, treceți calea acestuia ca parametru:

$latte = new Latte\Engine;
$latte->enablePhpLinter('/path/to/php');

try {
	$latte->compile('home.latte');
} catch (Latte\CompileException $e) {
	// prinde erori Latte și, de asemenea, erori de compilare în PHP
	echo 'Error: ' . $e->getMessage();
}

Local

Latte vă permite să setați localele, care afectează formatarea numerelor, a datelor și sortarea. Aceasta este setată utilizând metoda setLocale(). Identificatorul locale urmează standardul IETF language tag, care utilizează extensia PHP intl. Acesta constă dintr-un cod de limbă și, eventual, un cod de țară, de exemplu, en_US pentru limba engleză în Statele Unite, de_DE pentru limba germană în Germania etc.

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

Setarea locale afectează filtrele localDate, sort, number și bytes.

Necesită extensia PHP intl. Setarea din Latte nu afectează setarea locală globală din PHP.

Modul strict

În modul de analiză strictă, Latte verifică dacă lipsesc etichete HTML de închidere și, de asemenea, dezactivează utilizarea variabilei $this. Pentru a o activa:

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

Pentru a genera șabloane cu antetul declare(strict_types=1), procedați după cum urmează:

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

Traducerea în șabloane

Utilizați extensia TranslatorExtension pentru a adăuga {_...}, {translate} și să filtreze translate la șablon. Acestea sunt utilizate pentru a traduce valori sau părți ale șablonului în alte limbi. Parametrul este metoda (PHP callable) care efectuează traducerea:

class MyTranslator
{
	public function __construct(private string $lang)
	{}

	public function translate(string $original): string
	{
		// creați $translated din $original în conformitate cu $this->lang
		return $translated;
	}
}

$translator = new MyTranslator($lang);
$extension = new Latte\Essential\TranslatorExtension(
	$translator->translate(...), // [$translator, 'translate'] în PHP 8.0
);
$latte->addExtension($extension);

Traducătorul este apelat în timpul execuției atunci când șablonul este redat. Cu toate acestea, Latte poate traduce toate textele statice în timpul compilării șablonului. Acest lucru economisește performanță, deoarece fiecare șir de caractere este tradus o singură dată, iar traducerea rezultată este scrisă în fișierul compilat. Astfel, se creează mai multe versiuni compilate ale șablonului în directorul cache, una pentru fiecare limbă. Pentru a face acest lucru, trebuie doar să specificați limba ca al doilea parametru:

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

Prin text static înțelegem, de exemplu, {_'hello'} sau {translate}hello{/translate}. Textul nestatic, cum ar fi {_$foo}, va continua să fie tradus în timpul execuției.

Șablonul poate, de asemenea, să transmită parametrii suplimentari traducătorului prin intermediul {_$original, foo: bar} sau {translate foo: bar}, pe care acesta îi primește sub forma matricei $params:

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

Depanarea și Tracy

Latte încearcă să facă dezvoltarea cât mai plăcută posibil. În scopuri de depanare, există trei etichete {dump}, {debugbreak} și {trace}.

Veți obține cel mai mult confort dacă instalați instrumentul de depanare excelent Tracy și activați pluginul Latte:

// permite Tracy
Tracy\Debugger::enable();

$latte = new Latte\Engine;
// activează extensia lui Tracy
$latte->addExtension(new Latte\Bridges\Tracy\TracyExtension);

Veți vedea acum toate erorile într-un ecran roșu îngrijit, inclusiv erorile din șabloane cu evidențierea rândurilor și coloanelor (video). În același timp, în colțul din dreapta jos, în așa-numita Tracy Bar, apare o filă pentru Latte, unde puteți vedea clar toate șabloanele redate și relațiile dintre ele (inclusiv posibilitatea de a face clic în șablon sau în codul compilat), precum și variabilele:

Deoarece Latte compilează șabloanele în cod PHP lizibil, puteți să le parcurgeți în mod convenabil în IDE-ul dumneavoastră.

Linter: Validarea sintaxei șablonului

Instrumentul Linter vă va ajuta să treceți prin toate șabloanele și să verificați dacă există erori de sintaxă. Acesta se lansează din consolă:

vendor/bin/latte-lint <path>

Utilizați parametrul --strict pentru a activa modul strict.

Dacă utilizați etichete personalizate, creați și Linterul personalizat, de exemplu custom-latte-lint:

#!/usr/bin/env php
<?php

// introduceți calea reală către fișierul autoload.php
require __DIR__ . '/vendor/autoload.php';

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

$linter = new Latte\Tools\Linter;
$latte = $linter->getEngine();
// adăugați extensiile individuale aici
$latte->addExtension(/* ... */);

$ok = $linter->scanDirectory($path);
exit($ok ? 0 : 1);

Alternativ, puteți transmite propriul obiect Latte\Engine către Linter:

$latte = new Latte\Engine;
// aici configurăm obiectul $latte
$linter = new Latte\Tools\Linter(engine: $latte);

Încărcarea șabloanelor dintr-un șir de caractere

Aveți nevoie să încărcați șabloane din șiruri de caractere în loc de fișiere, poate în scopuri de testare? StringLoader vă va ajuta:

$latte->setLoader(new Latte\Loaders\StringLoader([
	'main.file' => '{include other.file}',
	'other.file' => '{if true} {$var} {/if}',
]));

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

Manipulator de excepții

Puteți defini propriul gestionar pentru excepțiile așteptate. Excepțiile ridicate în interiorul {try} și în sandbox sunt transmise către acesta.

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

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

Căutarea automată a aspectului

Utilizarea tag-ului {layout}, șablonul își determină șablonul părinte. De asemenea, este posibil ca aspectul să fie căutat automat, ceea ce va simplifica scrierea șabloanelor, deoarece acestea nu vor trebui să includă eticheta {layout}.

Acest lucru se realizează după cum urmează:

$finder = function (Latte\Runtime\Template $template) {
	if (!$template->getReferenceType()) {
		// returnează calea către fișierul șablon părinte
		return 'automatic.layout.latte';
	}
};

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

În cazul în care șablonul nu trebuie să aibă un aspect, acesta va indica acest lucru cu ajutorul etichetei {layout none}.