Sablon betöltők

A betöltők a Latte által a sablonok forráskódjának lekérdezésére használt mechanizmusok. Leggyakrabban a sablonok a lemezen tárolt fájlok, de a Latte rugalmas betöltő rendszere lehetővé teszi, hogy gyakorlatilag bárhonnan betöltse őket, vagy akár dinamikusan generálja őket.

Mi az a betöltő?

Amikor sablonokkal dolgozol, általában a .latte fájlokra gondolsz, amelyek a projekted könyvtárszerkezetében találhatóak. Ezt a Latte alapértelmezett FileLoaderje kezeli. Azonban a kapcsolat egy sablon neve (mint például 'main.latte' vagy 'components/card.latte') és a tényleges forráskód tartalma között nem kell, hogy közvetlen fájlútvonal-leképezés legyen.

Itt jönnek a képbe a betöltők. A betöltő egy olyan objektum, amely a sablon nevének (egy azonosító karakterláncnak) a fogadásáért felelős, és a Latte-nak a forráskódját adja meg. A Latte teljes mértékben a konfigurált betöltőre támaszkodik ebben a feladatban. Ez nem csak a $latte->render('main.latte') címen keresztül kért kezdeti sablonra vonatkozik, hanem minden olyan sablonra, amelyre a {include ...}, {layout ...}, {embed ...} vagy {import ...} típusú címkékkel hivatkoznak.

Miért használjon egyéni betöltőt?

  • Feltöltés alternatív forrásokból: Adatbázisban, gyorsítótárban (például Redis vagy Memcached), verziókezelő rendszerben (például Git, egy adott commit alapján) tárolt vagy dinamikusan generált sablonok lehívása.
  • Egyéni elnevezési konvenciók megvalósítása: Lehet, hogy rövidebb aliasokat szeretne használni a sablonokhoz, vagy egy speciális keresési útvonal-logikát szeretne megvalósítani (pl. először egy téma könyvtárban keres, majd egy alapértelmezett könyvtárba tér vissza).
  • Biztonság vagy hozzáférés-szabályozás hozzáadása: Egy egyéni betöltő ellenőrizheti a felhasználói jogosultságokat bizonyos sablonok betöltése előtt.
  • Előfeldolgozás: Bár általában nem javasolt(a fordítói átmenetek jobbak), a betöltő elméletileg *előfeldolgozhatná a sablonok tartalmát, mielőtt átadja a Latte-nak.

A betöltőt a Latte\Engine példányához a setLoader() módszerrel konfigurálhatja:

$latte = new Latte\Engine;

// Az alapértelmezett FileLoader használata a '/path/to/templates' fájlokra
$loader = new Latte\Loaders\FileLoader('/path/to/templates');
$latte->setLoader($loader);

A betöltőnek a Latte\Loader interfészt kell megvalósítania.

Beépített betöltők

A Latte számos szabványos betöltőt biztosít:

FileLoader

Ez az alapértelmezett betöltő, amelyet a Latte\Engine használ, ha nincs más betöltő megadva. A sablonokat közvetlenül a fájlrendszerből tölti be.

Opcionálisan beállíthat egy gyökérkönyvtárat a hozzáférés korlátozásához:

use Latte\Loaders\FileLoader;

// A következő csak a /var/www/html/templates fájlban lévő sablonok betöltését teszi lehetővé
$loader = new FileLoader('/var/www/html/templates');
$latte->setLoader($loader);

// $latte->render('../../../../etc/passwd'); // Ez kivételt dobna.

// A /var/www/html/templates/pages/contact.latte alatt található sablon renderelése.
$latte->render('pages/contact.latte');

Az olyan címkék használatakor, mint a {include} vagy a {layout}, a sablonneveket az aktuális sablonhoz képest oldja fel, hacsak nem adunk meg abszolút elérési utat.

StringLoader

Ez a betöltő egy asszociatív tömbből hívja le a sablonok tartalmát, ahol a kulcsok a sablonok nevei (azonosítók), az értékek pedig a sablonok forráskódjának karakterláncai. Különösen hasznos teszteléshez vagy kisebb alkalmazásokhoz, ahol a sablonok magában a PHP kódban tárolódhatnak.

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}',
	// További sablonok hozzáadása szükség szerint
]);

$latte->setLoader($loader);

$latte->render('main.latte', ['name' => 'World']);
// Kimenetek: Tartalom: Hello World, include is below:Included content: 10

Ha csak egyetlen sablont kell közvetlenül egy karakterláncból renderelnie anélkül, hogy szüksége lenne más nevű karakterlánc-sablonokra hivatkozó include-okra vagy öröklődésre, akkor a karakterláncot közvetlenül átadhatja a render() vagy a renderToString() címre, ha a StringLoader -t tömb nélkül használja:

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

$templateString = 'Hello {$name}!';
$output = $latte->renderToString($templateString, ['name' => 'Alice']);
// $output tartalmazza 'Hello Alice!'

Egyéni betöltő létrehozása

Saját betöltő létrehozásához (például sablonok adatbázisból, gyorsítótárból, verziókezelőből vagy más forrásból történő betöltéséhez) létre kell hoznia egy olyan osztályt, amely megvalósítja a Latte\Loader interfészt.

Nézzük meg, hogy az egyes metódusoknak mit kell tenniük.

getContent (string $name): string

Ez a betöltő alapvető metódusa. Feladata a $name által azonosított sablon teljes forráskód tartalmának lekérdezése és visszaadása (ahogyan azt a $latte->render() -nek átadta vagy a getReferredName() által visszaadta).

Ha a sablon nem található vagy nem érhető el, akkor ennek a metódusnak a Latte\RuntimeException-t kell dobnia.

public function getContent(string $name): string
{
	// Példa: Letöltés egy feltételezett belső tárolóból
	$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

Ez a metódus kezeli az olyan címkékben használt sablonnevek feloldását, mint a {include}, {layout}, stb. Amikor a Latte találkozik például a {include 'partial.latte'} címmel a main.latte címen belül, akkor ezt a metódust hívja meg a $name = 'partial.latte' és a $referringName = 'main.latte' címmel.

A módszer feladata a $name feloldása kanonikus azonosítóvá (pl. abszolút elérési útvonal, egyedi adatbázis-kulcs), amelyet a $referringName által megadott kontextus alapján más betöltőmódszerek hívásakor használnak.

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

getUniqueId (string $name): string

A Latte a teljesítmény érdekében a lefordított sablon gyorsítótárat használja. Minden lefordított sablonfájlnak egyedi névre van szüksége, amely a forrássablon azonosítójából származik. Ez a módszer egy olyan karakterláncot ad meg, amely egyedi módon azonosítja a sablont $name.

A fájlalapú sablonok esetében az abszolút elérési útvonal is működhet. Adatbázis-sablonok esetében egy előtag és az adatbázis-azonosító kombinációja a szokásos.

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

Példa: Egyszerű adatbázis-töltő

Ez a példa egy olyan betöltő alapvető felépítését mutatja be, amely a templates nevű, name (egyedi azonosító), content és updated_at oszlopokkal rendelkező adatbázis-táblában tárolt sablonokat hívja le.

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;
	}

	// Ez az egyszerű példa sablonneveket feltételez ('honlap', 'cikk', stb.)
	// egyedi azonosítók, és a sablonok nem hivatkoznak egymásra relatíve.
	public function getReferredName(string $name, string $referringName): string
	{
		return $name;
	}

	public function getUniqueId(string $name): string
	{
		// Az előtag és maga a név használata itt egyedi és elegendő.
		return 'db_' . $name;
	}
}

// Használat:
$pdo = new \PDO(/* connection details */);
$loader = new DatabaseLoader($pdo);
$latte->setLoader($loader);
$latte->render('homepage'); // nevű sablon betöltése a DB-ből.

Az egyéni betöltők teljes ellenőrzést biztosítanak a Latte sablonok származási helye felett, lehetővé téve a különböző tárolórendszerekkel és munkafolyamatokkal való integrációt.

verzió: 3.0