Створення власних функцій

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

Що таке функції?

Функції в Latte дозволяють розширити набір функцій, які можна викликати в межах виразів у шаблонах ({...}). Ви можете уявити їх як власні PHP-функції, доступні лише всередині ваших Latte-шаблонів. Це надає кілька переваг:

Зручність: Ви можете визначити допоміжну логіку (наприклад, обчислення, форматування або доступ до даних застосунку) і викликати її за допомогою простого, знайомого синтаксису функцій безпосередньо в шаблоні, так само, як ви б викликали strlen() або date() в PHP.

{var $userInitials = initials($userName)} {* напр. 'J. D.' *}

{if hasPermission('article', 'edit')}
    <a href="...">Edit</a>
{/if}

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

Інтеграція з логікою застосунку: PHP-об'єкт, що викликається, який стоїть за функцією Latte, може бути чим завгодно — анонімною функцією, статичним методом або методом екземпляра. Це означає, що ваші функції в шаблонах можуть легко отримувати доступ до сервісів застосунку, баз даних, конфігурації або будь-якої іншої необхідної логіки шляхом захоплення змінних (у випадку анонімних функцій) або за допомогою впровадження залежностей (у випадку об'єктів). Наведений вище приклад hasPermission це чітко демонструє, коли він, ймовірно, викликає на фоні сервіс авторизації.

Перевизначення нативних функцій (необов'язково): Ви можете навіть визначити функцію Latte з такою ж назвою, як у нативної PHP-функції. У шаблоні замість оригінальної функції буде викликана ваша власна версія. Це може бути корисно для надання поведінки, специфічної для шаблону, або забезпечення послідовної обробки (наприклад, забезпечення того, що strlen завжди буде багатобайтово безпечною). Використовуйте цю функцію обережно, щоб уникнути непорозумінь.

За замовчуванням Latte дозволяє викликати всі нативні PHP-функції (якщо вони не обмежені Sandbox). Власні функції розширюють цю вбудовану бібліотеку специфічними потребами вашого проекту.

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

Створення та реєстрація функцій

Подібно до фільтрів, існує кілька способів визначення та реєстрації власних функцій.

Пряма реєстрація за допомогою addFunction()

Найпростіший метод — це використання addFunction() на об'єкті Latte\Engine. Ви вказуєте назву функції (як вона буде відображатися в шаблоні) та відповідний PHP-об'єкт, що викликається.

$latte = new Latte\Engine;

// Проста допоміжна функція
$latte->addFunction('initials', function (string $name): string {
	preg_match_all('#\b\w#u', $name, $m);
	return implode('. ', $m[0]) . '.';
});

Використання в шаблоні:

{var $userInitials = initials($userName)}

Аргументи функції в шаблоні передаються безпосередньо PHP-об'єкту, що викликається, в тому ж порядку. Функціональність PHP, така як підказки типів, значення за замовчуванням та змінні параметри (...), працює як очікувалося.

Реєстрація за допомогою розширення

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

namespace App\Latte;

use Latte\Extension;
use Nette\Security\Authorizator;

class MyLatteExtension extends Extension
{
	public function __construct(
		// Припускаємо, що сервіс Authorizator існує
		private Authorizator $authorizator,
	) {
	}

	public function getFunctions(): array
	{
		// Реєстрація методів як функцій Latte
		return [
			'hasPermission' => $this->hasPermission(...),
		];
	}

	public function hasPermission(string $resource, string $action): bool
	{
		return $this->authorizator->isAllowed($resource, $action);
	}
}

// Реєстрація (припускаємо, що $container містить DI-контейнер)
$extension = $container->getByType(App\Latte\MyLatteExtension::class);
$latte = new Latte\Engine;
$latte->addExtension($extension);

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

Функції, що використовують клас з атрибутами

Так само, як і фільтри, функції можуть бути визначені як методи у вашому класі параметрів шаблону за допомогою атрибута #[Latte\Attributes\TemplateFunction].

use Latte\Attributes\TemplateFunction;

class TemplateParameters
{
	public function __construct(
		public string $userName,
		// інші параметри...
	) {}

	// Цей метод буде доступний як {initials(...)} у шаблоні
	#[TemplateFunction]
	public function initials(string $name): string
	{
		preg_match_all('#\b\w#u', $name, $m);
		return implode('. ', $m[0]) . '.';
	}
}

// Передача об'єкта до шаблону
$params = new TemplateParameters(userName: 'John Doe', /* ... */);
$latte->render('template.latte', $params);

Latte автоматично виявить та зареєструє методи, позначені цим атрибутом, коли об'єкт параметрів передається до шаблону. Назва функції в шаблоні відповідає назві методу.

{* Використання функції, визначеної в класі параметрів *}
{var $inits = initials($userName)}

Контекстні функції?

На відміну від фільтрів, не існує прямого поняття “контекстних функцій”, які б отримували об'єкт, подібний до FilterInfo. Функції працюють у межах виразів і зазвичай не потребують прямого доступу до контексту рендерингу або інформації про тип вмісту так само, як фільтри, застосовані до блоків.

версія: 3.0