ALBIREO CMS
version: 2026.10.02
© Albireo CMS, 2020-2026
h1 Функции строк Albireo CMS
checkStr convertDate hex2RGB humanFilesize implodeWrap isValidEmoji isValidUrl mb_ucfirst plur strCropWord strEval strExplode strFirstDotClean strFormat strRemoveLF strToSlug strUcFirst

Функция checkStr

Проверяет входное значение и классифицирует его по трем состояниям: «не задано» (возвращает null), «отключено» (возвращает false) и «включено» (возвращает true). Это особенно полезно для обработки конфигурационных параметров, где отсутствие опции имеет иной смысл, чем её явное отключение.

Сигнатура

function checkStr(mixed $str): ?bool

Аргументы

mixed $str
Входное значение для проверки. Может быть строкой, null, false или пустым значением.

Результат

Возвращает одно из трех значений:

  • null — Если входное значение $str строго равно null, false или пустой строке ''. Это означает, что опция не задана.
  • false — Если $str после удаления пробелов равно '0', '-' или (без учета регистра) 'false'. Это означает, что опция явно отключена.
  • true — Во всех остальных случаях (например, '1', 'on', 'любой текст'). Это означает, что опция задана и активна.

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

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

Демонстрация работы функции с разными типами входных данных.

// Состояние «не задано»
var_dump(checkStr(null)); // NULL
var_dump(checkStr(''));   // NULL

// Состояние «отключено»
var_dump(checkStr('0'));      // bool(false)
var_dump(checkStr('  -  ')); // bool(false)
var_dump(checkStr('False'));  // bool(false)

// Состояние «включено»
var_dump(checkStr('1'));          // bool(true)
var_dump(checkStr('активно'));    // bool(true)
var_dump(checkStr('2024-01-01')); // bool(true)

Пример 2: Обработка опционального параметра

Частый сценарий: нужно установить значение по умолчанию, если опция не задана, но учесть её явное выключение.

// Получаем значение опции 'show_sidebar' со страницы.
// Если опции нет, getPageData вернет null.
$mode = checkStr(getPageData('show_sidebar', null));

// Устанавливаем значение по умолчанию (true), если опция не задана.
// В противном случае используем результат проверки (true или false).
$showSidebar = is_null($mode) ? true : $mode;

if ($showSidebar) {
    echo 'Показываем сайдбар.';
} else {
    echo 'Сайдбар скрыт.';
}

Пример 3: Использование в условных конструкциях

Важно использовать строгое сравнение (=== или !==) для точного определения состояния.

$data = ['draft' => '1', 'sitemap' => '0', 'comments' => '-'];

// Пропускаем только те страницы, которые являются черновиками (draft: 1)
// checkStr($data['draft']) вернет true
if (checkStr($data['draft']) === true) {
    // continue; // пропустить
}

// Пропускаем страницы, явно исключенные из карты сайта (sitemap: 0)
// checkStr($data['sitemap']) вернет false
if (checkStr($data['sitemap']) === false) {
    // continue; // пропустить
}

// Выполняем действие, если комментарии НЕ отключены (то есть, включены или не заданы)
// checkStr($data['comments']) вернет false
if (checkStr($data['comments']) !== false) {
    // render_comments();
}

Примечания

  • Функция применяет trim() к строке, поэтому пробелы по краям не влияют на результат.
  • Проверка на слово 'false' является регистронезависимой.

Функция convertDate

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

Сигнатура

function convertDate(string $inputDate, string $outputFormat = 'd-m-Y'): string

Аргументы

string $inputDate
Входящая строка с датой. Должна быть в формате, который может быть обработан функцией PHP strtotime(). Примеры: '2024-05-21', 'now', '+1 day', 'last Monday'.
string $outputFormat (необязательный)
Строка формата для выходной даты, использующая символы, принятые в функции date(). По умолчанию используется 'd-m-Y'.

Результат

Возвращает отформатированную дату в виде строки (string) или пустую строку (''), если не удалось преобразовать исходную дату.

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

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

Преобразование даты из формата ISO 8601 в формат «день-месяц-год».

$isoDate = '2024-12-31';
$ruDate = convertDate($isoDate, 'd.m.Y');

echo $ruDate; // Выведет: 31.12.2024

Пример 2: Использование относительных дат

Функция легко работает с относительными датами, которые понимает strtotime.

$tomorrow = convertDate('+1 day', 'l, F j, Y');

// Выведет завтрашнюю дату, например: "Wednesday, May 22, 2024"
echo $tomorrow;

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

Извлечение только времени из полной строки даты.

$fullDateTime = '2023-10-26 22:05:15';
$timeOnly = convertDate($fullDateTime, 'H:i');

echo $timeOnly; // Выведет: 22:05

Пример 4: Обработка некорректной даты

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

$invalidDate = '32-13-2024';
$result = convertDate($invalidDate);

var_dump($result); // Выведет: string(0) ""

Примечания

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

Функция hex2RGB

Конвертирует шестнадцатеричное значение цвета (HEX) в его RGB-эквивалент. Функция поддерживает 6-значный и 3-значный форматы, автоматически очищает входную строку от посторонних символов (например, #) и может возвращать результат как в виде ассоциативного массива, так и в виде строки с настраиваемым разделителем.

Сигнатура

function hex2RGB(string $hexStr, bool $returnAsString = false, string $separator = ','): array|string

Аргументы

string $hexStr
Строка с HEX-кодом цвета. Может быть в 3-значном (f0c) или 6-значном (ff00cc) формате, с префиксом # или без него.
bool $returnAsString (необязательный)
Определяет формат возвращаемого значения. Если true, функция вернет строку. Если false (по умолчанию), вернется ассоциативный массив.
string $separator (необязательный)
Символ или строка, которая будет использоваться в качестве разделителя для компонентов RGB, если $returnAsString установлен в true. По умолчанию — запятая (,).

Результат

Возвращает значение в зависимости от параметра $returnAsString:

  • array (по умолчанию): Ассоциативный массив с ключами 'red', 'green', 'blue' и их числовыми значениями (0-255).
  • string: Строка, содержащая значения R, G, B, разделенные указанным сепаратором.

Если входная строка $hexStr не является валидным 3- или 6-значным HEX-кодом, функция вернет значения для белого цвета (255, 255, 255).

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

Пример 1: Получение RGB в виде массива

$hexColor = '#343a40';
$rgbArray = hex2RGB($hexColor);

// Выведет:
// array(3) {
//   ["red"]=> int(52)
//   ["green"]=> int(58)
//   ["blue"]=> int(64)
// }
print_r($rgbArray);

Пример 2: Работа с 3-значным форматом

// 'f8d' эквивалентно '#ff88dd'
$shortHex = 'f8d';
$rgbArray = hex2RGB($shortHex);

// Выведет: ['red' => 255, 'green' => 136, 'blue' => 221]
print_r($rgbArray);

Пример 3: Получение RGB в виде строки для CSS

$hex = '#ffc107';
$rgbString = hex2RGB($hex, true);

echo 'color: rgb(' . $rgbString . ');';
// Выведет: color: rgb(255,193,7);

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

$hex = '#17a2b8';
$rgbString = hex2RGB($hex, true, ' ');

echo $rgbString;
// Выведет: 23 162 184

Примечания

  • Функция автоматически удаляет все символы, не являющиеся шестнадцатеричными (0-9, A-F), из входной строки, поэтому передача значений вроде '#FF9900' является безопасной.
  • Источник и дополнительная информация: php.net

Функция humanFilesize

Преобразует числовое значение размера файла в байтах в более понятный для человека формат, добавляя суффиксы для байт (B), килобайт (K), мегабайт (M), гигабайт (G) и так далее. Функция использует степени 1024 для вычислений.

Сигнатура

function humanFilesize(int|float $bytes, int $decimals = 2): string

Аргументы

int|float $bytes
Размер в байтах.
int $decimals (необязательный)
Количество знаков после запятой для форматирования результата. По умолчанию 2.

Результат

Возвращает отформатированную строку (string), представляющую размер файла в человекочитаемом формате (например, '4.88K', '1.18M').

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

Пример 1: Базовое использование с разными размерами

echo humanFilesize(0);           // Выведет: 0.00B
echo humanFilesize(980);         // Выведет: 980.00B
echo humanFilesize(5000);        // Выведет: 4.88K
echo humanFilesize(1234567);     // Выведет: 1.18M
echo humanFilesize(9876543210);  // Выведет: 9.20G

Пример 2: Изменение точности вывода

Можно управлять количеством знаков после запятой с помощью второго аргумента.

$fileSizeInBytes = 1572864; // Это 1.5 МБ

echo humanFilesize($fileSizeInBytes, 0); // Выведет: 1M
echo humanFilesize($fileSizeInBytes, 2); // Выведет: 1.50M
echo humanFilesize($fileSizeInBytes, 4); // Выведет: 1.5000M

Пример 3: Практическое применение с функцией filesize

Чаще всего эта функция используется для отображения размера реального файла.

$filePath = 'path/to/your/large-file.zip';

if (file_exists($filePath)) {
    $bytes = filesize($filePath);
    echo 'Размер файла ' . basename($filePath) . ': ' . humanFilesize($bytes);
} else {
    echo 'Файл не найден.';
}

Примечания

  • Функция использует следующие суффиксы: B (байты), K (килобайты), M (мегабайты), G (гигабайты), T (терабайты), P (петабайты). Обратите внимание, что используются однобуквенные обозначения (K, M), а не более привычные 'KB', 'MB'.
  • В основе расчетов лежат степени 1024 (двоичные префиксы), а не 1000.
  • Источник и дополнительная информация: php.net

Функция implodeWrap

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

Сигнатура

function implodeWrap(array $data, string $before = '', string $after = ''): string

Аргументы

array $data
Индексированный или ассоциативный массив, значения которого будут обработаны.
string $before (необязательный)
Строка, которая будет добавлена в начало каждого непустого элемента массива.
string $after (необязательный)
Строка, которая будет добавлена в конец каждого непустого элемента массива.

Результат

Возвращает одну строку (string), полученную путем конкатенации всех обработанных элементов массива. Если исходный массив пуст, возвращается пустая строка.

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

Пример 1: Создание набора HTML-тегов

Преобразование простого массива тегов в HTML-разметку.

$tags = ['php', 'mysql', 'javascript'];
$beforeTag = '<span class="tag-item">';
$afterTag = '</span>';

$htmlTags = implodeWrap($tags, $beforeTag, $afterTag);

// $htmlTags будет содержать:
// <span class="tag-item">php</span><span class="tag-item">mysql</span><span class="tag-item">javascript</span>
echo $htmlTags;

Пример 2: Игнорирование пустых значений

Функция автоматически пропускает элементы, которые являются "пустыми" (null, false, 0, '').

$values = ['Первый', null, 'Третий', 0, '', 'Последний'];
$result = implodeWrap($values, '[', ']');

// $result будет содержать:
// [Первый][Третий][Последний]
echo $result;

Пример 3: Обычное обрамление без HTML

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

$words = ['цитата', 'ещё одна'];
$quotedString = implodeWrap($words, '"', '" '); // Добавляем пробел в конце для разделения

// $quotedString будет содержать:
// "цитата" "ещё одна" 
echo $quotedString;

Примечания

  • Пустые значения: Элементы массива, которые приводятся к false (например, 0, '', null, false), не будут обрамлены и фактически исчезнут из итоговой строки.

Функция isValidEmoji

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

Валидным считается либо пустая строка, либо строка, содержащая ровно один разрешенный символ-эмодзи. Флаги и символы из внутреннего "черного списка" считаются невалидными.

Сигнатура

function isValidEmoji(string $input): bool

Аргументы

string $input
Строка для проверки.

Результат

Возвращает булево значение (bool):

  • true — если строка пустая или содержит один разрешенный эмодзи.
  • false — если строка содержит обычный текст, цифры, несколько символов, флаг или запрещенный эмодзи.

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

Пример 1: Базовая валидация

Демонстрация работы с различными входными данными.

// Позитивные тесты
$isValid1 = isValidEmoji('✅'); // true
$isValid2 = isValidEmoji(' ');   // true (пробелы обрезаются, строка становится пустой)

// Негативные тесты
$isInvalid1 = isValidEmoji('❌');     // false (в черном списке)
$isInvalid2 = isValidEmoji('Hello');   // false (текст)
$isInvalid3 = isValidEmoji('😊😊'); // false (два символа)
$isInvalid4 = isValidEmoji('🇩🇪');   // false (флаг)

Пример 2: Валидация пользовательского ввода

Предположим, у вас есть форма, где пользователь может установить себе "статус" в виде одного эмодзи.

$userStatus = $_POST['status_emoji'] ?? ''; // Например, пользователь ввел '👍'

if (isValidEmoji($userStatus)) {
    // Ввод корректен, можно сохранять в базу данных
    saveUserStatus($userId, $userStatus);
    echo "Статус успешно обновлен!";
} else {
    // Ввод некорректен
    echo "Ошибка: пожалуйста, выберите один разрешенный эмодзи в качестве статуса.";
}

Примечания

  • Пустая строка: Функция целенаправленно считает пустую строку валидным значением. Это позволяет использовать её для опциональных полей.
  • Зависимость: Функция пытается использовать расширение PHP intl (функцию grapheme_strlen) для более точного определения длины строки, состоящей из одного визуального символа (графема). Если расширение недоступно, используется регулярное выражение с флагом \X.
  • Флаги и черный список: Эмодзи-флаги (состоящие из двух региональных индикаторов) и символы из внутреннего массива $blacklist всегда считаются невалидными.

Функция isValidUrl

Функция предназначена для проверки корректности и безопасности URL-адресов. Она выполняет последовательную валидацию по набору правил, включая проверку схемы, хоста, порта, пути, query-строки и наличие потенциально опасных XSS-вставок.

Сигнатура

function isValidUrl(string $url): bool

Аргументы

string $url
Строка с URL-адресом, который требуется проверить.

Результат

bool — возвращает true, если URL корректен и безопасен, или false, если нарушает правила.

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

// Валидный URL с кириллическим доменом
var_dump(isValidUrl('https://пример.ua/страница')); // true

// Валидный URL с поддоменом и query
var_dump(isValidUrl('https://sub.domain.com/path?x=1')); // true

// Невалидный URL с javascript-схемой
var_dump(isValidUrl('javascript://alert(1)')); // false

// Невалидный URL с двойным слэшем в пути
var_dump(isValidUrl('http://example.com//resource')); // false

// Невалидный URL с XSS-подобной вставкой
var_dump(isValidUrl('http://test.com/%3Cscript%3Ealert(1)%3C/script%3E')); // false

Примечания

Функция не использует преобразование IDN-доменов в Punycode, поэтому допускает Unicode-домены напрямую. Это упрощает работу с кириллическими и другими национальными доменными зонами.

Функция mb_ucfirst

Преобразует первый символ многобайтовой строки в верхний регистр. Эта функция является полифилом (polyfill) — реализацией функциональности, которая недоступна в версии PHP < 8.4. Она служит безопасной заменой для стандартной функции ucfirst() при работе с многобайтовыми кодировками, такими как UTF-8.

Сигнатура

function mb_ucfirst(string $string, string $encoding = 'UTF-8'): string

Аргументы

string $string
Входная строка, первый символ которой нужно преобразовать.
string $encoding (необязательный)
Имя кодировки символов. По умолчанию используется 'UTF-8'.

Результат

Возвращает строку (string), в которой первый символ преобразован в верхний регистр.

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

Пример 1: Работа с кириллицей

Стандартная функция ucfirst() некорректно работает с кириллическими символами, в то время как mb_ucfirst() справляется с этой задачей.

$text = 'привет';

echo ucfirst($text);      // Выведет 'привет' (не сработает)
echo mb_ucfirst($text); // Выведет 'Привет' (сработает корректно)

Пример 2: Обработка строки, уже начинающейся с заглавной буквы

Если строка уже начинается с заглавной буквы, она останется без изменений.

$text = 'Уже с заглавной';
echo mb_ucfirst($text); // Выведет 'Уже с заглавной'

Пример 3: Работа с пустой строкой

Передача пустой строки не вызовет ошибок и вернет пустую строку.

$emptyString = '';
echo mb_ucfirst($emptyString); // Выведет '' (пустую строку)

Примечания

  • Полифил: Код функции обернут в условие if (!function_exists('mb_ucfirst')). Это означает, что функция будет определена только в том случае, если она еще не существует в ядре PHP, что обеспечивает совместимость с будущими версиями.
  • Зависимости: Для работы функции требуется наличие расширения PHP mbstring.
  • Источник: Комментарии в официальной документации PHP

Функция plur

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

Сигнатура

function plur(int|string $number, string $f1, string $f2, string $f5): string

Аргументы

int|string $number
Число, на основе которого производится склонение. Может быть передано как целое число, так и в виде строки.
string $f1
Форма для единственного числа (когда число заканчивается на 1, кроме 11). Например, 'файл' («один файл»).
string $f2
Форма для малого количества (когда число заканчивается на 2, 3, 4, кроме 12, 13, 14). Например, 'файла' («два файла»).
string $f5
Форма для множественного числа (когда число заканчивается на 0, 5-9 или является исключением 11-19). Например, 'файлов' («пять файлов»).

Результат

Возвращает строку (string) с подходящей формой слова, которая была дополнительно обработана функцией перевода lang().

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

Пример вывода количества найденных элементов

$count1 = 1;
echo 'Найден ' . $count1 . ' ' . plur($count1, 'результат', 'результата', 'результатов');
// Выведет: Найден 1 результат

$count2 = 4;
echo 'Найдено ' . $count2 . ' ' . plur($count2, 'результат', 'результата', 'результатов');
// Выведет: Найдено 4 результата

$count3 = 25;
echo 'Найдено ' . $count3 . ' ' . plur($count3, 'результат', 'результата', 'результатов');
// Выведет: Найдено 25 результатов

$count4 = 11;
echo 'Найдено ' . $count4 . ' ' . plur($count4, 'результат', 'результата', 'результатов');
// Выведет: Найдено 11 результатов

Функция strCropWord

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

Сигнатура

function strCropWord(string $text, int $countWords = 15, string $atEnd = ' ...', int $minChars = 2, bool $stripTags = true): string

Аргументы

string $text
Входная строка для обработки.
int $countWords (необязательный)
Целевое количество "значимых" слов, которые должны остаться в строке. По умолчанию 15.
string $atEnd (необязательный)
Строка, которая будет добавлена в конец, если текст был укорочен. По умолчанию ' ...'.
int $minChars (необязательный)
Минимальное количество символов, которое должно быть в слове, чтобы оно было засчитано в лимит $countWords. По умолчанию 2.
bool $stripTags (необязательный)
Если true (по умолчанию), все HTML и PHP-теги будут удалены из входной строки перед обрезкой.

Результат

Возвращает обрезанную строку (string). Если исходная строка короче заданного лимита, она возвращается без изменений и без добавления конечной строки $atEnd.

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

Пример 1: Базовая обрезка анонса

Создание короткого анонса для статьи блога.

$fullPost = 'Это первая статья в нашем новом блоге. Мы планируем регулярно публиковать здесь полезные материалы, советы и новости из мира веб-разработки. Оставайтесь с нами!';
$excerpt = strCropWord($fullPost, 10, ' »');

// $excerpt будет: 'Это первая статья в нашем новом блоге. Мы планируем регулярно »'
echo $excerpt;

Пример 2: Игнорирование коротких слов

С помощью параметра $minChars можно получить более качественный результат, не учитывая короткие служебные слова.

$text = 'Раз, два, три, четыре, пять - я иду тебя искать. А кто не спрятался, я не виноват.';

// Обычная обрезка до 7 слов
$result1 = strCropWord($text, 7); // 'Раз, два, три, четыре, пять - ...'

// Обрезка до 7 слов, но считаем только те, в которых 3+ символа
$result2 = strCropWord($text, 7, '...', 3); // 'Раз, два, три, четыре, пять - иду тебя искать. спрятался, виноват. ...'

echo "Обычная обрезка: " . $result1 . "\n";
echo "Умная обрезка: " . $result2 . "\n";

Пример 3: Работа с HTML-содержимым

Функция может очистить текст от HTML-разметки перед обрезкой.

$html = '<h2>Заголовок</h2><p>Это <b>очень</b> важный текст, который нужно <i>красиво</i> обрезать.</p>';

// С удалением тегов
$resultWithStrip = strCropWord($html, 5); // 'Заголовок Это очень важный текст, ...'

// Без удаления тегов (не рекомендуется, может сломать разметку)
$resultWithoutStrip = strCropWord($html, 5, '...', 2, false); // '<h2>Заголовок</h2><p>Это <b>очень</b> важный ...'

echo "С очисткой: " . $resultWithStrip . "\n";
echo "Без очистки: " . htmlspecialchars($resultWithoutStrip) . "\n";

Примечания

  • Зависимости: Функция использует расширение mbstring (для mb_strlen) для корректной работы с многобайтовыми кодировками, такими как UTF-8.
  • Разделитель: Функция использует пробел в качестве разделителя слов. Она может некорректно работать с текстами, где слова разделены несколькими пробелами или другими символами.

Функция strEval

Выполняет PHP-код, внедрённый в текстовую строку в виде открывающих и закрывающих тегов PHP, перехватывает вывод и возвращает полученный результат.

Сигнатура

function strEval(string $_TEXT): string

Аргументы

string $_TEXT
Строка, содержащая произвольный текст и/или внедрённый PHP-код внутри тегов <?php ... ?> или коротких тегов вывода <?= ... ?>.

Результат

Строка (string) — сгенерированное в процессе выполнения содержимое либо исходная строка $_TEXT в случае возникновения ошибки или отсутствия PHP-тегов.

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

// 1. Подстановка динамических значений


$template = 'Здравствуйте, Иван!';


echo strEval($template); // 'Здравствуйте, Иван!'


// 2. Использование коротких тегов вывода


$math = '2 + 2 = 4';


echo strEval($math); // '2 + 2 = 4'


// 3. Строка без PHP-кода (возвращается без запуска eval)


$plain = 'Обычный текст без тегов';


echo strEval($plain); // 'Обычный текст без тегов'


// 4. Безопасная обработка ошибок (при исключении буфер сбрасывается и возвращается исходная строка)


$broken = 'Результат: 
Error in pages/04.core/19.string.php
Type: Exception
Message: Ошибка
File: pages/04.core/_func/string/strEval.php
Line: 43