ALBIREO CMS
version: 2025.11.01
© Albireo CMS, 2020-2025

Функции шаблонизатора Albireo CMS

tpl tplContent

Функция tpl

Функция tpl является высокоуровневой оберткой для шаблонизатора tplContent. Её основная задача — загружать шаблоны из файлов, кешировать их содержимое для повышения производительности и передавать их на обработку. Это основной способ использования шаблонизатора при работе с файлами.

Сигнатура

function tpl(string $tpl, array $data = [], array $add = [], bool $compress = false): string

Аргументы

string $tpl
Полный путь к файлу шаблона (.php или .html), который необходимо обработать.
array $data (необязательный)
Основной ассоциативный массив данных. Ключи этого массива (например, $data['title']) становятся переменными ($title) внутри шаблона.
array $add (необязательный)
Дополнительный массив данных, который также преобразуется в переменные. Удобен для передачи глобальных или вспомогательных переменных.
bool $compress (необязательный)
Если true, итоговый HTML-код будет сжат (минимизирован) с помощью функции compressHtml(). По умолчанию false.

Результат

Возвращает строку (string) с отрендеренным HTML-кодом. Если файл шаблона не найден, возвращается пустая строка.

Примеры использования

Пример 1: Рендеринг основного шаблона страницы

Файл шаблона main-layout.php:

<!DOCTYPE html>
<html>
<head>
    <title>{* $pageTitle *}</title>
</head>
<body>
    <h1>{{ $pageH1 }}</h1>
    <div class="content">
        {{ $content }}
    </div>
</body>
</html>

Вызов в PHP:

$pageData = [
    'pageTitle' => 'Моя страница',
    'pageH1' => 'Добро пожаловать!',
    'content' => '<p>Это содержимое страницы.</p>'
];

echo tpl(TPL_DIR . 'main-layout.php', $pageData);

Пример 2: Использование в цикле для вывода списка

Благодаря внутреннему кешированию, файл list-item.php будет прочитан с диска только один раз, что значительно повышает производительность.

Файл шаблона list-item.php:

<li><a href="{{ $url }}">{{ $name }}</a></li>

Вызов в PHP:

$menuItems = [
    ['name' => 'Главная', 'url' => '/'],
    ['name' => 'О нас', 'url' => '/about'],
    ['name' => 'Контакты', 'url' => '/contact'],
];

echo '<ul>';
foreach ($menuItems as $item) {
    // На каждой итерации используется закешированное содержимое файла
    echo tpl(TPL_DIR . 'list-item.php', $item);
}
echo '</ul>';

Примечания

  • Кеширование: Функция кеширует содержимое последнего запрошенного файла в статической переменной. Это делает её очень эффективной для рендеринга множества однотипных элементов в цикле.
  • Различие с tplContent: Ключевое различие в том, что tpl() работает с файлами, а tplContent() — с текстовыми строками.

Функция tplContent

Функция tplContent представляет собой мощный, но легковесный PHP-шаблонизатор, реализованный в одной функции. Она преобразует строку с кастомным синтаксисом в нативный PHP-код, выполняет его и возвращает результат. Шаблонизатор поддерживает переменные, условия, циклы, безопасный вывод, комментарии и множество других директив, вдохновленных популярными движками, такими как Blade и Twig.

Сигнатура

function tplContent(string $_Content, array $DATA = [], array $ADD = [], string $FILE = ''): string

Аргументы

string $_Content
Строка с текстом шаблона, содержащая как обычный HTML, так и специальный синтаксис шаблонизатора.
array $DATA
Основной ассоциативный массив данных. Ключи этого массива (после очистки от недопустимых символов) становятся переменными, доступными внутри шаблона.
array $ADD
Дополнительный массив данных, который также преобразуется в переменные. Если ключи в $ADD совпадают с ключами в $DATA, переменные из $DATA не будут перезаписаны.
string $FILE
Путь к файлу шаблона. Этот параметр не влияет на логику, но используется для вывода более информативных сообщений об ошибках, указывая, в каком файле произошла ошибка.

Результат

Возвращает строку (string) с результатом выполнения шаблона (как правило, это готовый HTML-код).

Синтаксис шаблонов

См. TPL-шаблонизатор в Albireo CMS.

Вывод переменных

{{ $variable }}
Выводит содержимое переменной. Эквивалентно <?= $variable ?>.
{* $variable *}
Выводит содержимое переменной, предварительно экранировав его с помощью htmlspecialchars(). Эквивалентно <?= htmlspecialchars($variable, ENT_QUOTES) ?>.

Управляющие конструкции

{@if $condition} ... {@elseif $condition2} ... {@else} ... {@endif}
Стандартные условные операторы. Поддерживается отрицание: {@if! $condition}.
{@isset $var} ... {@endisset}
Проверяет существование переменной. Поддерживается отрицание {@isset! $var} и конструкции {@elseisset $var}.
{@empty $var} ... {@endempty}
Проверяет переменную на "пустоту". Поддерживается отрицание {@empty! $var} и конструкции {@elseempty $var}.
{@check $var} ... {@endcheck}
Специальная проверка. Блок выполняется, если переменная $var существует и её значение "положительно" (checkStr($var) === true). Поддерживается отрицание {@check! $var}.

Циклы

{@foreach $array as $item} ... {@endforeach}
Стандартный цикл foreach.
{@for ...} ... {@endfor}
Стандартный цикл for.
{@while ...} ... {@endwhile}
Стандартный цикл while.
{@continue} / {@break}
Операторы для управления циклом. Поддерживается условная форма: {@continue $condition}.

Специальные директивы

{@loop $DATA} ... {@endloop}
Расширенный цикл foreach. Внутри блока доступны переменные: $loopIndex, $loopKey, $loopFirst, $loopLast, $loopCount, $loopEven, $loopOdd, $loopRemaining. Все ключи текущего элемента цикла также становятся переменными.
{@loopfile $DATA, 'path/to/template.php'}
Аналогичен {@loop}, но вместо блока кода для каждого элемента массива подключает и выполняет указанный tpl-файл, передавая в него те же вспомогательные переменные.
{@contentFile}
Используется внутри {@loop} для вывода содержимого файла, связанного с текущим элементом цикла.
{@lang Text to translate}
Обертка для функции перевода. Эквивалентно echo lang('Text to translate').
{@class ['class1', 'class2' => $condition]}
Динамически формирует строку CSS-классов. Класс добавляется, если его значение истинно (true).
{@style ['style1' => $condition, 'style2']}
Динамически формирует строку для атрибута style.
{@verbatim} ... {@endverbatim}
Блок, содержимое которого не обрабатывается шаблонизатором. Полезно для вставки JavaScript-кода.
{# Комментарий #}
Комментарий, который будет полностью удален из итогового кода.

Примеры использования

Пример 1: Простой шаблон с переменными и условием

$template = '
<h1>{* $title *}</h1>
{@if $user_role === "admin"}
    <p>У вас права администратора.</p>
{@else}
    <p>Вы обычный пользователь.</p>
{@endif}
';

$data = [
    'title' => 'Страница пользователя & "Гость"',
    'user_role' => 'admin'
];

echo tplContent($template, $data);

Пример 2: Использование расширенного цикла {@loop}

$template = '
<ul>
{@loop $items}
    <li class="{@class ["first-item" => $loopFirst, "last-item" => $loopLast]}">
        {{ $loopIndex }}. {{ $name }} ({{ $status }})
    </li>
{@endloop}
</ul>
';

$data = [
    'items' => [
        ['name' => 'Задача 1', 'status' => 'Выполнена'],
        ['name' => 'Задача 2', 'status' => 'В процессе'],
        ['name' => 'Задача 3', 'status' => 'Новая'],
    ]
];

echo tplContent($template, $data);

Примечания

  • Безопасность: Функция использует eval(), что является потенциальной угрозой безопасности, если в шаблоны может попасть недоверенный код. Используйте её только с шаблонами, которые находятся под вашим полным контролем.
  • Кеширование: Скомпилированный PHP-код шаблона кешируется в статической переменной на время выполнения запроса, что предотвращает повторную обработку одного и того же шаблона.