Încărcătoare de șabloane

Încărcătoarele sunt mecanismul pe care Latte îl utilizează pentru a prelua codul sursă al șabloanelor dumneavoastră. Cel mai adesea, șabloanele sunt fișiere stocate pe disc, dar sistemul de încărcare flexibil al Latte vă permite să le încărcați practic de oriunde sau chiar să le generați dinamic.

Ce este un încărcător?

De obicei, atunci când lucrați cu șabloane, vă gândiți la fișiere .latte care se află în structura de directoare a proiectului dvs. Acest lucru este gestionat de FileLoader-ul implicit al Latte. Cu toate acestea, legătura dintre un nume de șablon (cum ar fi 'main.latte' sau 'components/card.latte') și conținutul său real de cod sursă nu trebuie să fie neapărat o corespondență directă a căii de acces la fișiere.

Aici intervin încărcătoarele. Un încărcător este un obiect responsabil pentru preluarea unui nume de șablon (un șir de identificatori) și furnizarea către Latte a codului său sursă. Latte se bazează în întregime pe încărcătorul configurat pentru această sarcină. Acest lucru este valabil nu numai pentru șablonul inițial solicitat prin $latte->render('main.latte'), ci și pentru toate șabloanele la care se face trimitere în cadrul acestuia folosind etichete precum {include ...}, {layout ...}, {embed ...}, sau {import ...}.

De ce să utilizați un încărcător personalizat?

  • Încărcarea din surse alternative: Preluarea șabloanelor stocate într-o bază de date, într-un cache (cum ar fi Redis sau Memcached), într-un sistem de control al versiunilor (cum ar fi Git, pe baza unui anumit commit) sau generate dinamic.
  • Implementarea convențiilor de denumire personalizate: Este posibil să doriți să utilizați aliasuri mai scurte pentru șabloane sau să implementați o logică specifică a căii de căutare (de exemplu, căutarea mai întâi într-un director de teme, apoi revenirea la un director implicit).
  • Adăugarea securității sau a controlului accesului: Un încărcător personalizat ar putea verifica permisiunile utilizatorului înainte de a încărca anumite șabloane.
  • Preprocesare: Deși, în general, este descurajat(trecerile compilatorului sunt mai bune), un încărcător ar putea teoretic să preproceseze conținutul șablonului înainte de a-l preda lui Latte.

Configurați încărcătorul pentru instanța Latte\Engine utilizând metoda setLoader():

$latte = new Latte\Engine;

// Utilizați FileLoader-ul implicit pentru fișierele din '/path/to/templates'
$loader = new Latte\Loaders\FileLoader('/path/to/templates');
$latte->setLoader($loader);

Un încărcător trebuie să implementeze interfața Latte\Loader.

Încărcătoare încorporate

Latte oferă mai multe încărcătoare standard:

FileLoader

Acesta este cărcatorul implicit utilizat de Latte\Engine dacă nu este specificat niciun alt încărcător. Acesta încarcă șabloanele direct din sistemul de fișiere.

Opțional, puteți seta un director rădăcină pentru a restricționa accesul:

use Latte\Loaders\FileLoader;

// Următorul text va permite numai încărcarea șabloanelor din /var/www/html/templates
$loader = new FileLoader('/var/www/html/templates');
$latte->setLoader($loader);

// $latte->render('../../../etc/passwd'); // Aceasta ar arunca o excepție

// Render șablon situat la /var/www/html/templates/pages/contact.latte
$latte->render('pages/contact.latte');

Acesta rezolvă numele șabloanelor în raport cu șablonul curent atunci când se utilizează etichete precum {include} sau {layout}, cu excepția cazului în care este furnizată o cale absolută.

StringLoader

Acest încărcător recuperează conținutul șablonului dintr-un array asociativ în care cheile sunt numele șablonului (identificatori), iar valorile sunt șirurile de cod sursă ale șablonului. Este deosebit de util pentru testare sau aplicații mici în care șabloanele pot fi stocate chiar în codul PHP.

use Latte\Loaders\StringLoader;

$loader = new StringLoader([
	'main.latte' => 'Hello {$name}, include is below:{include helper.latte}',
	'helper.latte' => '{var $x = 10}Included content: {$x}',
	// Adăugați mai multe șabloane după cum este necesar
]);

$latte->setLoader($loader);

$latte->render('main.latte', ['name' => 'World']);
// Ieșiri: Hello World, include este mai jos: Conținut inclus: 10

Dacă aveți nevoie doar de redarea unui singur șablon direct dintr-un șir de caractere, fără a avea nevoie de incluziuni sau moșteniri care să facă trimitere la alte șabloane denumite șir de caractere, puteți transmite șirul direct la render() sau renderToString() atunci când utilizați StringLoader fără un array:

$loader = new StringLoader;
$latte->setLoader($loader);

$templateString = 'Hello {$name}!';
$output = $latte->renderToString($templateString, ['name' => 'Alice']);
// $output conține "Bună ziua Alice!

Crearea unui încărcător personalizat

Pentru a crea un încărcător propriu (de exemplu, pentru a încărca șabloane dintr-o bază de date, cache, control de versiune sau altă sursă), trebuie să creați o clasă care implementează interfața Latte\Loader.

Să vedem ce trebuie să facă fiecare metodă.

getContent (string $name): string

Aceasta este metoda principală a încărcătorului. Responsabilitatea sa este să recupereze și să returneze conținutul codului sursă complet pentru șablonul identificat prin $name (astfel cum a fost transmis la $latte->render() sau returnat prin getReferredName()).

Dacă șablonul nu poate fi găsit sau accesat, această metodă trebuie să arunce un Latte\RuntimeException.

public function getContent(string $name): string
{
	// Exemplu: Preluare de pe o memorie internă ipotetică
	$content = $this->storage->read($name);
	if ($content === null) {
		throw new Latte\RuntimeException("Template '$name' cannot be loaded.");
	}
	return $content;
}

getReferredName (string $name, string $referringName): string

Această metodă gestionează rezolvarea numelor de șabloane utilizate în cadrul unor etichete precum {include}, {layout}, etc. Atunci când Latte întâlnește, de exemplu, {include 'partial.latte'} în interiorul main.latte, apelează această metodă cu $name = 'partial.latte' și $referringName = 'main.latte'.

Sarcina metodei este de a rezolva $name într-un identificator canonic (de exemplu, o cale absolută, o cheie unică de bază de date), care va fi utilizat la apelarea altor metode de încărcare, pe baza contextului furnizat de $referringName.

public function getReferredName(string $name, string $referringName): string
{
	return ...;
}

getUniqueId (string $name): string

Latte utilizează cache-ul șablonului compilat pentru performanță. Fiecare fișier de șablon compilat are nevoie de un nume unic derivat din identificatorul șablonului sursă. Această metodă furnizează un șir de caractere care identifică în mod unic șablonul $name.

Pentru șabloanele bazate pe fișiere, calea absolută ar putea funcționa. Pentru șabloanele din bazele de date, este obișnuită o combinație între un prefix și ID-ul bazei de date.

public function getUniqueId(string $name): string
{
	return ...;
}

Exemplu: Încărcător simplu de baze de date

Acest exemplu demonstrează structura de bază a unui încărcător care recuperează șabloane stocate într-un tabel din baza de date numit templates cu coloanele name (identificator unic), content și updated_at.

use Latte;

class DatabaseLoader implements Latte\Loader
{
	public function __construct(
		private \PDO $db,
	) {
	}

	public function getContent(string $name): string
	{
		$stmt = $this->db->prepare('SELECT content FROM templates WHERE name = ?');
		$stmt->execute([$name]);
		$content = $stmt->fetchColumn();
		if ($content === false) {
			throw new Latte\RuntimeException("Template '$name' not found in database.");
		}
		return $content;
	}

	// Acest exemplu simplu presupune că numele șabloanelor ("homepage", "article" etc.)
	// sunt ID-uri unice, iar șabloanele nu se referă unele la altele relativ.
	public function getReferredName(string $name, string $referringName): string
	{
		return $name;
	}

	public function getUniqueId(string $name): string
	{
		// Utilizarea unui prefix și a numelui în sine este unică și suficientă aici
		return 'db_' . $name;
	}
}

// Utilizare:
$pdo = new \PDO(/* connection details */);
$loader = new DatabaseLoader($pdo);
$latte->setLoader($loader);
$latte->render('homepage'); // Încarcă șablonul cu numele "homepage" din DB

Încărcătoarele personalizate vă oferă control complet asupra provenienței șabloanelor Latte, permițând integrarea cu diverse sisteme de stocare și fluxuri de lucru.

versiune: 3.0