Функции прочие Albireo CMS

addClassmap comments extractDomain extras formHandler mail64 markdown module nextPrev promptsInfo snippet statCountPage stopWords templateModules textsimple widgets

Функция addClassmap

Функция addClassmap позволяет зарегистрировать путь к файлу или каталогу для автозагрузки классов, которые не соответствуют стандарту PSR-4. Она создает "карту классов" во временном хранилище, которая затем может быть использована автозагрузчиком, зарегистрированным через spl_autoload_register().

Сигнатура

function addClassmap(string $class, string $path): void

Аргументы

string $class

Имя класса или префикс пространства имен.

Полное имя класса: Например, 'My\Old\Logger'.
Префикс пространства имен: Например, 'MyModule'.

string $path

Полный путь на сервере.

Если в $class указано имя класса, здесь должен быть путь к файлу.
Если в $class указан префикс пространства имен, здесь должен быть путь к каталогу.

Результат

Функция ничего не возвращает (void). Её результат — это добавление новой записи в карту классов, которая используется автозагрузчиком.

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

Пример 1: Регистрация конкретного класса

Это полезно для подключения отдельных классов из старых библиотек или с нестандартной структурой.

// Регистрируем класс 'Smarty' из сторонней библиотеки
addClassmap('Smarty', VENDOR_DIR . 'smarty/libs/Smarty.class.php');

// Теперь автозагрузчик сможет найти и подключить этот класс
// $smarty = new Smarty();

Пример 2: Регистрация префикса пространства имен

Предположим, у вас есть модуль, классы которого лежат в одной папке, но имеют общее пространство имен.

// Структура файлов:
// /modules/feedback/
//   |- Controller.php  (содержит класс feedback\Controller)
//   |- Model.php       (содержит класс feedback\Model)

// Регистрируем префикс 'feedback' и указываем путь к каталогу
addClassmap('feedback', MODULES_DIR . 'feedback/');

// Теперь автозагрузчик сможет корректно обработать следующие вызовы:
// $controller = new feedback\Controller(); // Найдет /modules/feedback/Controller.php
// $model = new feedback\Model();          // Найдет /modules/feedback/Model.php

Примечания

Механизм работы: Функция сама по себе не загружает классы. Она лишь наполняет массив-карту, который хранится с помощью функций setVal/getVal.
Время жизни карты: Карта классов существует только в рамках одного HTTP-запроса.
Назначение: Основное назначение — обеспечить совместимость и автозагрузку для кода, не соответствующего современным стандартам автозагрузки, таким как PSR-4.

Функ-ция comments

Функция comments отвечает за полный цикл отображения комментариев на странице: она получает данные о комментариях из специализированного класса и передает их в шаблон для отрисовки. Функция работает в контексте текущей страницы, для которой она вызывается.

Сигнатура

function comments(): void

Аргументы

Функция не принимает аргументов.

Результат

Функция ничего не возвращает (void). Её результат — это прямой вывод (echo) HTML-кода, сгенерированного шаблоном комментариев.

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

1. Вызов в шаблоне страницы

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

<!-- В файле шаблона страницы, например, post.php -->
<div class="content">
    <?= $postContent ?>
</div>

<hr>

<div class="comments-section">
    <h2>Комментарии</h2>
    <?php comments(); ?>
</div>

2. Пример шаблона комментариев

Функция передает данные в шаблон TPL_DIR/comments/comment.php. Этот шаблон может выглядеть следующим образом:

{# --- TPL_DIR/comments/comment.php --- #}

<section class="container-comments"><a name="comments"></a>
    <div class="mar30-t mar20-b h4 bor-primary200 dark:bor-primary600 bor2 bor-solid-b">{@lang Comments} {@isset $count}({{ $count }}){@endisset} <a class="bi-rss-fill t90 pad7-rl bg-orange600 t-orange50 rounded b-inline b-right mar10-t hover-bg-primary600 hover-t-primary100 hover-no-underline" href="{{ SITE_URL }}rss-comments.xml">RSS</a></div>

    {@loop $DATA}
    {@if $allow}
        <a name="comment{{ $dateT }}"></a>
        <div class="{@class ['mar30-t', 'bg-primary100 dark:bg-primary700 rounded pad20-rl pad10-tb' => $mark ]}">
            <div class="t-primary600 dark:t-primary300 t100"><span class="bg-primary100 dark:bg-primary600 mar5-r pad5 rounded t-bold">{{ $loopIndex }}</span> <span class="mar15-r {@class ['bi-person' => !$user_emoji ]}">{* $user_emoji *} {* $author *}</span> <span class="bi-calendar mar15-r">{* $date *}</span>{@if $user}<span class="bi-check2-circle mar5-r" title="{@lang Registered user of the site}"></span>{@endif}{@if $edit} <a class="bi-pencil-square mar15-r" href="{{ $edit }}">Edit</a>{@endif} {@if $mark} <span class="b-inline b-right bg-primary200 t-primary700 pad3 rounded t80">{{ $mark }}</span> {@endif}</div>
            <div class="mar20-t"><!-- nosimple -->{{ $content }}<!-- /nosimple --></div>
        </div>
    {@else}
        <a name="comment{{ $dateT }}"></a>
        <div class="mar30-t">
            <div class="t-primary600 dark:t-primary300 t90"><span class="bg-primary100 dark:bg-primary600 mar5-r pad5 rounded t-bold">{{ $loopIndex }}</span>  <span class="bi-calendar mar15-r">{* $date *}</span>{@if $edit} <a class="bi-pencil-square mar15-r" href="{{ $edit }}">Edit</a>{@endif}</div>
            <div class="mar20-t t-primary500">{@lang Comment awaiting moderation}</div>
        </div>
    {@endif}

    {@if !$loopLast}
    <hr class="bor-primary200 dark:bor-primary600 bor2 dotted mar10-b">
    {@endif}

    {@endloop}
</section>

Примечания

Неодобренные комментарии: функция получает все комментарии, включая неодобренные. Логика их скрытия или отображения со специальной пометкой должна быть реализована внутри шаблона (например, с помощью проверки прав текущего пользователя).

Функция extractDomain

Извлекает основной домен из строки хоста. Функция умеет корректно обрабатывать составные домены верхнего уровня (такие как com.ua, co.uk), позволяя получить домен второго уровня (example.com.ua) вместо поддомена (sub.example.com.ua).

Сигнатура

function extractDomain(string $host, array $suffixList = ['com.ua', 'in.ua', 'co.ua']): string

Аргументы

string $host: Строка хоста для анализа. Например, 'www.example.com' или 'test.sub.in.ua'.
array $suffixList (необязательный): Массив строковых суффиксов, которые нужно считать частью домена верхнего уровня. По умолчанию: ['com.ua', 'in.ua', 'co.ua'].

Результат

Возвращает строку (string) с извлеченным доменом в нижнем регистре.

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

Пример 1: Стандартное использование

Для обычных хостов функция вернет домен второго уровня.

$host1 = 'WWW.My-Site.COM';
$domain1 = extractDomain($host1);
// $domain1 будет равен 'my-site.com'

$host2 = 'blog.wordpress.org';
$domain2 = extractDomain($host2);
// $domain2 будет равен 'wordpress.org'

Пример 2: Обработка составных доменов

Функция использует список по умолчанию для корректного определения домена.

// Хост заканчивается на 'com.ua', который есть в списке по умолчанию
$host1 = 'shop.my-store.com.ua';
$domain1 = extractDomain($host1);
// $domain1 будет равен 'my-store.com.ua'

// Хост заканчивается на 'in.ua'
$host2 = 'test.api.service.in.ua';
$domain2 = extractDomain($host2);
// $domain2 будет равен 'service.in.ua'

Пример 3: Использование собственного списка суффиксов

Можно передать свой массив суффиксов для обработки доменных зон, не включенных в список по умолчанию.

$ukHost = 'news.bbc.co.uk';
$ukSuffixes = ['co.uk', 'gov.uk', 'ac.uk'];

$domain = extractDomain($ukHost, $ukSuffixes);
// $domain будет равен 'bbc.co.uk'

Примечания

Функция нечувствительна к регистру, так как первым шагом приводит хост к нижнему регистру.
Если в хосте всего одна точка (например, 'example.com'), он возвращается без изменений.
Если ни один из суффиксов в $suffixList не найден, функция использует стандартный подход, возвращая две последние части хоста, разделенные точкой.

Функция extras

Функция extras является высокоуровневой оберткой для подключения и рендеринга шаблонных файлов, называемых 'extras'. Она автоматизирует процесс поиска файла в определенных директориях, позволяя реализовать механизм переопределения (сначала ищется пользовательская версия в SERVICE_DIR/my/extras/, а затем — стандартная в EXTRAS_DIR). После нахождения файла он обрабатывается шаблонизатором tpl.

Сигнатура

function extras(string $file, array $add = [], bool $compress = true): ?string

Аргументы

string $file: Имя файла для подключения. Функция будет искать этот файл в директориях SERVICE_DIR/my/extras/ и EXTRAS_DIR.
array $add (необязательный): Ассоциативный массив с дополнительными переменными, которые будут переданы в шаблон. Эти данные дополняют основные данные страницы, получаемые из getPageData().
bool $compress (необязательный): Если установлено в true (по умолчанию), итоговый HTML будет сжат (удалены лишние пробелы и переносы строк). Установите в false для отладки.

Результат

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

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

Пример 1: Простое подключение блока

Подключение стандартного блока, например, футера сайта. Функция найдет файл footer.php в одной из заданных директорий и выведет его содержимое.

// Выводим футер сайта
echo extras('footer.php');

Пример 2: Передача данных в шаблон

Подключение блока с передачей в него пользовательских данных. Внутри шаблона product_card.php будут доступны переменные $id, $name и $price.

// Данные о товаре
$productData = [
    'id' => 123,
    'name' => 'Беспроводные наушники',
    'price' => '4990 грн'
];

// Отображение карточки товара
echo extras('product_card.php', $productData);

Пример 3: Демонстрация механизма переопределения

Предположим, есть стандартный файл EXTRAS_DIR/social_links.php. Если пользователь хочет изменить его, он может создать свой файл SERVICE_DIR/my/extras/social_links.php. Функция extras автоматически подключит пользовательскую версию.

// Этот вызов подключит SERVICE_DIR/my/extras/social_links.php, если он существует,
// в противном случае будет использован EXTRAS_DIR/social_links.php.
echo extras('social_links.php');

Функция formHandler

Функция formHandler является вспомогательным инструментом для создания безопасных форм. Она генерирует скрытое поле <input>, которое содержит зашифрованную информацию о том, какой серверный скрипт или какая функция должна обработать данные этой формы. Это позволяет централизованно обрабатывать запросы, предотвращая возможность пользователя напрямую указать исполняемый файл.

Примечание. Для корректной работы с AJAX, если используется стандартный обработчик (REQUEST_AJAX), необходимо, чтобы имя файла/функции заканчивалось на _handler, например contact_handler.php, my_func_contact_handler.

Сигнатура

function formHandler(string $file, bool $func = false): string

Аргументы

string $file

Путь к файлу-обработчику или имя функции-обработчика.

bool $func (необязательный)

Определяет, как трактовать параметр $file.

Если false (по умолчанию), $file считается путем к файлу, и создается поле с именем _handler.
Если true, $file считается именем функции, и создается поле с именем _handler_func.

Результат

Возвращает HTML-строку (string), содержащую тег <input type="hidden"> с зашифрованным значением.

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

Основные примеры см. в «pages/specific/demo».

Примечания

Безопасность: Ключевой особенностью является шифрование пути/имени обработчика. Это не позволяет злоумышленнику изменить значение в HTML-коде и заставить сервер выполнить произвольный файл или функцию.
Серверная часть: Сама по себе эта функция бесполезна без соответствующей логики на сервере, которая будет принимать, расшифровывать и исполнять указанный обработчик. Часто она используется в связке с функцией, обрабатывающей AJAX-запросы.

Функция mail64

Отправляет почтовое сообщение, обеспечивая совместимость с различными почтовыми клиентами за счет использования кодировки Base64 для темы, тела письма и частей заголовков. Это решает распространенные проблемы с отображением кириллических и других не-ASCII символов.

Сигнатура

function mail64(string $to, string $subject, string $message, array $headers = [], array $additional = []): bool

Аргументы

string $to

Email-адрес получателя.

string $subject

Тема письма. Функция автоматически кодирует её в формат, понятный почтовым клиентам (=?UTF-8?B?...?=).

string $message

Тело письма.

По умолчанию отправляется как простой текст (text/plain).
Для отправки письма в формате HTML, строка сообщения должна начинаться с префикса 'HTML'. Этот префикс будет удален перед отправкой.

array $headers (необязательный)

Ассоциативный массив для формирования заголовков письма, таких как From, Reply-To, Cc и т.д.
Особенность: для кодирования не-ASCII имён или фраз в значениях заголовков, оберните их в двойные фигурные скобки, например: 'From' => '{{Иван Петров}} <ivan@server.com>'.

array $additional (необязательный)

Массив дополнительных параметров, которые будут добавлены в конец заголовков в виде строк. Используется для нестандартных случаев.

Результат

Возвращает булево значение (bool): true, если письмо было успешно принято для доставки почтовым сервером, и false в случае ошибки. Успешная отправка не гарантирует доставку письма.

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

Пример 1: Отправка простого текстового письма с кириллицей

$to = 'recipient@example.com';
$subject = 'Уведомление с сайта';
$message = 'Здравствуйте! Ваша заявка принята.';
$headers = ['From' => 'no-reply@mysite.com'];

mail64($to, $subject, $message, $headers);

Пример 2: Отправка HTML-письма с указанием имени отправителя

Обратите внимание на префикс 'HTML' в сообщении и конструкцию {{...}} в заголовке From.

$to = 'manager@example.com';
$subject = 'Новый заказ №123';

$message = 'HTML' .
    '<h1>Поступил новый заказ</h1>' .
    '<p>Детали заказа доступны в <a href="https://mysite.com/admin/orders/123">панели управления</a>.</p>';

$headers = [
    'From' => '{{Интернет-магазин "Техника"}} <sales@mysite.com>',
    'Reply-To' => 'manager@mysite.com'
];

mail64($to, $subject, $message, $headers);

Примечания

Функция является обёрткой над стандартной функцией PHP mail(), поэтому для её работы требуется настроенный почтовый сервер (sendmail или SMTP).
Источник и дополнительная информация: https://maxsite.org/page/php-mail

Функция markdown

Функция markdown преобразует текст, написанный на языке разметки Markdown, в HTML. Она использует популярную библиотеку Parsedown для выполнения этой задачи. В функцию встроена специальная логика для обхода проблемы, связанной с обработкой декларации <!DOCTYPE HTML> в парсере.

Сигнатура

function markdown(string $text): string

Аргументы

string $text: Строка, содержащая текст в формате Markdown.

Результат

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

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

Пример 1: Базовое преобразование

Преобразование основного синтаксиса Markdown в HTML.

$markdownContent = <<<MARKDOWN
# Главный заголовок

Это простой параграф с *курсивом* и **жирным** текстом.

- Элемент списка 1
- Элемент списка 2

[Это ссылка](https://example.com)
MARKDOWN;

$htmlContent = markdown($markdownContent);
echo $htmlContent;

Результатом будет корректный HTML-код с тегами <h1>, <p>, <em>, <strong>, <ul>, <li> и <a>.

Пример 2: Использование в Albireo CMS

В настройках страницы можно указать, что её содержимое нужно обрабатывать как Markdown.

title: Моя статья в Markdown
parser: markdown

# ОПЦИОНАЛЬНО. Указывает, что контент обрабатывается отдельно
# content-separate: 1

Примечания

Обход проблемы с DOCTYPE: Функция временно комментирует строку <!DOCTYPE HTML>, чтобы парсер её не испортил, а после обработки возвращает её в исходное состояние. Это позволяет использовать Markdown внутри полноценных HTML-документов.
Ссылки на документацию:
- Официальный сайт Parsedown: https://parsedown.org/
- Спецификация CommonMark: https://spec.commonmark.org/

Функция module

Функция module предоставляет удобный и безопасный способ для подключения файлов-модулей. Модули хранятся в специальных директориях.

Основное преимущество функции — она абстрагирует полный путь к файлу и выполняет проверку на его существование перед подключением, что делает код более чистым и надежным.

Сигнатура

function module(string $file, string $dir = ''): void

Аргументы

string $file: Имя файла модуля, который нужно подключить (например, 'header.php').
string $dir (необязательный): Полный путь к директории, где следует искать файл. Если параметр опущен или передан как пустая строка, будет использовано значение константы TEMPLATE_MODULES_DIR.

Результат

Функция ничего не возвращает (void). Её результат — это подключение и выполнение кода из указанного файла, если он существует.

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

Пример 1: Подключение стандартного модуля

Подключение модуля шапки сайта.

module('site-header.php');

Пример 2: Подключение модуля из альтернативной директории

// Подключаем модуль галереи из указанного каталога
module('gallery-widget.php', SERVICE_DIR . 'my-gallery/modules/');

Примечания

Убедитесь, что путь в параметре $dir заканчивается слэшем для корректной конкатенации с именем файла.

Функция nextPrev

Находит и возвращает информацию о предыдущей и следующей записях в блоге относительно текущей страницы. Эта функция полезна для создания навигации «Вперед/Назад» на страницах постов.

Функция автоматически определяет текущую страницу, выполняет один сложный SQL-запрос для получения всех необходимых данных и кеширует результат для повышения производительности при повторных вызовах.

Сигнатура

function nextPrev(): array|false

Аргументы

Функция не принимает аргументов. Она является контекстно-зависимой и получает необходимую информацию о текущей странице из других функций системы (getPageData("this-file")).

Результат

Возвращает ассоциативный массив с данными или false.

array — если текущая страница является записью блога и для нее удалось найти информацию. Массив будет содержать следующие ключи:

prev_file (string|null)

Идентификатор файла предыдущей записи.

prev_title (string|null)

Заголовок предыдущей записи.

prev_url (string|null)

URL-адрес предыдущей записи.

next_file (string|null)

Идентификатор файла следующей записи.

next_title (string|null)

Заголовок следующей записи.

next_url (string|null)

URL-адрес следующей записи.

Если предыдущей или следующей записи нет, соответствующие значения будут null.
false — если текущая страница не является опубликованной записью блога или не была найдена в базе данных.

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

Пример создания навигационных ссылок на странице поста

Этот код можно разместить в шаблоне страницы блога для вывода ссылок на соседние посты.

<?php
// Получаем данные о соседних записях
$navigation = nextPrev();

// Проверяем, что данные получены
if ($navigation) {
    echo '<nav class="post-navigation">';

    // Если есть предыдущая запись, выводим ссылку на неё
    if ($navigation['prev_url']) {
        echo '<div class="nav-previous">';
        echo '<a href="' . $navigation['prev_url'] . '">';
        echo '<span class="meta-nav">Предыдущая запись:</span> ';
        echo htmlspecialchars($navigation['prev_title']);
        echo '</a></div>';
    }

    // Если есть следующая запись, выводим ссылку на неё
    if ($navigation['next_url']) {
        echo '<div class="nav-next">';
        echo '<a href="' . $navigation['next_url'] . '">';
        echo '<span class="meta-nav">Следующая запись:</span> ';
        echo htmlspecialchars($navigation['next_title']);
        echo '</a></div>';
    }

    echo '</nav>';
}
?>

Примечания

Кеширование: Результат выполнения кешируется в статической переменной. Это означает, что запрос к базе данных будет выполнен только при первом вызове функции в рамках одного HTTP-запроса. Все последующие вызовы мгновенно вернут сохраненный результат.

Функция promptsInfo

Функция promptsInfo генерирует список URL-ссылок на различные ИИ-платформы (например, ChatGPT, Google AI Studio) с уже подготовленными промптами. Эти промпты формируются на основе конфигурационного файла и текущего URL-адреса страницы, что позволяет быстро отправлять контекст текущей страницы в ИИ для анализа.

Сигнатура

function promptsInfo(string $file, string $pageUrl): array

Аргументы

string $file

Имя конфигурационного файла (например, 'ai_prompts.php'). Этот файл должен располагаться в директории CONFIG_DIR и возвращать PHP-массив. Каждый элемент массива должен соответствовать структуре:

[
    'title' => 'Проанализировать статью', // Заголовок промпта
    'prompt' => 'Проанализируй содержание статьи: [URL]', // Шаблон промпта
    'ai' => 'chatgpt, aistudio', // Список ИИ-платформ через запятую (по умолчанию 'chatgpt')
    'show' => true // (Необязательно) Если false, промпт будет проигнорирован. По умолчанию true.
]

string $pageUrl

Полный URL-адрес текущей страницы, который будет подставлен в шаблон промпта. В шаблоне промпта строка [URL] будет заменена на это значение. Также, две косые черты // в шаблоне промпта будут заменены на символ новой строки (LF), позволяя создавать многострочные промпты.

Результат

Функция возвращает массив типа array<int, array{0, 1}>, где каждый внутренний массив содержит два элемента:

0: Полный URL-адрес, ведущий на соответствующую ИИ-платформу с уже закодированным промптом. Значение предварительно обработано htmlspecialchars().
1: Заголовок промпта, взятый из конфигурации, с добавленной в скобках меткой ИИ-платформы (например, "Проанализировать статью (ChatGPT)"). Значение также обработано htmlspecialchars().

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

// $page_url_full соджержит адрес текущй страницы
foreach(promptsInfo('prompts-info1.php', $page_url_full) as $_elem) {
    echo '<a href="' . $_elem[0] . '">' . $_elem[1] . '</a> ';
}

Примечания

Все генерируемые ссылки и заголовки проходят через htmlspecialchars(), что делает их безопасными для непосредственного вывода в HTML.
Промпты кодируются с помощью urlencode(), что обеспечивает их корректную передачу в URL-адресе.

Функция snippet

Функция snippet предназначена для подключения и вывода небольших, переиспользуемых фрагментов кода (сниппетов). Она реализует механизм поиска файла в нескольких директориях, что позволяет переопределять стандартные сниппеты в шаблоне. Все ошибки, возникающие при выполнении сниппета, отлавливаются, чтобы избежать падения всего сайта.

Сигнатура

function snippet(string $snippet, mixed $DATA = '', mixed $DATA1 = '', mixed $DATA2 = '', mixed $DATA3 = ''): void

Аргументы

string $snippet: Имя файла сниппета без расширения .php. Функция будет искать файл [имя].php.
mixed $DATA (необязательный): Данные любого типа (чаще всего массив или объект), которые будут доступны внутри подключенного файла как переменная $DATA.
mixed $DATA1 (необязательный): Дополнительные данные, доступные как переменная $DATA1.
mixed $DATA2 (необязательный): Дополнительные данные, доступные как переменная $DATA2.
mixed $DATA3 (необязательный): Дополнительные данные, доступные как переменная $DATA3.

Результат

Функция ничего не возвращает (void). Она напрямую выводит результат выполнения файла-сниппета в поток вывода (как правило, HTML-код).

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

Пример 1: Подключение простого сниппета

Вызов сниппета для отображения блока с иконками социальных сетей.

// Вызов в основном шаблоне:
snippet('social_links');

// Содержимое файла /snippets/social_links.php:
// <?php
// echo '<div class="social"><a href="#">VK</a> <a href="#">Telegram</a></div>';
// ?>

Пример 2: Передача данных в сниппет

Вывод навигации «Вперед/Назад» с передачей массива URL-адресов.

// Вызов в шаблоне страницы:
$navigation = ['prev_url' => '/blog/post1', 'next_url' => '/blog/post3'];
snippet('post_navigation', $navigation);

// Содержимое файла /snippets/post_navigation.php:
// <?php
// // Переменная $DATA доступна здесь
// if (!empty($DATA['prev_url'])) {
//     echo '<a href="' . $DATA['prev_url'] . '">« Назад</a>';
// }
// if (!empty($DATA['next_url'])) {
//     echo '<a href="' . $DATA['next_url'] . '">Вперед »</a>';
// }
// ?>

Пример 3: Демонстрация обработки ошибок

Если в коде сниппета есть ошибка, функция snippet предотвратит крах страницы.

// Вызов сниппета с ошибкой
snippet('broken_snippet');

// Содержимое файла /snippets/broken_snippet.php:
// <?php
// // Эта функция не существует и вызовет ошибку
// non_existent_function();
// ?>

// На странице будет выведено сообщение вроде:
// "Error (snippet) in <b>broken_snippet</b>: Call to undefined function non_existent_function() in line 3"

Функция statCountPage

Получает и возвращает количество просмотров (прочтений) для текущей страницы. Функция является оберткой для сервиса \PageViews\PageViews и имеет особенность: она возвращает результат, только если количество просмотров больше единицы. Это позволяет не отображать счетчик для страниц с очень низкой популярностью.

Сигнатура

function statCountPage(): int|string

Аргументы

Функция не принимает аргументов. Она является контекстно-зависимой и получает информацию о текущей странице из сервиса, который она вызывает.

Результат

Возвращает целое число или пустую строку:

int — количество просмотров, если оно больше 1.
string — пустая строка (''), если количество просмотров равно 0 или 1, или если сервис статистики недоступен.

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

Пример: Отображение счетчика просмотров в шаблоне

Функция идеально подходит для использования в шаблонизаторах или PHP-вставках для отображения статистики.

<?php 
$viewCount = statCountPage();

if ($viewCount) {
    echo '<span class="page-views" title="Количество просмотров">';
    echo '👁️ ' . $viewCount;
    echo '</span>';
}
?>

В этом примере блок со счетчиком будет выведен только в том случае, если у страницы 2 или более просмотров.

Пример из документации (для внутреннего шаблонизатора)

{@check $stat_page}
    {@ $statCountPage = statCountPage() @}
    {@if $statCountPage}
        <span class="mar10-r bi-eye" title="{@lang Post views}">{{ $statCountPage }}</span>
    {@endif}
{@endcheck}

Примечания

Контекст: Функция работает с "текущей" страницей.
Порог отображения: Ключевой особенностью является порог > 1.

Функция stopWords

Функция stopWords предназначена для антиспам-проверки. Она анализирует переданную строку на наличие запрещенных слов или фраз (стоп-слов), которые загружаются из специального конфигурационного файла. Проверка является регистронезависимой, поддерживает Unicode (UTF-8) и ищет только полные слова, чтобы избежать ложных срабатываний (например, слово 'art' не будет найдено внутри 'start').

Сигнатура

function stopWords(string $text): array

Аргументы

string $text: Текст, который необходимо проверить на спам. Например, комментарий пользователя или текст из формы обратной связи.

Результат

Возвращает индексированный массив (array) строк, содержащий все уникальные стоп-слова, найденные в тексте. Если совпадений нет, возвращается пустой массив.

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

Пример 1: Проверка комментария на спам

Это основной сценарий использования функции. Мы проверяем текст и, если результат — непустой массив, помечаем его как спам.

// Содержимое файла CONFIG_DIR/stop-words.php:
// casino
// pharmacy
// buy now

$userComment = "Hello! Check out my new cool pharmacy site!";

$foundSpam = stopWords($userComment);

if (!empty($foundSpam)) {
    // Действия при обнаружении спама
    // Например, отклонить комментарий или отправить на модерацию
    echo "Комментарий содержит запрещенные слова: " . implode(', ', $foundSpam);
    // Вывод: Комментарий содержит запрещенные слова: pharmacy
} else {
    // Комментарий прошел проверку
    echo "Комментарий успешно принят.";
}

Пример 2: Демонстрация регистронезависимости и поиска целых слов

Функция корректно обработает разный регистр и не найдет стоп-слово, если оно является частью другого слова.

// Предположим, в stop-words.php есть слово "art".

$text1 = "This is a piece of ART.";
$text2 = "This new smart speaker is amazing.";

$found1 = stopWords($text1); // Вернет ['ART']
$found2 = stopWords($text2); // Вернет [] (пустой массив), т.к. 'art' - часть слова 'smart'

if (!empty($found1)) {
    echo "В первом тексте найдено стоп-слово.";
}

if (empty($found2)) {
    echo "Во втором тексте стоп-слова не найдены, проверка пройдена.";
}

Примечания

Производительность: Функция оптимизирована для работы с большим количеством стоп-слов, так как она объединяет их в одно регулярное выражение вместо множества отдельных проверок.

Функция templateModules

Функция templateModules служит для динамического подключения наборов модулей (частей шаблона), основываясь на конфигурации, заданной в полях текущей страницы. Это позволяет гибко управлять структурой страницы, не изменяя основной код шаблона.

Ключевой особенностью является поддержка каскадной системы поиска: сначала модуль ищется в пользовательской директории (для переопределения), а затем — в стандартной.

Сигнатура

function templateModules(string $key): void

Аргументы

string $key: Ключ (идентификатор) для получения списка модулей из метаданных страницы с помощью функции getPageData(). Значение, связанное с этим ключом, должно быть строкой, в которой имена файлов модулей перечислены через запятую.

Результат

Функция ничего не возвращает (void). Результатом её работы является прямое включение (require) и выполнение кода из найденных файлов модулей.

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

Пример 1: Подключение одного модуля

Предположим, в полях страницы определен ключ для хедера:

header_file: default_header.php

Тогда в основном файле шаблона можно вызвать функцию так:

// В main-template.php
templateModules('header_file');

Функция найдет файл default_header.php в одной из директорий и подключит его.

Пример 2: Подключение нескольких модулей и демонстрация переопределения

Допустим, на странице блога нужно вывести несколько виджетов в сайдбаре. Конфигурация может выглядеть так:

// В полях страницы
sidebar_widgets: categories.php, custom_banner.php, tags_cloud.php

Вызов в шаблоне:

<aside class="sidebar">
    <?php templateModules('sidebar_widgets'); ?>
</aside>

Функция последовательно подключит три файла. При этом, если разработчик создал свою версию баннера и разместил её по пути SERVICE_DIR/my/modules/custom_banner.php, то будет подключена именно эта версия, а не стандартная из TEMPLATE_MODULES_DIR. Файлы categories.php и tags_cloud.php будут искаться по стандартному пути.

Примечания

Функция не генерирует ошибок, если файл не найден, она просто его проигнорирует.

Функция textsimple

Функция textsimple преобразует текст, написанный на языке разметки TextSimple, в HTML.

Полное описание: https://maxsite.org/albireo/introduction/textsimple

Сигнатура

function textsimple(string $text): string

Аргументы

string $text: Строка, содержащая текст в формате TextSimple.

Результат

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

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

Пример 1: Базовое преобразование

Преобразование основного синтаксиса TextSimple в HTML.

$textSimpleContent = <<<TEXTSIMPLE
# Главный заголовок

Это простой параграф с *курсивом* и **жирным** текстом.

- Элемент списка 1
- Элемент списка 2

[Это ссылка](https://example.com)
TEXTSIMPLE;

$htmlContent = textsimple($textSimpleContent);
echo $htmlContent;

Результатом будет корректный HTML-код с тегами <h1>, <p>, <em>, <strong>, <ul>, <li> и <a>.

Пример 2: Использование в Albireo CMS

В настройках страницы можно указать, что её содержимое нужно обрабатывать как TextSimple.

parser: textsimple

Функция widgets

Функция widgets является центральным механизмом для выполнения и отображения виджетов. Она считывает конфигурационный файл, определяет, какие виджеты нужно выполнить, находит их файлы (с поддержкой переопределения) и вызывает в каждом из них функцию run().

Сигнатура

function widgets(string $configFile = ''): array

Аргументы

string $configFile (необязательный)

Путь к файлу конфигурации виджетов. Логика определения файла следующая:

Если аргумент $configFile передан, используется он.
Если аргумент пуст, функция пытается получить имя файла из полей текущей страницы по ключу widgets-config (например, getPageData('widgets-config')).
Если и метаданные отсутствуют, используется файл по умолчанию: CONFIG_DIR/widgets.php.

Результат

Возвращает индексированный массив (array), где каждый элемент является результатом, возвращаемым функцией run() соответствующего виджета (обычно это строка с HTML-кодом). Если файл конфигурации не найден или не содержит активных виджетов, возвращается пустой массив.

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

Пример 1: Файл конфигурации `widgets.php`

Это основной файл, описывающий, какие виджеты и с какими параметрами нужно выполнить.

// Содержимое файла CONFIG_DIR/widgets.php
return [
    [
        'widget' => 'categories', // Имя каталога виджета. Обязательный параметр.
        'title'  => 'Рубрики блога',
    ],
    [
        'widget' => 'recent_posts',
        'title'  => 'Свежие записи',
        'limit'  => 5,
    ],
    [
        'widget' => 'promo_banner',
        'show'   => false, // Этот виджет не будет выполнен.
    ],
];

Пример 2: Структура файла виджета

Каждый виджет должен находиться в своей директории и иметь файл index.php со специальной структурой.

// Содержимое файла widgets/categories/index.php

namespace widgets\categories;

function run(array $params = []): string
{
    // $params содержит массив из файла конфигурации, в данном случае:
    // ['widget' => 'categories', 'title' => 'Рубрики блога']
    
    $title = $params['title'] ?? 'Категории';
    
    // Здесь логика получения и формирования списка категорий...
    $categoriesHtml = '<ul><li>Технологии</li><li>Путешествия</li></ul>';
    
    return '<div class="widget"><h3>' . htmlspecialchars($title) . '</h3>' . $categoriesHtml . '</div>';
}

Пример 3: Вызов и отображение виджетов в шаблоне

В основном файле шаблона можно вызвать функцию и вывести результат.

<aside class="sidebar">
    <?php
    // Выполняем все виджеты из конфигурации по умолчанию
    $widgetsOutput = widgets();

    // Выводим HTML-код каждого виджета
    foreach ($widgetsOutput as $widgetHtml) {
        echo $widgetHtml;
    }
    ?>
</aside>

Примечания

Механизм переопределения: Функция сначала ищет виджет в WIDGETS_DIR_SITE, и только если не находит, ищет в WIDGETS_DIR. Это позволяет пользователям создавать свои версии виджетов, не изменяя системные файлы.
Структура виджета: Каждый виджет должен иметь файл index.php, находиться в пространстве имен \widgets\[имя_каталога] и содержать публичную функцию run(array $params).