Завантажувачі шаблонів

Завантажувачі – це механізм, який Latte використовує для отримання вихідного коду ваших шаблонів. Найчастіше шаблони – це файли, що зберігаються на диску, але гнучка система завантажувачів Latte дозволяє завантажувати їх практично звідки завгодно, або навіть генерувати їх динамічно.

Що таке завантажувач?

Зазвичай, коли ви працюєте з шаблонами, ви думаєте про файли .latte, що знаходяться в структурі каталогів вашого проекту. Цим займається стандартний завантажувач файлів Latte FileLoader. Однак, зв'язок між назвою шаблону (наприклад, 'main.latte' або 'components/card.latte') і його фактичним вмістом не обов'язково має бути прямим відображенням шляху до файлу.

Саме тут і з'являються завантажувачі. Завантажувач – це об'єкт, відповідальний за отримання імені шаблону (ідентифікаційного рядка) і надання Latte його вихідного коду. У цьому завданні Latte повністю покладається на налаштований завантажувач. Це стосується не тільки початкового шаблону, запитуваного через $latte->render('main.latte'), але і кожного шаблону, на який посилаються всередині за допомогою тегів типу {include ...}, {layout ...}, {embed ...} або {import ...}.

Навіщо використовувати спеціальний завантажувач?

  • Завантаження з альтернативних джерел: Завантажуйте шаблони, що зберігаються у базі даних, кеші (наприклад, Redis або Memcached), системі контролю версій (наприклад, Git, на основі конкретного коміту) або згенеровані динамічно.
  • Впровадження користувацьких угод про імена:** Можливо, ви захочете використовувати коротші псевдоніми для шаблонів або реалізувати певну логіку шляху пошуку (наприклад, спочатку шукати в каталозі тем, а потім переходити до каталогу за замовчуванням).
  • Додавання безпеки або керування доступом: Спеціальний завантажувач може перевіряти дозволи користувача перед завантаженням певних шаблонів.
  • Предопераційна обробка: Хоча загалом це не рекомендується( краще використовуватипропуски компілятора ), завантажувач може теоретично попередньо обробити вміст шаблону перед передачею його до Latte.

Ви налаштовуєте завантажувач для вашого екземпляра Latte\Engine за допомогою методу setLoader():

$latte = new Latte\Engine;

// Використовуйте FileLoader за замовчуванням для файлів у каталозі '/путь/до/шаблонів'
$loader = new Latte\Loaders\FileLoader('/path/to/templates');
$latte->setLoader($loader);

Завантажувач повинен реалізовувати інтерфейс Latte\Loader.

Вбудовані завантажувачі

Latte надає кілька стандартних завантажувачів:

FileLoader

Це завантажувач за замовчуванням, який використовується Latte\Engine, якщо не вказано інший завантажувач. Він завантажує шаблони безпосередньо з файлової системи.

За бажанням ви можете вказати кореневий каталог для обмеження доступу:

use Latte\Loaders\FileLoader;

// Наступний код дозволить завантажувати шаблони лише з каталогу /var/www/html/templates
$loader = new FileLoader('/var/www/html/templates');
$latte->setLoader($loader);

// $latte->render('../../../etc/passwd'); // Це викличе виключення

// Відрендерити шаблон, розташований у /var/www/html/templates/pages/contact.latte
$latte->render('pages/contact.latte');

При використанні тегів на кшталт {include} або {layout}, якщо не вказано абсолютний шлях, імена шаблонів розпізнаються відносно поточного шаблону.

StringLoader

Цей завантажувач отримує вміст шаблону з асоціативного масиву, де ключами є назви (ідентифікатори) шаблонів, а значеннями – рядки вихідного коду шаблону. Це особливо корисно для тестування або невеликих додатків, де шаблони можуть зберігатися у самому 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}',
	// Додайте більше шаблонів за потреби
]);

$latte->setLoader($loader);

$latte->render('main.latte', ['name' => 'World']);
// Вихідні дані: Hello World, включити нижче:Включений вміст: 10

Якщо вам потрібно відрендерити лише один шаблон безпосередньо з рядка, без використання інклудів або успадкування, що посилаються на інші шаблони з іменованими рядками, ви можете передати рядок безпосередньо на render() або renderToString() при використанні StringLoader без масиву:

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

$templateString = 'Hello {$name}!';
$output = $latte->renderToString($templateString, ['name' => 'Alice']);
// $output містить 'Hello Alice!'.

Створення власного завантажувача

Щоб створити власний завантажувач (наприклад, для завантаження шаблонів з бази даних, кешу, контролю версій або іншого джерела), вам потрібно створити клас, який реалізує інтерфейс Latte\Loader.

Давайте розглянемо, що повинен робити кожен метод.

getContent (string $name): string

Це основний метод завантажувача. Він відповідає за отримання та повернення повного вмісту вихідного коду шаблону, ідентифікованого за адресою $name (переданого до $latte->render() або повернутого за допомогою getReferredName()).

Якщо шаблон неможливо знайти або отримати до нього доступ, цей метод повинен згенерувати Latte\RuntimeException.

public function getContent(string $name): string
{
	// Приклад: Вибірка з гіпотетичного внутрішнього сховища
	$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

Цей метод обробляє роздільну здатність імен шаблонів, що використовуються в тегах типу {include}, {layout} тощо. Коли Latte зустрічає, наприклад, {include 'partial.latte'} всередині main.latte, він викликає цей метод з $name = 'partial.latte' і $referringName = 'main.latte'.

Завдання методу полягає у перетворенні $name у канонічний ідентифікатор (наприклад, абсолютний шлях, унікальний ключ бази даних), який буде використано при виклику інших методів завантажувача, виходячи з контексту, наданого $referringName.

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

getUniqueId (string $name): string

Latte використовує кеш скомпільованих шаблонів для підвищення продуктивності. Кожному файлу скомпільованого шаблону потрібно присвоїти унікальне ім'я, отримане з ідентифікатора вихідного шаблону. Цей метод надає рядок, який унікально ідентифікує шаблон $name.

Для файлових шаблонів можна використовувати абсолютний шлях. Для шаблонів баз даних поширеною є комбінація префікса та ідентифікатора бази даних.

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

Приклад: Простий завантажувач баз даних

Цей приклад демонструє базову структуру завантажувача, який отримує шаблони, що зберігаються у таблиці бази даних templates зі стовпчиками name (унікальний ідентифікатор), content та 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;
	}

	// У цьому простому прикладі передбачається, що назви шаблонів ("домашня сторінка", "стаття" і т.д.)
	// є унікальними ідентифікаторами і шаблони не посилаються один на одного відносно.
	public function getReferredName(string $name, string $referringName): string
	{
		return $name;
	}

	public function getUniqueId(string $name): string
	{
		// Використання префікса і самої назви є унікальним і достатнім
		return 'db_' . $name;
	}
}

// Використання:
$pdo = new \PDO(/* connection details */);
$loader = new DatabaseLoader($pdo);
$latte->setLoader($loader);
$latte->render('homepage'); // Завантажує шаблон з іменем 'homepage' з БД

Користувацькі завантажувачі дають вам повний контроль над тим, звідки беруться ваші шаблони Latte, дозволяючи інтегрувати їх з різними системами зберігання та робочими процесами.

версія: 3.0