Завантажувачі

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

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

Коли ви працюєте з шаблонами, зазвичай уявляєте собі файли .latte, розташовані в структурі каталогів вашого проекту. Цим займається стандартний FileLoader в Latte. Однак зв'язок між назвою шаблону (наприклад, '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 для файлів у '/path/to/templates'
$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, include is below:Included content: 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.

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

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

	// Цей простий приклад припускає, що назви шаблонів ('homepage', 'article', тощо)
	// є унікальними ID, і шаблони не посилаються один на одного відносно.
	public function getReferredName(string $name, string $referringName): string
	{
		return $name;
	}

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

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

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

версія: 3.0