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

Функции массивов Albireo CMS

arrayCondition arrayFindPrevNext arrayFormat arrayNatSort arrayPagination arrayReplaceKeys arraySearchKeys arraySortKeys arrayToStrHTML arrayValidate checkArrVal choiceKey searchInArray sortArray

Функция arrayСondition

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

Сигнатура

function arrayСondition(array $array, string $delimiter = ' '): string

Аргументы

array $array
Массив где:
  • Элементы с числовыми ключами добавляются всегда
  • Элементы со строковыми ключами добавляются только если значение === true
string $delimiter
Разделитель между элементами (по умолчанию пробел)

Возвращаемое значение

Строка с объединенными элементами согласно условиям.

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

// Генерация классов
$classes = [
    'btn',
    'btn-primary' => $isPrimary,
    'btn-large' => $isLarge,
    'disabled' => $isDisabled
];
echo 'class="' . arrayСondition($classes) . '"';

// Генерация стилей
$styles = [
    'color: red' => $isError,
    'font-weight: bold' => true,
    'display: none' => $isHidden
];
echo 'style="'.arrayСondition($styles, '; ').'"';

// Простой список
$items = ['one', 'two' => false, 'three' => true];
echo arrayСondition($items, ', '); // 'one, three'

При использовании в tpl-шаблонизаторе:

class="{{ arrayСondition(['t-bold' => $loopOdd, 't-red' => true]) }}"

style="{{ arrayСondition(['margin: 20px' => $loopOdd, 'padding: 10px' => true], ';') }}"

Примечания

  • Для числовых ключей всегда использует значение
  • Для строковых ключей использует ключ только если значение === true
  • Идеально подходит для:
    • Динамических классов CSS
    • Условных inline-стилей
    • Формирования строк с условиями
    • Безопасно обрабатывает все типы данных
    • Оптимизированная реализация через implode()

Функция arrayFindPrevNext

Находит предыдущий и следующий элементы в массиве относительно указанного значения.

Сигнатура

function arrayFindPrevNext(array $array, mixed $value, string $findKey): array

Аргументы

array $array
Исходный массив с числовой индексацией (0,1,2...), в котором производится поиск
mixed $value
Значение для поиска в указанном ключе элементов массива
string $findKey
Ключ в элементах массива, в котором нужно искать указанное значение

Результат

Возвращает ассоциативный массив с двумя элементами:

  • prev - предыдущий элемент или пустой массив, если текущий элемент первый
  • next - следующий элемент или пустой массив, если текущий элемент последний

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

// Навигация между статьями
$articles = [
    ['id' => 101, 'title' => 'Article 1'],
    ['id' => 102, 'title' => 'Article 2'],
    ['id' => 103, 'title' => 'Article 3']
];

$nav = arrayFindPrevNext($articles, 102, 'id');
// $nav содержит:
// [
//    'prev' => ['id' => 101, 'title' => 'Article 1'],
//    'next' => ['id' => 103, 'title' => 'Article 3']
// ]

// Пример с отсутствующим значением
$nav = arrayFindPrevNext($articles, 999, 'id');
// Возвращает: ['prev' => [], 'next' => []]

Примечания

  • Массив должен иметь последовательную числовую индексацию (0,1,2...)
  • Сравнение значений выполняется строго (===)
  • Если значение не найдено, возвращаются пустые массивы для prev и next
  • Функция прекращает поиск после первого совпадения

Функция arrayFormat

Преобразует массив ассоциативных массивов в строку по заданному шаблону.

Сигнатура

function arrayFormat(array $array, string $format = '<a class="%icon%" href="%url%">%name%</a>', string $before = '', string $after = ''): string

Аргументы

array $array
Массив элементов, где каждый элемент - ассоциативный массив с данными
string $format
Шаблон строки с плейсхолдерами в формате %ключ%. По умолчанию: '<a class="%icon%" href="%url%">%name%</a>'
string $before
Текст, добавляемый перед объединенным результатом (по умолчанию пустая строка)
string $after
Текст, добавляемый после объединенного результата (по умолчанию пустая строка)

Результат

Возвращает строку, состоящую из:

  1. Содержимого $before
  2. Всех элементов массива, отформатированных по шаблону
  3. Содержимого $after

Если массив пуст, возвращает пустую строку.

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

// Форматирование навигационного меню
$menuItems = [
    ['title' => 'Home', 'link' => '/', '_before' => '<li>', '_after' => '</li>'],
    ['title' => 'Products', 'link' => '/products', '_before' => '<li>', '_after' => '</li>']
];
echo arrayFormat($menuItems, '<a href="%link%">%title%</a>', '<ul>', '</ul>');
// Вывод: <ul><li><a href="/">Home</a></li><li><a href="/products">Products</a></li></ul>

// Форматирование карточек товаров
$products = [
    ['name' => 'Product 1', 'price' => '10.99', 'sku' => 'P001'],
    ['name' => 'Product 2', 'price' => '15.99', 'sku' => 'P002']
];
echo arrayFormat($products, '<div class="product"><h3>%name%</h3><p>Price: %price%</p></div>');

Примечания

  • Специальные ключи _before и _after добавляют текст вокруг каждого элемента
  • Плейсхолдеры в формате %ключ% заменяются на соответствующие значения
  • Если ключ не найден в элементе, плейсхолдер остается без изменений
  • Функция эффективна для генерации HTML-кода из данных массива

Функция arrayNatSort

Рекурсивно сортирует массив с сохранением ключей, используя натуральную сортировку.

Сигнатура

function arrayNatSort(array &$array): void

Аргументы

array &$array
Ссылка на массив для сортировки. Массив сортируется in-place (изменяется переданный массив).

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

// Сортировка файловой структуры
$filesystem = [
    'docs' => ['chapter2.md' => '', 'chapter1.md' => ''],
    'images' => [],
    'README.md' => ''
];
arrayNatSort($filesystem);
// Результат:
// [
//     'README.md' => '',
//     'docs' => ['chapter1.md' => '', 'chapter2.md' => ''],
//     'images' => []
// ]

// Сортировка сложной структуры
$data = [
    'Zebra' => 1,
    'apple' => 2,
    'Banana' => ['yellow' => 1, 'Green' => 2],
    '123' => 3,
    '45' => 4
];
arrayNatSort($data);
// Результат:
// [
//     '45' => 4,
//     '123' => 3,
//     'apple' => 2,
//     'Banana' => ['Green' => 2, 'yellow' => 1],
//     'Zebra' => 1
// ]

Примечания

  • Функция изменяет исходный массив (работает по ссылке)
  • Натуральная сортировка учитывает числовые значения в строках
  • Сортировка регистронезависимая (используется strnatcasecmp)
  • Подходит для сортировки файловых структур, меню, древовидных данных
  • Для простых массивов без вложенности можно использовать natcasesort()

Функция arrayPagination

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

Сигнатура

function arrayPagination(array $array, int $limit): array

Аргументы

array $array
Исходный массив данных для разбиения на страницы
int $limit
Количество элементов на одной странице (должно быть ≥1)

Возвращаемое значение

Ассоциативный массив со следующими ключами:

  • records - общее количество элементов
  • limit - элементов на страницу
  • max - всего страниц
  • current - текущая страница
  • prev/next - номера предыдущей/следующей страницы (0 если нет)
  • prevLink/nextLink - URL для навигации
  • offset - смещение для текущей страницы
  • outRange - флаг выхода запрошенной страницы за пределы
  • urlFull - базовый URL без параметров пагинации
  • pagLinks - массив ссылок для отображения пагинации
  • files - элементы для текущей страницы

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

// Пример с массивом данных
$products = [...]; // массив товаров
$perPage = 12;
$pageData = arrayPagination($products, $perPage);

// Использование в шаблоне
foreach ($pageData['files'] as $product) {
    // вывод товара
}

// Вывод пагинации
if ($pageData['max'] > 1) {
    echo '<div class="pagination">';
    if ($pageData['prev']) {
        echo '<a href="'.$pageData['prevLink'].'">Предыдущая</a>';
    }
    // ... вывод номеров страниц
    if ($pageData['next']) {
        echo '<a href="'.$pageData['nextLink'].'">Следующая</a>';
    }
    echo '</div>';
}

Функция arrayReplaceKeys

Рекурсивно заменяет подстроки в ключах многомерного массива аналогично str_replace().

Сигнатура

function arrayReplaceKeys(array $array, string|array $search, string|array $replace): array

Аргументы

array $array
Исходный массив для обработки. Может быть многомерным.
string|array $search
Искомая подстрока или массив подстрок для поиска в ключах
string|array $replace
Строка или массив замены (аналогично параметру replace в str_replace)

Возвращаемое значение

Новый массив с обновленными ключами, сохраняющий исходную структуру и значения.

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

// Простая замена подстроки в ключах
$data = ['user_name' => 'John', 'user_age' => 30];
$result = arrayReplaceKeys($data, 'user_', '');
// Результат: ['name' => 'John', 'age' => 30]

// Множественная замена
$data = ['tmp_file' => 'a.txt', 'tmp_dir' => '/path'];
$result = arrayReplaceKeys($data, ['tmp_', 'file'], ['', 'document']);
// Результат: ['document' => 'a.txt', 'tmp_dir' => '/path']

// Рекурсивная обработка
$data = [
    'old_key' => 'value',
    'nested' => [
        'old_key' => 'nested_value',
        'other' => 123
    ]
];
$result = arrayReplaceKeys($data, 'old_', 'new_');
// Результат: [
//     'new_key' => 'value',
//     'nested' => [
//         'new_key' => 'nested_value',
//         'other' => 123
//     ]
// ]

Функция arraySearchKeys

Ищет в массиве все элементы, у которых указанный ключ имеет заданное значение, и возвращает их ключи.

Сигнатура

function arraySearchKeys(array $array, mixed $key, mixed $value): array

Аргументы

array $array
Многомерный ассоциативный массив, в котором производится поиск. Может быть как числовым, так и ассоциативным массивом верхнего уровня.
mixed $key
Ключ в элементах массива, по которому осуществляется поиск. Может быть строкой (для ассоциативных массивов) или integer (для числовых индексов).
mixed $value
Значение для сравнения. Сравнение выполняется строго (оператор ===).

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

$data = [
    'first' => ['role' => 'admin', 'name' => 'Alice'],
    'second' => ['role' => 'user', 'name' => 'Bob'],
    'third' => ['role' => 'admin', 'name' => 'Charlie']
];

// Поиск всех администраторов
$admins = arraySearchKeys($data, 'role', 'admin'); // ['first', 'third']

// Поиск по несуществующему ключу
$empty = arraySearchKeys($data, 'status', 'active'); // []

Функция arraySortKeys

Сортирует ассоциативный массив по указанному порядку ключей.

Сигнатура

function arraySortKeys(array $array, array $sortKeys): array

Аргументы

array $array
Исходный ассоциативный массив для сортировки
array $sortKeys
Массив ключей в порядке, в котором они должны появиться в результате

Возвращаемое значение

Новый массив с элементами, упорядоченными согласно списку ключей.

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

// Простая сортировка ключей
$data = ['z' => 1, 'x' => 2, 'y' => 3];
$result = arraySortKeys($data, ['x', 'y', 'z']);
// Результат: ['x' => 2, 'y' => 3, 'z' => 1]

// Сортировка с неполным списком ключей
$data = ['title' => 'Test', 'date' => '2023-01-01', 'author' => 'John'];
$result = arraySortKeys($data, ['date', 'title']);
// Результат: ['date' => '2023-01-01', 'title' => 'Test', 'author' => 'John']

// Работа с вложенными структурами
$error = [
    'message' => 'Error',
    'code' => 500,
    'details' => ['file' => 'app.php', 'line' => 10]
];
$result = arraySortKeys($error, ['code', 'message', 'details']);
// Сохраняет структуру, меняет только порядок ключей верхнего уровня

Примечания

  • Сохраняет все элементы исходного массива
  • Ключи, не указанные в $sortKeys, остаются в исходном порядке в конце массива
  • Если ключ из $sortKeys отсутствует в массиве, он игнорируется
  • Не изменяет порядок элементов вложенных массивов
  • Полезен для:
    • Унификации порядка ключей в API ответах
    • Подготовки данных для вывода
    • Стандартизации структуры массивов

Функция arrayToStrHTML

Преобразует массив в HTML-строку с автоматическим экранированием спецсимволов.

Сигнатура

function arrayToStrHTML(
    array $array, 
    string $start = '<ul>', 
    string $end = '</ul>', 
    string $before = '<li>', 
    string $after = '</li>'
): string

Аргументы

array $array
Одномерный массив значений для преобразования
string $start
HTML-обертка начала списка (по умолчанию <ul>)
string $end
HTML-обертка конца списка (по умолчанию </ul>)
string $before
Текст/теги перед каждым элементом (по умолчанию <li>)
string $after
Текст/теги после каждого элемента (по умолчанию </li>)

Возвращаемое значение

Строка HTML с экранированными значениями массива в указанной структуре.

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

// Базовый пример списка
$fruits = ['Apple', 'Banana', 'Orange'];
echo arrayToStrHTML($fruits);
// <ul><li>Apple</li><li>Banana</li><li>Orange</li></ul>

// Кастомная обертка
$menuItems = ['Home', 'Products', 'Contacts'];
echo arrayToStrHTML($menuItems, '<div class="menu"><ul>', '</ul></div>', '<li class="item">', '</li>');

// Обработка пользовательского ввода
$comments = ['Hello!', '<script>alert(1)</script>', 'Good >> bad'];
echo arrayToStrHTML($comments);
// Спецсимволы будут корректно экранированы

Примечания

  • Автоматически экранирует спецсимволы через htmlspecialchars()
  • Работает только с одномерными массивами
  • Идеально подходит для:
    • Генерации HTML-меню
    • Вывода списков
    • Обработки пользовательского ввода
    • Создания структурированных данных

Функция arrayValidate

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

См. Работа с формами в Albireo CMS.

Примеры см. в pages/spacific/demo.

Сигнатура

function arrayValidate(array $array, array $rules): array

Аргументы

array $array
Ассоциативный массив с данными для проверки, например, $_POST.
array $rules
Массив, описывающий правила валидации. Ключи этого массива должны соответствовать ключам в $array. Значение для каждого ключа — это ассоциативный массив правил, где ключ — имя правила, а значение — его параметры.

Результат

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

  • 'data': Исходный массив $array, который может быть модифицирован (например, добавлены значения по умолчанию или применены функции очистки вроде trim).
  • 'errors': Массив строк, содержащий все сообщения об ошибках, сгенерированные в процессе валидации. Если ошибок нет, массив будет пустым.

Список правил валидации

default
Устанавливает значение по умолчанию, если поле отсутствует в исходных данных.
required
Поле не может быть пустым.
email
Проверяет, является ли значение корректным email-адресом.
url
Проверяет, является ли значение корректным и безопасным URL-адресом.
min_length / max_length
Проверяет минимальную/максимальную длину строки.
in_list
Проверяет, входит ли значение в указанный список допустимых значений.
start_with
Проверяет, начинается ли строка с указанной подстроки.
equals
Проверяет, равно ли значение указанному.
ip
Проверяет, является ли значение корректным IP-адресом.
numeric / numeric_int
Проверяет, является ли значение числом / целым числом.
numeric_positive / numeric_negative
Проверяет, является ли число положительным (>= 0) / отрицательным (< 0).
numeric_min / numeric_max
Проверяет, находится ли число в допустимом диапазоне.
date
Проверяет, соответствует ли строка формату даты 'Y-m-d'. Если строка пустая, то она не проверяется.
time
Проверяет, соответствует ли строка формату времени 'H:i'. Если строка пустая, то она не проверяется.
datetime_sql
Проверяет, соответствует ли строка формату времени 'Y-m-d H:i:s'. Если строка пустая, то она не проверяется.
chars_forbidden
Проверяет на отсутствие запрещенных символов.
chars_allow
Проверяет, что строка состоит только из разрешенных символов.
chars_normal
Проверяет, что строка состоит из букв, цифр и опционально разрешенных символов.
base64
Проверяет, является ли строка валидной Base64-строкой.
stop_words
Проверяет на наличие стоп-слов.

Правила предобработки

val_trim
Применяет trim() к значению перед валидацией.
val_strip_tags
Применяет strip_tags() к значению перед валидацией.

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

Пример: Валидация формы регистрации

$formData = [
    'login' => ' user123 ',
    'email' => 'invalid-email',
    'password' => '123',
    'password_confirm' => '1234',
    'agreement' => null,
    'user_type' => 'guest',
];

$rules = [
    'login' => [
        'val_trim' => true,
        'required' => true,
        'min_length' => 4,
        'chars_normal' => '', // разрешены только буквы и цифры
    ],
    'email' => [
        'required' => ['error' => 'Поле Email обязательно для заполнения.'],
        'email' => ['error' => 'Пожалуйста, введите корректный Email.'],
    ],
    'password' => [
        'required' => true,
        'min_length' => ['options' => 6, 'error' => 'Пароль должен быть не менее 6 символов.'],
    ],
    'password_confirm' => [
        'required' => true,
        'equals' => ['options' => $formData['password'], 'error' => 'Пароли не совпадают.'],
    ],
    'agreement' => [
        'required' => ['error' => 'Вы должны принять условия соглашения.'],
    ],
    'user_type' => [
        'default' => 'user',
        'in_list' => ['options' => ['user', 'moderator', 'admin']],
    ],
];

$validationResult = arrayValidate($formData, $rules);

if ($validationResult['errors']) {
    // Если есть ошибки, выводим их
    echo '<ul>';
    foreach ($validationResult['errors'] as $error) {
        echo '<li>' . htmlspecialchars($error) . '</li>';
    }
    echo '<ul>';
} else {
    // Ошибок нет, можно работать с очищенными данными
    echo 'Валидация прошла успешно!';
    // print_r($validationResult['data']);
}

Примечания

  • Кастомные сообщения об ошибках: Для каждого правила можно задать собственное сообщение об ошибке через ключ 'error'.

Функция checkArrVal

Проверяет значение элемента массива с особыми условиями, удобна для работы с флагами и настройками.

Сигнатура

function checkArrVal(array $array, string $key, bool $default = false): bool

Аргументы

array $array
Массив для проверки значений
string $key
Ключ элемента массива для проверки
bool $default
Значение по умолчанию, если ключ отсутствует (по умолчанию false)

Возвращаемое значение

Результат проверки согласно правилам:

  • false - если ключ отсутствует (возвращается $default)
  • false - если значение равно 0, '0', '-' или 'false'
  • true - во всех остальных случаях

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

// Проверка настроек
$config = [
    'debug' => 1,
    'caching' => 'false',
    'logging' => '-'
];

$isDebug = checkArrVal($config, 'debug'); // true
$isCaching = checkArrVal($config, 'caching'); // false
$isLogging = checkArrVal($config, 'logging'); // false
$isFeature = checkArrVal($config, 'new_feature', true); // true (значение по умолчанию)

// Использование в условиях
if (checkArrVal($options, 'expand_menu')) {
    // Показывать расширенное меню
}

Примечания

  • Использует функцию checkStr() для проверки значений
  • Чувствителен к регистру при проверке строк 'false'
  • Не изменяет исходный массив
  • Полезен для:
    • Проверки флагов в конфигурациях
    • Обработки параметров запросов
    • Работы с настройками пользователей

Функция choiceKey

Выбирает первое существующее значение из массива по переданным ключам.

Сигнатура

function choiceKey(array $array, mixed ...$keys): mixed

Аргументы

array $array
Ассоциативный массив, в котором производится поиск значений
mixed ...$keys
Перечень ключей для проверки (один или несколько). Ключи проверяются в порядке передачи.

Результат

Возвращает значение первого найденного ключа (тип mixed) или null, если ни один из ключей не существует в массиве.

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

// Пример с приоритетом ключей
$page = ['meta_title' => 'О компании', 'title' => 'Компания'];
$title = choiceKey($page, 'meta_title', 'title', 'slug') ?? 'Без названия'; // 'О компании'

// Пример с настройками
$settings = ['color' => 'blue'];
$theme = choiceKey($settings, 'theme', 'color'); // 'blue'

// Пример с обработкой отсутствия ключей
$data = ['id' => 123];
$value = choiceKey($data, 'name', 'email'); // null

Примечания

  • Ключи проверяются в порядке их передачи в функцию
  • Для установки значения по умолчанию рекомендуется использовать оператор ??
  • Функция не рекурсивна - работает только с массивом верхнего уровня

Функция searchInArray

Фильтрует многомерный массив по наличию ключа и/или его значению.

Сигнатура

function searchInArray(array $array, string $key, mixed $value = null): array

Аргументы

array $array
Многомерный ассоциативный массив для поиска
string $key
Ключ, по которому осуществляется поиск
mixed $value
Значение для сравнения:
  • null - проверяется только наличие ключа
  • любое другое значение - строгое сравнение (===)

Возвращаемое значение

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

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

// Данные для примеров
$users = [
    ['id' => 1, 'name' => 'John', 'role' => 'admin'],
    ['id' => 2, 'name' => 'Jane'],
    ['id' => 3, 'name' => 'Bob', 'role' => 'user']
];

// Поиск всех пользователей с ролью
$withRole = searchInArray($users, 'role');
// Результат: элементы John и Bob

// Поиск администраторов
$admins = searchInArray($users, 'role', 'admin');
// Результат: только John

// Поиск несуществующего значения
$empty = searchInArray($users, 'role', 'guest');
// Результат: пустой массив

Примечания

  • Использует строгое сравнение (===) при указании значения
  • Сохраняет оригинальные ключи массива
  • Не рекурсивна - проверяет только первый уровень вложенности
  • Эффективна для:
    • Фильтрации конфигураций
    • Поиска элементов по флагам
    • Выборки данных по категориям/типам

Функция sortArray

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

Сигнатура

function sortArray(array $array, string $field, string $algorithm): array

Аргументы

array $array
Исходный массив для сортировки. Может быть как ассоциативным, так и числовым.
string $field
Поле в элементах массива, по которому выполняется сортировка.
string $algorithm
Алгоритм сортировки:
  • number-asc/desc - числовая сортировка
  • date-asc/desc - сортировка по дате
  • string-asc/desc - строковая сортировка (natural order)
  • rand - случайное перемешивание

Результат

Возвращает отсортированную копию исходного массива с сохранением ключей.

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

// Сортировка страниц по полю order
$pages = getPages();
$sortedPages = sortArray($pages, 'order', 'number-asc');

// Сортировка новостей по дате (новые сверху)
$news = getNews();
$sortedNews = sortArray($news, 'date', 'date-desc');

// Случайное перемешивание элементов
$randomOrder = sortArray($products, '', 'rand');

Примечания

  • Для дат используется преобразование через strtotime()
  • Строковая сортировка выполняется с учетом natural order (strnatcasecmp)
  • Элементы без указанного поля помещаются в конец массива
  • Функция сохраняет ключи массива
  • Для случайной сортировки поле $field игнорируется