Loadere

Loaderele sunt mecanismul pe care Latte îl folosește pentru a obține codul sursă al șabloanelor dvs. Cel mai adesea, șabloanele sunt stocate ca fișiere pe disc, dar datorită sistemului flexibil de loadere, le puteți încărca practic de oriunde sau chiar le puteți genera dinamic.

Ce este un Loader?

Când lucrați cu șabloane, de obicei vă imaginați fișiere .latte situate în structura de directoare a proiectului dvs. De acest lucru se ocupă FileLoader implicit în Latte. Cu toate acestea, legătura dintre numele șablonului (cum ar fi 'main.latte' sau 'components/card.latte') și codul său sursă real nu trebuie să fie o mapare directă la calea fișierului.

Aici intervin loaderele. Un loader este un obiect care are sarcina de a lua numele șablonului (un șir de identificare) și de a furniza Latte codul său sursă. Latte se bazează complet pe loaderul configurat pentru această sarcină. Acest lucru este valabil nu numai pentru șablonul inițial solicitat folosind $latte->render('main.latte'), ci și pentru fiecare șablon referit în interior folosind tag-uri precum {include ...}, {layout ...}, {embed ...} sau {import ...}.

De ce să folosiți un loader personalizat?

  • Încărcarea din surse alternative: Obținerea șabloanelor stocate într-o bază de date, în cache (cum ar fi Redis sau Memcached), într-un sistem de control al versiunilor (cum ar fi Git, pe baza unui commit specific) 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ăilor de căutare (de exemplu, căutați mai întâi în directorul temei, apoi reveniți la directorul implicit).
  • Adăugarea securității sau a controlului accesului: Un loader personalizat poate verifica permisiunile utilizatorului înainte de a încărca anumite șabloane.
  • Preprocesare: Deși în general nu se recomandă (trecerile de compilare sunt mai bune), un loader ar putea teoretic să preproceseze conținutul șablonului înainte de a-l transmite către Latte.

Setați loaderul pentru instanța Latte\Engine folosind metoda setLoader():

$latte = new Latte\Engine;

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

Loaderul trebuie să implementeze interfața Latte\Loader.

Loadere încorporate

Latte oferă mai multe loadere standard:

FileLoader

Acesta este loaderul implicit utilizat de clasa Latte\Engine, dacă nu este specificat niciun altul. Î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 va permite încărcarea șabloanelor numai din directorul /var/www/html/templates
$loader = new FileLoader('/var/www/html/templates');
$latte->setLoader($loader);

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

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

La utilizarea tag-urilor precum {include} sau {layout}, rezolvă numele șabloanelor relativ la șablonul curent, dacă nu este specificată o cale absolută.

StringLoader

Acest loader obține conținutul șablonului dintr-un array asociativ, unde cheile sunt numele șabloanelor (identificatori) și valorile sunt șiruri de cod sursă al șablonului. Este deosebit de util pentru testare sau aplicații mici, unde șabloanele pot fi stocate direct în codul PHP.

use Latte\Loaders\StringLoader;

$loader = new StringLoader([
	'main.latte' => 'Salut {$name}, include este mai jos:{include helper.latte}',
	'helper.latte' => '{var $x = 10}Conținut inclus: {$x}',
	// Adăugați alte șabloane după cum este necesar
]);

$latte->setLoader($loader);

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

Dacă trebuie să randați doar un singur șablon direct dintr-un șir, fără a fi nevoie de includere sau moștenire care să facă referire la alte șabloane șir numite, puteți transmite șirul direct metodei render() sau renderToString() atunci când utilizați StringLoader fără un array:

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

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

Crearea unui Loader personalizat

Pentru a crea un loader personalizat (de exemplu, pentru a încărca șabloane dintr-o bază de date, cache, sistem de control al versiunilor 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 de bază a loaderului. Sarcina sa este să obțină și să returneze codul sursă complet al șablonului identificat prin $name (așa cum este transmis metodei $latte->render() sau returnat de metoda getReferredName()).

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

public function getContent(string $name): string
{
	// Exemplu: Încărcare dintr-un depozit intern ipotetic
	$content = $this->storage->read($name);
	if ($content === null) {
		throw new Latte\RuntimeException("Șablonul '$name' nu poate fi încărcat.");
	}
	return $content;
}

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

Această metodă se ocupă de traducerea numelor de șabloane utilizate în interiorul tag-urilor precum {include}, {layout}, etc. 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 să traducă $name într-un identificator canonic (de exemplu, cale absolută, cheie unică de bază de date), care va fi utilizat la apelarea altor metode ale loaderului, pe baza contextului furnizat în $referringName.

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

getUniqueId (string $name): string

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

Pentru șabloanele bazate pe fișiere, calea absolută poate servi. Pentru șabloanele din baza de date, o combinație de prefix și ID de bază de date este comună.

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

Exemplu: Loader simplu de bază de date

Acest exemplu arată structura de bază a unui loader care încarcă șabloane stocate într-un tabel de bază 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("Șablonul '$name' nu a fost găsit în baza de date.");
		}
		return $content;
	}

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

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

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

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

versiune: 3.0