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

Функции данных Albireo CMS

getConfig getConfigFile getDB getKeysPageData getPageData getPages getPagination

Функция getConfig

Функция getConfig является централизованным способом получения конфигурационных параметров. Она реализует трехуровневую систему приоритетов, что обеспечивает высокую гибкость настройки:

  1. Переопределение на уровне страницы: Сначала функция проверяет, не был ли параметр переопределен в метаданных текущей страницы (через поле setConfig).
  2. Пользовательская конфигурация: Если переопределения нет, ищется значение в пользовательском файле CONFIG_DIR/config.php.
  3. Системная конфигурация: Если значение не найдено, ищется в системном файле SYS_DIR/config/config.php.

Конфигурационные файлы загружаются и объединяются только один раз за запрос для повышения производительности.

Сигнатура

function getConfig(string|null|bool $key, mixed $default = ''): mixed

Аргументы

string|null|bool $key
Ключ для получения значения. Если передать null, false или пустую строку, функция вернет весь объединенный массив конфигурации.
mixed $default (необязательный)
Значение по умолчанию, которое будет возвращено, если ключ не найден ни в одном из источников. По умолчанию — пустая строка ''.

Результат

Возвращает значение параметра (тип mixed) или значение по умолчанию. Если $key не указан, возвращает весь массив конфигурации (array).

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

Пример 1: Получение базовых настроек

Получение названия сайта и email администратора из конфигурационных файлов.

$siteTitle = getConfig('siteTitle', 'Сайт без названия');
$adminEmail = getConfig('adminEmail');

echo "<title>{$siteTitle}</title>";

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

Предположим, у нас есть следующая конфигурация:

// В SYS_DIR/config/config.php
return ['theme' => 'default', 'show_breadcrumbs' => true];

// В CONFIG_DIR/config.php (пользовательский)
return ['theme' => 'dark'];

// В поле текущей страницы:
setConfig[show_breadcrumbs]: false

Результаты вызова getConfig будут следующими:

$theme = getConfig('theme'); // 'dark' (пользовательский файл переопределил системный)
$breadcrumbs = getConfig('show_breadcrumbs'); // false (страница переопределила системный)
$someOption = getConfig('non_existent_option', 'fallback'); // 'fallback' (используется значение по умолчанию)

Пример 3: Получение всего массива конфигурации

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

$allSettings = getConfig(null);
// print_r($allSettings);

Примечания

  • Кеширование: Конфигурационные файлы загружаются и объединяются только один раз за сеанс выполнения скрипта благодаря использованию статической переменной $result.
  • Объединение массивов: Для слияния конфигураций используется array_replace_recursive(), что позволяет гибко переопределять даже вложенные ключи в многомерных массивах.

Функция getConfigFile

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

Сигнатура

function getConfigFile(string $file, ?string $key = null, mixed $default = '', bool $recursive = false): mixed

Аргументы

string $file
Полный путь к файлу конфигурации.
string|null $key (необязательный)
Если указан, функция вернет значение из загруженного массива по этому ключу. Если null (по умолчанию), будет возвращен весь массив.
mixed $default (необязательный)
Значение по умолчанию, которое будет возвращено, если указан $key, но он не найден в массиве.
bool $recursive (необязательный)

Определяет режим загрузки:

  • false (по умолчанию): Обычный режим. Функция пытается загрузить файл по пути $file. Если он не найден, она ищет файл с таким же именем в системной директории SYS_DIR/config/ и загружает его.
  • true: Рекурсивный режим. Функция загружает и системный, и пользовательский файлы, а затем рекурсивно объединяет их с помощью array_replace_recursive(). Это позволяет в пользовательском файле определять только те значения, которые нужно изменить, а остальные будут унаследованы из системного.

Результат

Возвращает значение типа mixed. Это может быть массив, значение по ключу или значение по умолчанию. Если файл не найден ни в одном из мест, возвращается пустой массив [].

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

Пример 1: Обычная загрузка файла

Загрузка файла с пользователями. Если users.php не существует в CONFIG_DIR, функция попытается загрузить его из SYS_DIR/config/.

$usersData = getConfigFile(CONFIG_DIR . 'users.php');

Пример 2: Получение конкретного значения

// Получаем хост базы данных из файла database.php, по умолчанию 'localhost'
$dbHost = getConfigFile(CONFIG_DIR . 'database.php', 'host', 'localhost');

Пример 3: Рекурсивное объединение конфигураций

Предположим, у нас есть системные и пользовательские настройки для виджетов.

// В SYS_DIR/config/widgets.php:
// return [
//     'recent_posts' => ['title' => 'Recent Posts', 'limit' => 5],
//     'categories' => ['title' => 'Categories', 'show_count' => true],
// ];

// В CONFIG_DIR/widgets.php (пользовательский):
// return [
//     'recent_posts' => ['title' => 'Свежие записи'], // переопределяем только заголовок
//     'tags_cloud' => ['title' => 'Облако тегов'], // добавляем новый виджет
// ];

// Загружаем с рекурсивным объединением
$widgetsConfig = getConfigFile(CONFIG_DIR . 'widgets.php', null, [], true);

// Итоговый $widgetsConfig будет:
// [
//     'recent_posts' => ['title' => 'Свежие записи', 'limit' => 5], // 'title' заменен, 'limit' остался
//     'categories' => ['title' => 'Categories', 'show_count' => true], // остался без изменений
//     'tags_cloud' => ['title' => 'Облако тегов'], // добавлен новый
// ]

Примечания

  • Кеширование: Файлы загружаются только один раз за запрос. Результаты кешируются в статической переменной, что предотвращает повторное чтение с диска.
  • Безопасность: Функция использует require, поэтому загружаемые файлы должны быть доверенными и возвращать массив.

Функция getDB

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

Сигнатура

function getDB(string $aliasDB, bool $exitEmpty = false, string $configFN = 'dbase.php'): ?\PDO

Аргументы

string $aliasDB
Псевдоним (алиас) базы данных, который используется как ключ в конфигурационном файле. Например, 'main', 'users', 'filesinfo'.
bool $exitEmpty (необязательный)
Если true, и подключение к базе данных не удалось, выполнение скрипта будет немедленно прервано с сообщением об ошибке. Используется для критически важных подключений. По умолчанию false.
string $configFN (необязательный)
Имя файла конфигурации, который находится в директории CONFIG_DIR. По умолчанию 'dbase.php'.

Результат

Возвращает:

  • Объект \PDO в случае успешного подключения.
  • null, если подключение не удалось и $exitEmpty установлен в false.
  • В случае, если $exitEmpty равен true и подключение не удалось, функция прерывает выполнение скрипта и ничего не возвращает.

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

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

Это самый частый сценарий. Функция ищет алиас 'main' в файле CONFIG_DIR/dbase.php.

$mainDatabase = getDB('main');

if ($mainDatabase) {
    // Выполняем запросы
    $stmt = $mainDatabase->query("SELECT * FROM pages LIMIT 10");
    // ...
} else {
    echo "Не удалось подключиться к основной базе данных.";
}

Функция getKeysPageData

Функция getKeysPageData является специализированным инструментом для извлечения и форматирования наборов ключ-значение из метаданных страницы. Она предназначена для работы с такими группами данных, как мета-теги (<meta>), Open Graph (og), Twitter Cards (twitter) и т.п., которые хранятся в специальном формате group[key] = value.

Сигнатура

function getKeysPageData(string $key = 'meta', string|bool $format = '<meta name="[key]" content="[val]">', array|false $pageData = false, bool $html = false): array

Аргументы

string $key (необязательный)
Имя группы ключей для поиска в метаданных. По умолчанию 'meta'.
string|bool $format (необязательный)

Определяет формат вывода:

  • Строка-шаблон (по умолчанию): Плейсхолдеры [key] и [val] будут заменены на имя и значение каждого элемента. Результатом будет массив отформатированных строк.
  • false (логическое): Функция вернет "сырые" данные в виде ассоциативного массива [key => value].
array|false $pageData (необязательный)
Массив с данными страницы для обработки. Если false (по умолчанию), функция автоматически получит данные текущей страницы через getVal('pageData').
bool $html (необязательный)
Если true, ключ и значение будут экранированы с помощью htmlspecialchars() перед подстановкой в формат. По умолчанию false.

Результат

Возвращает массив (array). Содержимое массива зависит от параметра $format:

  • Если $format — строка, массив будет содержать отформатированные HTML-строки.
  • Если $format — false, массив будет ассоциативным, содержащим пары ключ-значение.

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

Пример 1: Генерация стандартных мета-тегов

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

meta[description]: Описание моей замечательной страницы.
meta[keywords]: php, web, development
meta[author]: Иван Петров

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

$metaTags = getKeysPageData('meta', '<meta name="[key]" content="[val]">', false, true);
echo implode("\n", $metaTags);

Результат:

<meta name="description" content="Описание моей замечательной страницы.">
<meta name="keywords" content="php, web, development">
<meta name="author" content="Иван Петров">

Пример 2: Генерация Open Graph тегов с кастомным форматом

В полях страницы:

og[title]: Заголовок для соцсетей
og[type]: article
og[image]: https://example.com/image.jpg

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

$ogTags = getKeysPageData('og', '<meta property="og:[key]" content="[val]">', false, true);
echo implode("\n", $ogTags);

Результат:

<meta property="og:title" content="Заголовок для соцсетей">
<meta property="og:type" content="article">
<meta property="og:image" content="https://example.com/image.jpg">

Пример 3: Получение данных в виде массива

Это может быть полезно для дальнейшей обработки данных в PHP.

$twitterData = getKeysPageData('twitter', false);
// $twitterData может быть: ['card' => 'summary_large_image', 'site' => '@myusername']

if (!empty($twitterData['card'])) {
    // ... какая-то логика ...
}

Функция getPageData

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

Сигнатура

function getPageData(string $key = '', mixed $default = '', string $before = '', string $after = ''): mixed

Аргументы

string $key (необязательный)
Ключ для получения значения из данных страницы. Если передана пустая строка (по умолчанию), функция вернет весь массив данных страницы.
mixed $default (необязательный)
Значение, которое будет возвращено, если ключ $key не найден в данных страницы. По умолчанию — пустая строка ''.
string $before (необязательный)
Строка, которая будет добавлена в начало результата. Применяется только если значение найдено и является строкой.
string $after (необязательный)
Строка, которая будет добавлена в конец результата. Применяется только если значение найдено и является строкой.

Результат

Возвращает значение типа mixed. Это может быть значение из данных страницы, значение по умолчанию или, если $key не указан, весь массив данных страницы (array).

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

Пример 1: Получение основных метаданных в шаблоне

<!DOCTYPE html>
<html lang="ru">
<head>
    <title><?= getPageData('title', 'Сайт') ?></title>
    <meta name="description" content="<?= getPageData('description', 'Описание по умолчанию') ?>">
</head>
<body>
    <h1><?= getPageData('h1', getPageData('title')) ?></h1>
</body>
</html>

Пример 2: Использование префикса и суффикса

Это удобно для генерации HTML-атрибутов или обрамления данных.

// Предположим, в данных страницы есть 'css-class: special-page'
$classAttr = getPageData('css-class', '', 'class="', '"');
// $classAttr будет: 'class="special-page"'

// Если 'css-class' отсутствует, $classAttr будет пустой строкой,
// что предотвратит вывод пустого атрибута class="".
echo "<div {$classAttr}>...</div>";

Пример 3: Получение всего массива данных

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

$allPageData = getPageData();
// pr($allPageData);

Пример 4: Замена данных страницы

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

// Получаем текущие данные
$currentPageData = getPageData();

// Изменяем заголовок
$currentPageData['title'] = 'Новый динамический заголовок';

// Сохраняем измененные данные обратно в хранилище
setVal('pageData', $currentPageData);

// Теперь последующие вызовы getPageData('title') вернут новое значение.

Функция getPages

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

Сигнатура

function getPages(int $limit = 10, string $where = 'draft = 0 AND type = "blog"', ...): array

Аргументы

int $limit (необязательный)
Количество записей на страницу. Если 0, пагинация не применяется, и будут возвращены все найденные записи. По умолчанию 10.
string $where (необязательный)
SQL-условие для фильтрации записей, которое будет вставлено в секцию WHERE. Не нужно писать само слово WHERE. По умолчанию 'draft = 0 AND type = "blog"'.
string $order (необязательный)
SQL-условие для сортировки. По умолчанию 'date_unix DESC' (сначала новые).
array $bindValue (необязательный)
Ассоциативный массив для безопасной привязки значений к плейсхолдерам в условии $where. Например, [':type' => 'news'].
array $bindValueType (необязательный)
Массив для явного указания типов данных привязываемых значений (используется в PDO).
bool $sqlResult (необязательный)
Если true, функция вернет "сырые" данные из базы данных. Если false (по умолчанию), данные каждой записи будут обработаны функцией getFileInfo().
bool $delayed (необязательный)
Если true (по умолчанию), в SQL-запрос будет добавлено условие, которое отсеивает записи с отложенной датой публикации (date_pub_unix).

Результат

Возвращает ассоциативный массив (array) с двумя ключами:

  • 'pagination': Массив с данными для построения навигации по страницам (результат работы функции getPagination()).
  • 'files': Массив, содержащий данные найденных записей. По умолчанию каждый элемент этого массива — это результат работы getFileInfo().

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

Пример 1: Вывод последних 5 новостей

$news = getPages(
    limit: 5,
    where: 'type = :type',
    bindValue: [':type' => 'news']
);

// Теперь можно передать данные в шаблон для отображения
echo tpl(data: $news['files'], tpl: 'template.php');
echo tpl(data: $news['pagination'], tpl: 'pagination.php');

Пример 2: Получение "сырых" данных для кастомной обработки

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

$rawPages = getPages(
    where: 'custom_field = 1',
    sqlResult: true // включаем режим "сырых" данных
);

foreach ($rawPages['files'] as $row) {
    // $row - это ассоциативный массив со всеми столбцами из таблицы file_info
    // echo $row['file_path']; 
}

Функция getPagination

Функция getPagination является компонентом для реализации постраничной навигации текущего URL. Она выполняет все необходимые расчеты и возвращает структурированный массив данных, который можно легко использовать для отрисовки ссылок "Вперед", "Назад", номеров страниц и т.д.

Сигнатура

function getPagination(int $limit, int $count): array

Аргументы

int $limit
Количество записей, отображаемых на одной странице.
int $count
Общее количество записей, которые нужно разбить на страницы.

Результат

Возвращает ассоциативный массив (array) со следующими ключами:

records (int)
Общее количество записей.
limit (int)
Количество записей на странице.
max (int)
Общее количество страниц пагинации.
current (int)
Номер текущей страницы.
prev (int)
Номер предыдущей страницы (0, если её нет).
prevLink (string)
URL-адрес предыдущей страницы (пустая строка, если её нет).
next (int)
Номер следующей страницы (0, если её нет).
nextLink (string)
URL-адрес следующей страницы (пустая строка, если её нет).
offset (int)
Смещение для SQL-запроса (LIMIT ... OFFSET ...).
outRange (bool)
Флаг, указывающий, был ли запрошенный номер страницы за пределами допустимого диапазона.
urlFull (string)
Базовый URL текущей страницы без GET-параметров.
pagLinks (array)
Ассоциативный массив, содержащий все ссылки на страницы пагинации. Ключ 'current' хранит номер текущей страницы, остальные ключи — URL-адреса, а значения — номера страниц.

Примечания

  • URL-адреса: Функция формирует ссылки, добавляя GET-параметр ?page=... к базовому URL. Для первой страницы параметр page не добавляется.