Programy ładujące szablony

Loadery to mechanizm wykorzystywany przez Latte do pobierania kodu źródłowego szablonów. Najczęściej szablony są plikami przechowywanymi na dysku, ale elastyczny system ładowania Latte pozwala na ładowanie ich z praktycznie dowolnego miejsca, a nawet generowanie ich dynamicznie.

Co to jest Loader?

Zazwyczaj podczas pracy z szablonami myśli się o plikach .latte znajdujących się w strukturze katalogów projektu. Jest to obsługiwane przez domyślny FileLoader Latte. Jednak połączenie między nazwą szablonu (np. 'main.latte' lub 'components/card.latte') a jego rzeczywistą zawartością kodu źródłowego nie musi być bezpośrednim mapowaniem ścieżki pliku.

W tym miejscu pojawiają się loadery. Program ładujący jest obiektem odpowiedzialnym za pobranie nazwy szablonu (ciąg identyfikatora) i dostarczenie Latte jego kodu źródłowego. Latte całkowicie polega na skonfigurowanym programie ładującym. Dotyczy to nie tylko początkowego szablonu żądanego za pośrednictwem $latte->render('main.latte'), ale także każdego szablonu, do którego odwołuje się za pomocą tagów takich jak {include ...}, {layout ...}, {embed ...} lub {import ...}.

Dlaczego warto używać niestandardowego programu ładującego?

  • Wczytywanie z alternatywnych źródeł: Pobieranie szablonów przechowywanych w bazie danych, pamięci podręcznej (takiej jak Redis lub Memcached), systemie kontroli wersji (takim jak Git, na podstawie określonego zatwierdzenia) lub generowanych dynamicznie.
  • Wdrażanie niestandardowych konwencji nazewnictwa:** Możesz chcieć użyć krótszych aliasów dla szablonów lub zaimplementować określoną logikę ścieżki wyszukiwania (np. najpierw szukając w katalogu motywu, a następnie powracając do katalogu domyślnego).
  • Dodanie zabezpieczeń lub kontroli dostępu:** Niestandardowy program ładujący może weryfikować uprawnienia użytkownika przed załadowaniem niektórych szablonów.
  • Preprocessing: Choć generalnie jest to odradzane(kompilatory są lepsze), program ładujący mógłby teoretycznie wstępnie przetworzyć zawartość szablonu przed przekazaniem go do Latte.

Program ładujący dla instancji Latte\Engine konfiguruje się za pomocą metody setLoader():

$latte = new Latte\Engine;

// Użyj domyślnego FileLoadera dla plików w '/path/to/templates'
$loader = new Latte\Loaders\FileLoader('/path/to/templates');
$latte->setLoader($loader);

Program ładujący musi implementować interfejs Latte\Loader.

Wbudowane programy ładujące

Latte oferuje kilka standardowych ładowarek:

FileLoader

Jest to domyślny program ładujący używany przez Latte\Engine, jeśli nie określono innego programu ładującego. Ładuje szablony bezpośrednio z systemu plików.

Opcjonalnie można ustawić katalog główny, aby ograniczyć dostęp:

use Latte\Loaders\FileLoader;

// Poniższe rozwiązanie pozwoli na ładowanie szablonów tylko w obrębie /var/www/html/templates
$loader = new FileLoader('/var/www/html/templates');
$latte->setLoader($loader);

// $latte->render('../../../etc/passwd'); // Spowoduje to zgłoszenie wyjątku.

// Renderowanie szablonu znajdującego się w /var/www/html/templates/pages/contact.latte
$latte->render('pages/contact.latte');

Rozwiązuje nazwy szablonów względem bieżącego szablonu, gdy używane są znaczniki takie jak {include} lub {layout}, chyba że podano ścieżkę bezwzględną.

StringLoader

Ten program ładujący pobiera zawartość szablonu z tablicy asocjacyjnej, w której kluczami są nazwy szablonów (identyfikatory), a wartościami są ciągi kodu źródłowego szablonu. Jest to szczególnie przydatne do testowania lub małych aplikacji, w których szablony mogą być przechowywane w samym kodzie 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}',
	// Dodaj więcej szablonów w razie potrzeby
]);

$latte->setLoader($loader);

$latte->render('main.latte', ['name' => 'World']);
// Dane wyjściowe: Hello World, include znajduje się poniżej:Included content: 10

Jeśli potrzebujesz tylko wyrenderować pojedynczy szablon bezpośrednio z ciągu znaków, bez potrzeby dołączania lub dziedziczenia odwołań do innych nazwanych szablonów ciągów znaków, możesz przekazać ciąg znaków bezpośrednio do render() lub renderToString(), gdy używasz StringLoader bez tablicy:

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

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

Tworzenie niestandardowego programu ładującego

Aby utworzyć własny program ładujący (np. w celu załadowania szablonów z bazy danych, pamięci podręcznej, kontroli wersji lub innego źródła), należy utworzyć klasę implementującą interfejs Latte\Loader.

Przyjrzyjmy się, co każda metoda musi zrobić.

getContent (string $name): string

Jest to podstawowa metoda programu ładującego. Jej zadaniem jest pobranie i zwrócenie pełnej zawartości kodu źródłowego szablonu zidentyfikowanego przez $name (przekazanego do $latte->render() lub zwróconego przez getReferredName()).

Jeśli nie można znaleźć szablonu lub uzyskać do niego dostępu, ta metoda musi rzucić Latte\RuntimeException.

public function getContent(string $name): string
{
	// Przykład: Pobieranie z hipotetycznej pamięci wewnętrznej
	$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

Ta metoda obsługuje rozwiązywanie nazw szablonów używanych w tagach, takich jak {include}, {layout}, itp. Kiedy Latte napotka, na przykład, {include 'partial.latte'} wewnątrz main.latte, wywołuje tę metodę z $name = 'partial.latte' i $referringName = 'main.latte'.

Zadaniem tej metody jest przekształcenie $name w kanoniczny identyfikator (np. bezwzględną ścieżkę, unikalny klucz bazy danych), który będzie używany podczas wywoływania innych metod ładujących, w oparciu o kontekst dostarczony przez $referringName.

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

getUniqueId (string $name): string

Latte używa skompilowanej pamięci podręcznej szablonów w celu zwiększenia wydajności. Każdy skompilowany plik szablonu wymaga unikalnej nazwy pochodzącej z identyfikatora szablonu źródłowego. Ta metoda zapewnia ciąg znaków, który jednoznacznie identyfikuje szablon $name.

W przypadku szablonów opartych na plikach może działać ścieżka bezwzględna. W przypadku szablonów baz danych powszechne jest połączenie prefiksu i identyfikatora bazy danych.

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

Przykład: Prosty program ładujący bazę danych

Ten przykład demonstruje podstawową strukturę programu ładującego pobierającego szablony przechowywane w tabeli bazy danych o nazwie templates z kolumnami name (unikalny identyfikator), 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;
	}

	// Ten prosty przykład zakłada, że nazwy szablonów ("strona główna", "artykuł" itp.)
	// są unikalnymi identyfikatorami, a szablony nie odnoszą się do siebie nawzajem.
	public function getReferredName(string $name, string $referringName): string
	{
		return $name;
	}

	public function getUniqueId(string $name): string
	{
		// Użycie prefiksu i samej nazwy jest tutaj unikalne i wystarczające
		return 'db_' . $name;
	}
}

// Użycie:
$pdo = new \PDO(/* connection details */);
$loader = new DatabaseLoader($pdo);
$latte->setLoader($loader);
$latte->render('homepage'); // Ładuje szablon o nazwie 'homepage' z bazy danych

Niestandardowe programy ładujące zapewniają pełną kontrolę nad tym, skąd pochodzą szablony Latte, umożliwiając integrację z różnymi systemami pamięci masowej i przepływami pracy.

wersja: 3.0