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

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

arrayFindPrevNext arrayFormat arrayNatSort arrayPagination arrayReplaceKeys arraySearchKeys arraySortKeys arrayToStrHTML arrayValidate arrayСondition checkArrVal choiceKey searchInArray sortArray

Функция 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-меню
    • Вывода списков
    • Обработки пользовательского ввода
    • Создания структурированных данных

No description 😟...

Функция 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()

Функция 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
Поле в элементах массива, по которому выполняется сортировка. Если передана пустая строка,

используется только для алгоритма 'rand'.

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 игнорируется