Функции рубрик Albireo CMS

categoryGetAll categoryGetPages categoryLinks categoryList categoryPagesPrompts_handler categoryTitleTriggers

Функция categoryGetAll

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

Сигнатура

function categoryGetAll(): array

Аргументы

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

Результат

Возвращает индексированный массив (array), отсортированный согласно параметру order из файла конфигурации. Каждый элемент этого массива — это ассоциативный массив, описывающий одну рубрику. Структура этого внутреннего массива определяется функцией categoryList().

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

1. Файл конфигурации `CONFIG_DIR/category.php`

В этом файле задаются "человеческие" имена для рубрик и их порядок.

return [
    'astronomy' => [ // site/category
        'title' => 'Астрономия',
        'caption' => 'Астрономия',
        'description' => 'Статьи по астрономии',
        'text-start' => '<div class="h2 mar20-tb">Астрономия</div>',
        'text-end' => '<hr>Текст в конце рубрики',
        'order' => 10,
        'order-pages' => 'date-desc',
        'limit' => 4,
        'path' => '',
        'my-url' => 'astronomy',
    ],

    // Рубрика 'misc' не описана, её имя будет взято из слага.
];

2. Вывод списка рубрик в сайдбаре

Это основной сценарий использования функции.

$categories = categoryGetAll();

if ($categories) {
    echo '<div class="widget categories-widget">';
    echo '<h3>Рубрики</h3>';
    echo '<ul>';

    foreach ($categories as $category) {
        echo '<li>';
        echo '<a href="' . $category['url'] . '">' . htmlspecialchars($category['title']) . '</a>';
        echo ' (' . $category['count'] . ')';
        echo '</li>';
    }

    echo '</ul></div>';
}

Примечания

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

Функция categoryGetPages

Обеспечивает удобное получение записей типа «blog» из базы данных, фильтруя их по принадлежности к одной или нескольким рубрикам, хранящимся в формате JSON.

Сигнатура

function categoryGetPages(
    string|array $category, 
    int $limit = 10, 
    string $order = 'date_unix DESC', 
    bool $sqlResult = false, 
    string $where = ''
): array

Аргументы

string|array $category: Рубрика или массив рубрик. Записи, содержащие хотя бы одну из них, попадут в выборку.
int $limit: Максимальное количество записей (пагинация).
string $order: SQL-строка для сортировки результатов (например, 'date_unix DESC').
bool $sqlResult: Флаг формата вывода, передаваемый в getPages().
string $where: Дополнительное SQL-условие для расширения фильтрации.

Результат

Возвращает массив записей (или объект запроса, если $sqlResult равен true), отфильтрованный по типу 'blog' и статусу draft = 0.

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

// Поиск по нескольким категориям с дополнительным фильтром
$posts = categoryGetPages(
    category: ['news', 'tech'],
    limit: 20,
    where: 'AND views > 100'
);

Примечания

Функция ожидает, что поле category в таблице является валидным JSON-массивом.
Используется COLLATE NOCASE, поэтому поиск регистронезависим (работает корректно для латиницы).

Функция categoryLinks

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

Сигнатура

function categoryLinks(string|array $cats, string $delimer = ', '): string

Аргументы

string $cats: Строка, содержащая один или несколько слагов рубрик, разделенных запятыми или готовый массив рубрик.
string $delimer (необязательный): Строка-разделитель, которая будет вставляться между сгенерированными HTML-ссылками. По умолчанию используется запятая с пробелом (', ').

Результат

Возвращает строку (string) с HTML-кодом, содержащим ссылки на страницы рубрик. Если исходная строка $cats пуста или не содержит ни одного существующего слага, возвращается пустая строка.

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

Пример 1: Отображение рубрик для поста в блоге

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

// Предположим, в полях поста есть поле:
// category: php-news, tutorials

// Получаем это значение
$postCategories = getPageData('category'); // 'php-news, tutorials'

// Генерируем и выводим HTML-ссылки
if ($postCategories) {
    echo '<div class="post-categories">';
    echo 'Рубрики: ' . categoryLinks($postCategories);
    echo '</div>';
}

// Результат:
// <div class="post-categories">
// Рубрики: <a href=".../category/php-news">Новости PHP</a>, <a href=".../category/tutorials">Уроки и статьи</a>
// </div>

Пример 2: Использование другого разделителя

Можно легко изменить внешний вид списка, поменяв разделитель.

$cats = 'design,frontend';
$links = categoryLinks($cats, ' / ');

// $links будет:
// <a href=".../category/design">Дизайн</a> / <a href=".../category/frontend">Фронтенд</a>
echo $links;

Примечания

Производительность: Функция categoryGetAll(), вызываемая внутри, кеширует свой результат, поэтому многократные вызовы categoryLinks в рамках одного запроса не приведут к повторным обращениям к базе данных.
Готовые ссылки: Функция использует уже готовую HTML-ссылку из поля 'link', которое формируется в categoryGetAll/categoryList.

Функция categoryList

Функция categoryList является вспомогательным инструментом, который "обогащает" простой список слагов рубрик полной информацией. Она объединяет данные из трех источников: списка слагов, файла конфигурации и массива со счетчиками записей. Для каждой рубрики функция генерирует недостающие поля (такие как URL, title, description), что позволяет получить на выходе унифицированный и полный набор данных для каждой категории.

Сигнатура

function categoryList(array $cats, array $catConfig, array $catsCount = []): array

Аргументы

array $cats: Индексированный массив, содержащий слаги (идентификаторы) рубрик, которые необходимо обработать. Например, ['php-news', 'tutorials'].
array $catConfig: Ассоциативный массив с конфигурацией рубрик, загруженный из файла (например, category.php). Ключами в этом массиве должны быть слаги рубрик.
array $catsCount (необязательный): Ассоциативный массив, где ключ — это слаг рубрики, а значение — количество записей в ней. Например, ['php-news' => 25, 'tutorials' => 40].

Результат

Возвращает отсортированный по иерархии (полю path) массив, где каждый элемент — это ассоциативный массив с полными данными одной рубрики. Типичная структура элемента:

slug: Идентификатор рубрики.
url: Полный URL-адрес страницы архива.
count: Количество записей.
title: Заголовок рубрики (из конфига или сгенерированный из слага).
caption: Подпись (аналогично title).
description: Описание.
text-start / text-end: Текстовые блоки для вывода до и после списка записей.
path: Иерархический путь (например, 'web.php.frameworks').
pathLevel: Уровень вложенности (количество точек в 'path').
link: Готовый HTML-тег <a>.
... а также любые другие поля из файла конфигурации.

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

Обычно эта функция вызывается внутри других, более высокоуровневых функций, таких как categoryGetAll(). Прямой вызов может выглядеть так:

// 1. Исходные данные
$activeSlugs = ['php', 'js', 'css'];

$configuration = [
    'php' => ['title' => 'Статьи о PHP', 'path' => 'backend.php'],
    'js'  => ['title' => 'Статьи о JavaScript', 'path' => 'frontend.js'],
    'css' => ['title' => 'CSS-трюки', 'path' => 'frontend.css', 'my-url' => 'all-about-css'],
];

$postCounts = [
    'php' => 50,
    'js'  => 75,
    'css' => 30,
];

// 2. Вызов функции
$fullCategoryData = categoryList($activeSlugs, $configuration, $postCounts);

// 3. Результат (упрощенно)
// $fullCategoryData будет содержать массив из 3-х элементов. Например, для 'css':
// [
//    'slug' => 'css',
//    'title' => 'CSS-трюки',
//    'path' => 'frontend.css',
//    'my-url' => 'all-about-css',
//    'url' => 'https://mysite.com/all-about-css', // сгенерирован из 'my-url'
//    'count' => 30,
//    'pathLevel' => 1,
//    'link' => '<a href="https://mysite.com/all-about-css">CSS-трюки</a>',
//    ...
// ]
print_r($fullCategoryData['css']);

Примечания

Генерация полей: Если какие-то ключевые поля (title, caption, description) не заданы в конфигурации, функция сгенерирует их на основе слага или оставит пустыми, обеспечивая унифицированную структуру для всех рубрик.
URL-адреса: Функция поддерживает кастомные URL через поле my-url в конфигурации. Если его нет, URL генерируется по стандартному шаблону SITE_URL/category/[slug].

Функция categoryPagesPrompts_handler

Предназначена для подготовки контекста (промптов) для больших языковых моделей (LLM). Функция агрегирует метаданные рубрики и список её записей, форматируя их в удобочитаемый для ИИ текстовый блок.

Сигнатура

function categoryPagesPrompts_handler(
    string $cat, 
    string $before = '', 
    int $limit = 100, 
    string $order = 'ASC'
): void

Аргументы

string $cat: Код рубрики, данные о которой нужно извлечь из category.php.
string $before: Текст, предваряющий вывод. Если передан, выводится до основного блока.
int $limit: Количество записей для выборки.
string $order: Направление сортировки: 'ASC' (по возрастанию) или 'DESC' (по убыванию даты).

Результат

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

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

// Вывод записей рубрики 'ai' для последующей обработки ChatGPT
categoryPagesPrompts_handler('ai', 'Ниже приведены статьи для анализа:', 10, 'DESC');

Примечания

Функция предназначена для использования через AJAX-запрос, но может использоваться напрямую, поскольку не вносит никаких изменений и не содержит критических данных.
Функция ожидает наличие файла конфигурации рубрик по пути CONFIG_DIR . 'category.php'.

Функция categoryTitleTriggers

Функция categoryTitleTriggers — это специализированная функция-триггер, предназначенная для динамического изменения мета-тегов title и description на страницах архивов рубрик. Она определяет текущую рубрику из URL, находит для неё данные в конфигурационном файле category.php и обновляет метаданные страницы. Если конфигурация для рубрики не найдена, она генерирует заголовок и описание по умолчанию.

Сигнатура

function categoryTitleTriggers(array $pageData): void

Аргументы

array $pageData: Массив с текущими данными страницы. Этот аргумент передается автоматически системой триггеров перед рендерингом страницы.

Результат

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

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

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

Активация триггера

Чтобы функция сработала для страницы архива рубрик (например, для файла pages/specific/category.php):

triggers[]: categoryTitleTriggers

Примечания

Назначение: Это узкоспециализированная функция, предназначенная для работы в рамках системы триггеров и страниц архивов рубрик.

Функции рубрик Albireo CMS

Функция categoryGetAll

Сигнатура

Аргументы

Результат

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

1. Файл конфигурации CONFIG_DIR/category.php

2. Вывод списка рубрик в сайдбаре

Примечания

Функция categoryGetPages

Сигнатура

Аргументы

Результат

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

Примечания

Функция categoryLinks

Сигнатура

Аргументы

Результат

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

Пример 1: Отображение рубрик для поста в блоге

Пример 2: Использование другого разделителя

Примечания

Функция categoryList

Сигнатура

Аргументы

Результат

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

Примечания

Функция categoryPagesPrompts_handler

Сигнатура

Аргументы

Результат

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

Примечания

Функция categoryTitleTriggers

Сигнатура

Аргументы

Результат

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

Активация триггера

Примечания

1. Файл конфигурации `CONFIG_DIR/category.php`