Функции строк Albireo CMS

checkStr convertDate hex2RGB humanFilesize implodeWrap isValidEmoji isValidUrl mb_ucfirst plur strCropWord 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.
Разделитель: Функция использует пробел в качестве разделителя слов. Она может некорректно работать с текстами, где слова разделены несколькими пробелами или другими символами.

Функция strExplode

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

Сигнатура

function strExplode(string $s = '', bool $unique = true, bool $int = false, bool $rangeDot = false): array

Аргументы

string $s (обязательный): Входная строка для разбора. Элементы должны быть разделены запятыми.
bool $unique (необязательный): Если true (по умолчанию), все дублирующиеся значения в итоговом массиве будут удалены.
bool $int (необязательный): Если true, функция отфильтрует массив, оставив только те элементы, которые являются положительными целыми числами (больше нуля). По умолчанию false.
bool $rangeDot (необязательный): Если true, функция попытается распознать строку как числовой диапазон, заданный через две точки (например, '1..10'), и преобразует её в массив чисел этого диапазона. По умолчанию false.

Результат

Возвращает массив строк (array). Даже при использовании опции $int, элементы массива остаются строками. Если после всех обработок массив пуст, возвращается пустой массив.

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

Пример 1: Обработка списка тегов

Стандартный случай: получение уникальных тегов из строки.

$tagString = ' php, javascript, css, php,  , html ';
$tags = strExplode($tagString);

// $tags будет: ['php', 'javascript', 'css', 'html']
print_r($tags);

Пример 2: Получение списка числовых ID

Фильтрация строки для получения только валидных положительных идентификаторов.

$idString = '101, 54, 0, -20, abc, 101';
$ids = strExplode($idString, true, true);

// $ids будет: ['101', '54']
print_r($ids);

Пример 3: Создание числового диапазона

Удобно для задания диапазонов в конфигурационных файлах.

$rangeString = '1..7';
$numbers = strExplode($rangeString, false, false, true);

// $numbers будет: ['1', '2', '3', '4', '5', '6', '7']
print_r($numbers);

Примечания

Функция автоматически удаляет пустые элементы, которые могут появиться из-за двойных или висячих запятых (например, 'a,,b,').
При использовании опции $int = true, в итоговый массив попадают строковые представления чисел, а не сами числа типа integer.
Опция $rangeDot = true лучше всего работает, когда входная строка содержит только диапазон и ничего больше. Поведение при смешивании диапазона с другими значениями (например, '1, 2, 5..10') не определено и может привести к непредсказуемым результатам.

Функция strFirstDotClean

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

Сигнатура

function strFirstDotClean(string $path): string

Аргументы

string $path: Входная строка для обработки. Может содержать разделители / или \.

Результат

Возвращает обработанную строку (string), в которой из каждого сегмента удален префикс вида "число-точка". Если в строке не было разделителей, она обрабатывается как один сегмент.

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

Пример 1: Очистка пути с разделителем `\`

Часто используется для путей в операционной системе Windows.

$windowsPath = 'C:\Users\Admin\Documents\01.Work\05.Reports\2024.report.docx';
$cleanedPath = strFirstDotClean($windowsPath);

// $cleanedPath будет: 'C:\Users\Admin\Documents\Work\Reports\2024.report.docx'
echo $cleanedPath;

Пример 2: Очистка пути с разделителем `/`

Стандартный случай для веб-путей или систем на базе Unix.

$urlPath = 'docs/01.getting-started/02.installation-guide';
$cleanedUrl = strFirstDotClean($urlPath);

// $cleanedUrl будет: 'docs/getting-started/installation-guide'
echo $cleanedUrl;

Пример 3: Обработка строки без разделителей

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

$fileName = '03.final-chapter.md';
$cleanedFileName = strFirstDotClean($fileName);

// $cleanedFileName будет: 'final-chapter.md'
echo $cleanedFileName;

Пример 4: Частичное совпадение

Префиксы удаляются только там, где они есть. Остальные сегменты остаются без изменений.

$mixedPath = 'projects/01.alpha-project/src/main.js';
$cleanedMixedPath = strFirstDotClean($mixedPath);

// $cleanedMixedPath будет: 'projects/alpha-project/src/main.js'
echo $cleanedMixedPath;

Примечания

Определение разделителя: Функция сначала ищет символ /. Если он не найден, она ищет \. Используется первый найденный разделитель.
Формат префикса: Удаляются только префиксы, состоящие из одной или нескольких цифр, за которыми сразу следует точка (.). Префиксы вроде '01-' или 'A.' не будут удалены.

Функция strFormat

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

Сигнатура

function strFormat(string $format, array $array): string

Аргументы

string $format: Строка-шаблон, содержащая плейсхолдеры для замены. Например, 'Привет, %user%!'.
array $array: Ассоциативный массив данных, где ключи — это имена плейсхолдеров (без символов %), а значения — это данные для подстановки.

Результат

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

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

Пример 1: Создание HTML-ссылки

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

$linkParams = [
    'class' => 'user-link active',
    'url'   => '/users.php?id=' . urlencode('1&role=admin'), // urlencode для безопасности URL
    'name'  => htmlspecialchars('<Ivan Ivanov>'),         // htmlspecialchars для безопасности HTML
    'count' => 5,
];

$format = '<a class="%class%" href="%url%">%name% <sup>%count%</sup></a>';

$htmlLink = strFormat($format, $linkParams);

// $htmlLink будет содержать:
// <a class="user-link active" href="/users.php?id=1%26role%3Dadmin">&lt;Ivan Ivanov&gt; <sup>5</sup></a>
echo $htmlLink;

Пример 2: Формирование простого текстового отчета

Функцию можно использовать для создания любых текстовых сообщений по шаблону.

$reportData = [
    'date'    => date('d.m.Y'),
    'user'    => 'Администратор',
    'status'  => 'успешно',
    'records' => 150,
];

$reportTemplate = 'Отчет за %date%. Пользователь: %user%. Операция завершена %status%. Обработано записей: %records%.';

$reportText = strFormat($reportTemplate, $reportData);

// Выведет что-то вроде:
// Отчет за 21.05.2024. Пользователь: Администратор. Операция завершена успешно. Обработано записей: 150.
echo $reportText;

Примечания

Безопасность: Функция выполняет простую замену текста и не производит никакого экранирования. Всегда подготавливайте и экранируйте данные (например, с помощью htmlspecialchars для HTML или urlencode для URL) перед передачей их в функцию, чтобы избежать XSS и других уязвимостей.
Отсутствующие ключи: Если в массиве $array отсутствует ключ, соответствующий плейсхолдеру в строке $format, то этот плейсхолдер останется в итоговой строке без изменений (например, %unmatched_key%).

Функция strRemoveLF

Функция strRemoveLF предназначена для базовой минимизации текстовых данных, таких как HTML, CSS или JavaScript. Она выполняет две основные операции: сначала удаляет все ведущие и замыкающие пробелы и символы табуляции с каждой строки текста, а затем убирает все переносы строк, превращая форматированный код в одну сплошную строку.

Сигнатура

function strRemoveLF(string $text): string

Аргументы

string $text: Входная строка для сжатия. Может содержать форматирование, такое как отступы и переносы строк.

Результат

Возвращает сжатую строку (string) без переносов и лишних пробелов по краям строк.

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

Пример 1: Сжатие HTML-кода

Часто используется для удаления форматирования из HTML-шаблонов перед выводом, чтобы уменьшить размер ответа.

$htmlBlock = '
    <div class="container">
        <h1>Привет, мир!</h1>
    </div>
';

$compressedHtml = strRemoveLF($htmlBlock);

// $compressedHtml будет:
// <div class="container"><h1>Привет, мир!</h1></div>
echo $compressedHtml;

Пример 2: Минимизация CSS

Аналогично можно сжимать стили.

$cssRules = '
    .header {
        background-color: #f0f0f0;
        padding: 10px;
    }

    .footer {
        font-size: 12px;
    }
';

$minifiedCss = strRemoveLF($cssRules);

// $minifiedCss будет:
// .header {background-color: #f0f0f0;padding: 10px;}.footer {font-size: 12px;}
echo $minifiedCss;

Пример 3: Обработка простого текста

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

$multiLineText = "
    Это первая строка.
    А это вторая.
      И третья с отступом.
";

$singleLine = strRemoveLF($multiLineText);

// $singleLine будет:
// Это первая строка.А это вторая.И третья с отступом.
echo $singleLine;

Пример 4: Использование Heredoc-синтаксиса

css.style[]: <?= strRemoveLF(<<<TXT
    li {margin-bottom: 20px}
    div.r {color: red}
TXT) ?>

Примечания

Функция не является полноценным минификатором кода. Она не удаляет пробелы внутри строк (например, между селектором и скобкой в CSS) и не обрабатывает синтаксические конструкции, такие как строковые литералы в JavaScript. Её основная задача — убрать форматирование отступов и переносов.

Функция strToSlug

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

Сигнатура

function strToSlug(string $slug, bool $deleteSlash = true, bool $deleteDot = false, string $nbsp = '-'): string

Аргументы

string $slug: Входная строка для преобразования.
bool $deleteSlash (необязательный): Если true (по умолчанию), удаляет все прямые (/) и обратные (\) слэши. Установите в false, чтобы сохранить структуру пути.
bool $deleteDot (необязательный): Если true, удаляет все точки (.). По умолчанию false, что позволяет сохранять расширения файлов.
string $nbsp (необязательный): Символ-заменитель для пробелов. По умолчанию используется дефис (-).

Результат

Возвращает очищенную и транслитерированную строку (string) в нижнем регистре.

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

Пример 1: Создание слага для заголовка статьи

Это основной сценарий использования для генерации URL-адресов страниц.

$articleTitle = 'Статья №1: «Лучшие практики» © 2024';
$urlSlug = strToSlug($articleTitle);

// $urlSlug будет: 'statya-1-luchshie-praktiki-c-2024'
echo $urlSlug;

Пример 2: Очистка имени файла с сохранением расширения

С помощью флагов можно аккуратно обработать имя файла, сохранив его расширение и структуру каталогов.

$filePath = 'Мои Документы/Отчёт (лето).docx';

// Сохраняем слэш и точку
$cleanPath = strToSlug($filePath, false, false);

// $cleanPath будет: 'moi-dokumenty/otchyot-leto.docx'
echo $cleanPath;

// Полная очистка для использования в качестве ID
$cleanId = strToSlug($filePath, true, true);

// $cleanId будет: 'moi-dokumentyotchyot-letodocx'
echo $cleanId;

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

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

$text = 'Some variable name';
$variableName = strToSlug($text, true, true, '_');

// $variableName будет: 'some_variable_name'
echo $variableName;

Примечания

Источник: Функция основана на реализации, используемой в MaxSite CMS.
Многоязычность: Таблица транслитерации включает символы для русского, украинского, белорусского, румынского и болгарского языков.
Стандарт транслитерации: За основу взят стандарт ISO 9, но с некоторыми популярными отклонениями (например, 'ц' → 'cz', 'ч' → 'ch').

Функция strUcFirst

Функция strUcFirst преобразует строку, делая заглавной первую букву каждого слова или сегмента, разделенного одним из указанных символов-разделителей. Это полезно для форматирования идентификаторов, путей или заголовков в более читаемый вид (например, "kebab-case" в "Header-Case").

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

Сигнатура

function strUcFirst(string $string, array $delimiters = ['/', '|', '-', '_']): string

Аргументы

string $string: Исходная строка для обработки.
array $delimiters (необязательный): Массив символов, которые будут использоваться в качестве разделителей. По умолчанию: ['/', '|', '-', '_'].

Результат

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

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

Пример 1: Форматирование "kebab-case" строки

Преобразование строки, используемой в URL, в читаемый заголовок.

$slug = 'my-first-post-about-php';
$title = strUcFirst($slug, ['-']);

// $title будет 'My-First-Post-About-Php'
echo $title;

Пример 2: Работа с путями и смешанными разделителями

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

$complexPath = 'modules/user_profile|show-action';
$formattedPath = strUcFirst($complexPath);

// $formattedPath будет 'Modules/User_Profile|Show-Action'
echo $formattedPath;

Пример 3: Обработка строки в верхнем регистре

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

$constantName = 'MY_CONSTANT_VALUE';
$formattedName = strUcFirst($constantName, ['_']);

// $formattedName будет 'My_Constant_Value'
echo $formattedName;

Примечания

Разделители: Сами символы-разделители остаются в строке без изменений.

Функции строк Albireo CMS

Функция checkStr

Сигнатура

Аргументы

Результат

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

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

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

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

Примечания

Функция convertDate

Сигнатура

Аргументы

Результат

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

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

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

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

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

Примечания

Функция hex2RGB

Сигнатура

Аргументы

Результат

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

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

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

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

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

Примечания

Функция humanFilesize

Сигнатура

Аргументы

Результат

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

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

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

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

Примечания

Функция implodeWrap

Сигнатура

Аргументы

Результат

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

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

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

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

Примечания

Функция isValidEmoji

Сигнатура

Аргументы

Результат

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

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

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

Примечания

Функция isValidUrl

Сигнатура

Аргументы

Результат

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

Примечания

Функция mb_ucfirst

Сигнатура

Аргументы

Результат

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

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

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

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

Примечания

Функция plur

Сигнатура

Аргументы

Результат

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

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

Функция strCropWord

Сигнатура

Аргументы

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

Пример 1: Очистка пути с разделителем `\`

Пример 2: Очистка пути с разделителем `/`