Функции работы с текстом в Битрикс: что реально полезно в проектах

Ниже — «самые рабочие» классы и методы, которые действительно попадают в боль проекта, плюс примеры, где это полезно.

Коротко: что брать в первую очередь

Если заглянуть в пространство имен Bitrix\Main\Text, можно выделить несколько инструментов, которые регулярно помогают:

1. Безопасный вывод и конвертация TEXT/HTML — HtmlFilter, HtmlConverter, Converter
2. Кодировки — Encoding
3. Emoji в базе — Emoji
4. Безопасная работа с UTF‑строками на «сыром» вводе — UtfSafeString
5. Конвертация имён и точечные строковые хелперы — StringHelper
6. Сервисные «фичи» под конкретные задачи — DateConverter, Diff, GeoHash, Base32, JsExpression

Дальше — разбор по «проектным» сценариям.

HtmlFilter / HtmlConverter: безопасный вывод и работа с TEXT/HTML

HtmlFilter::encode — минимальный и быстрый способ закрыть XSS

Класс HtmlFilter делает одну вещь: экранирует строку через htmlspecialchars(..., "UTF-8").

Это удобно, когда вы пишете новый код на D7 и хотите избежать «магии» старых хелперов, а также явно контролировать флаги (ENT_COMPAT по умолчанию) и doubleEncode.

        use Bitrix\Main\Text\HtmlFilter;

$name = $arResult['NAME'] ?? '';
echo HtmlFilter::encode($name);

    

Где полезно:

• шаблоны компонентов и админские страницы, где выводите данные пользователя (имя, комментарий, название товара)
• HTML‑атрибуты (тут обычно лучше отдельно думать про контекст, но базово encode() всё равно обязателен)

Converter::getHtmlConverter + HtmlConverter::encode: когда у вас «TEXT/HTML» тип поля

В Битриксе много мест, где у текста есть «тип»: обычный текст или HTML (часто поля DETAIL_TEXT + DETAIL_TEXT_TYPE, описания в настройках и т.п.). Converter даёт фабрики конвертеров, а HtmlConverter умеет:

• encode($text, $textType) — если тип text, экранирует (через HtmlFilter::encode), если html — оставляет как есть
• decode($text, $textType) — делает обратное

Практический сценарий: вы храните «описание» как text или html и при выводе хотите:

• text — показать безопасно (экранировать)
• html — показать как HTML (тоже осознанно, потому что это потенциально опасный источник)

        use Bitrix\Main\Text\Converter;

$text = (string)($row['DETAIL_TEXT'] ?? '');
$type = (string)($row['DETAIL_TEXT_TYPE'] ?? 'text'); // text|html

echo Converter::getHtmlConverter()->encode($text, $type);

    

Где полезно:

• универсальные блоки «описание/контент», которые могут быть либо HTML из редактора, либо обычным текстом
• единый вывод для инфоблоков, highload‑блоков и кастомных таблиц, где вы повторяете один и тот же «если HTML — не трогать»

Encoding: когда проект живёт на стыке Windows‑1251/UTF‑8/внешних интеграций

Encoding полезен, когда данные прилетают из разных источников и в разных кодировках. Главные методы:

• Encoding::convertEncoding($data, $from, $to) — конвертирует строку, массив или SplFixedArray рекурсивно, включая ключи
• Encoding::detectUtf8($string) — проверка «похоже ли на UTF‑8»
• Encoding::convertToUtf($string) — переводит в UTF‑8, если строка не UTF‑8 (берёт default_charset из конфигурации, иначе BX_DEFAULT_CHARSET)

Пример: импорт CSV в Windows‑1251 → в UTF‑8 перед разбором

Очень типично для проектов: файл в cp1251, сайт в UTF‑8, а дальше всё ломается на json_encode, поиске, регулярках, сохранении.

        use Bitrix\Main\Text\Encoding;

$raw = file_get_contents($csvPath);
$raw = Encoding::convertEncoding($raw, 'Windows-1251', 'UTF-8');


    

Где полезно:

• обмен с 1С и «наследием» на Windows‑1251
• выгрузки/импорты CSV/Excel, почтовые парсеры, внешние API
• когда вы видите в базе «кракозябры» и понимаете, что где-то смешались кодировки

Emoji: как хранить emoji, когда база/таблицы не готовы к utf8mb4

Emoji решает конкретную боль: 4‑байтовые UTF‑символы (emoji и часть редких символов) ломают сохранение в БД, если колонка/кодировка не поддерживает utf8mb4.

Подход Битрикс — перед сохранением «упаковать» emoji в безопасный ASCII‑вид :f09f938e: (hex), а при чтении — обратно.

Ключевые методы:

• Emoji::encode($text) / Emoji::decode($text)
• Emoji::replace($text, $callback) — для кастомных замен по emoji‑паттерну
• Emoji::getSaveModificator() / Emoji::getFetchModificator() — готовые модификаторы для ORM‑полей

Пример: подключить модификаторы в D7 ORM (как в ядре)

В ядре это используется, например, в IM‑сообщениях (MessageTable).

        class MyMessageTable extends \Bitrix\Main\Entity\DataManager
{
	public static function getTableName()
	{
		return 'b_my_message';
	}

	public static function getMap()
	{
		return [
			'ID' => [
				'data_type' => 'integer',
				'primary' => true,
				'autocomplete' => true,
			],
			'MESSAGE' => [
				'data_type' => 'text',
				'save_data_modification' => ['\Bitrix\Main\Text\Emoji', 'getSaveModificator'],
				'fetch_data_modification' => ['\Bitrix\Main\Text\Emoji', 'getFetchModificator'],
			],
		];
	}
}

    

Пример: ручное использование при сохранении «проблемных» колонок

        use Bitrix\Main\Text\Emoji;

$safeForDb = Emoji::encode($userText);
// ... сохранить $safeForDb

$original = Emoji::decode($fromDb);

    

Где полезно:

• чаты, комментарии, отзывы, любые пользовательские тексты
• старые инсталляции, где база исторически не utf8mb4
• интеграции, которые приносят emoji, а вы не можете «просто сменить» кодировку таблиц

UtfSafeString: когда строка может быть «битой» и вы не хотите падать на UTF‑операциях

UtfSafeString — набор утилит, который полезен в «грязном мире»: лог‑файлы, бинарные куски, внешние источники, обрезка по байтам.

Полезные методы:

• UtfSafeString::rtrimInvalidUtf($string) — отрезает «хвост», если строка заканчивается на обрезанную последовательность UTF‑8
• UtfSafeString::escapeInvalidUtf($string) — заменяет невалидные байты на ? (по сути, санитайзер)
• UtfSafeString::pad($string, $padLen, $padStr, $padType) — str_pad для UTF
• UtfSafeString::checkEncoding($data) — проверка валидности UTF‑8 для строки/массива
• UtfSafeString::getLastPosition($haystack, $needle) — mb_strrpos, но только если строка валидная

Пример: безопасная обрезка ответа внешнего API «по байтам»

Обычно хочется взять первые N байт, чтобы не раздувать логи/уведомления. Но substr может разрезать UTF‑символ посередине и дальше всё «поедет».

        use Bitrix\Main\Text\UtfSafeString;

$raw = (string)$httpResponseBody;
$snippet = substr($raw, 0, 2048);
$snippet = UtfSafeString::rtrimInvalidUtf($snippet);

    

Пример: очистить «битую» строку перед записью в лог/JSON

        use Bitrix\Main\Text\UtfSafeString;

$safe = UtfSafeString::escapeInvalidUtf($raw);
$json = json_encode(['payload' => $safe], JSON_UNESCAPED_UNICODE);

    

Где полезно:

• логирование payload’ов интеграций
• обработка файлов/вложений, где вы берёте «кусок» контента
• любые места, где есть риск получить невалидный UTF‑8 (и потом словить странные ошибки в mb_* / JSON)

StringHelper: camelCase↔snake_case, безопасный str_replace для массивов, stringable‑проверки

StringHelper — небольшой, но часто применимый класс.

camel2snake / snake2camel — нормальный мост между «PHP‑миром» и «API‑миром»

        use Bitrix\Main\Text\StringHelper;

$apiField = StringHelper::camel2snake('createdAt');   // created_at
$dtoField = StringHelper::snake2camel('created_at');  // CreatedAt
$propName = StringHelper::snake2camel('created_at', true); // createdAt

    

Где полезно:

• REST/JSON API: в PHP вы живёте в camelCase, наружу отдаёте snake_case
• маппинг DTO ↔ массивы ($fields['created_at'] → $dto->createdAt)

StringHelper::str_replace — когда нужно заменить в массиве, не проваливаясь в рекурсию

Метод аккуратно обрабатывает только первый уровень массива и заменяет только scalar‑значения (строки/числа/булевы), что удобно для «массивов параметров».

        use Bitrix\Main\Text\StringHelper;

$values = [
	'SUBJECT' => 'Заказ #ORDER_ID#',
	'BODY' => 'Спасибо за заказ #ORDER_ID#',
	'META' => ['IGNORE' => '#ORDER_ID#'],
];

$values = StringHelper::str_replace('#ORDER_ID#', (string)$orderId, $values);

    

StringHelper::isStringable — безопасная проверка перед тем, как приводить к строке

        use Bitrix\Main\Text\StringHelper;

if (StringHelper::isStringable($value))
{
	$message = (string)$value;
}

    

Где полезно:

• логирование, трассировка, сбор диагностик, где в контексте может оказаться «что угодно»
• сбор сообщений ошибок, которые могут прийти как объект с __toString()

DateConverter: распознавание дат из «человеческого текста»

DateConverter — не «строковый хелпер», а небольшой парсер, который пытается извлечь дату/время из фразы вроде:

• завтра утром
• в пятницу 25.10
• end of next week (в англ. окружении, если есть соответствующие локализации)

Главный метод — DateConverter::decode($text, $limit = 0), который возвращает массив объектов DateConverterResult. В результате есть:

• распознанная дата (getDate())
• исходный фрагмент текста (getText()), позиция и длина в строке
• тип распознавания (relative/dayofweek/calendar/partofday и т.п.)

Пример: превратить «напомни завтра в 14:00» в дату для задачи

        use Bitrix\Main\Text\DateConverter;

$text = (string)$request->getPost('message');
$candidates = DateConverter::decode($text, 200);

$date = null;
if (!empty($candidates))
{
	$date = $candidates[0]->getDate();
	
	echo $date->format('d.m.Y H:i:s'); // 27.02.2026 14:00:00
}

    

Где полезно:

• чат‑боты, формы «быстрого напоминания», обработка команд в стиле «создай задачу на завтра»
• когда вы хотите UX «как в календарях»: пользователь пишет фразу, система подхватывает дату

Diff: подсветка отличий между версиями текста

Diff реализует алгоритм Майерса и умеет строить HTML‑представление изменений: удалённое выделяет через <s style="color:red">, добавленное — через <b style="color:green">.

Пример: показать пользователю «что поменялось» в описании

        use Bitrix\Main\Text\Diff;

$diff = new Diff();
$html = $diff->getDiffHtml($oldText, $newText);

echo $html;

    

Где полезно:

• история правок (контент, wiki‑страницы, регламенты)
• сравнение «до/после» в админке при модерации

Base32: удобные токены и ключи (RFC 4648)

Base32 кодирует/декодирует Base32 (RFC 4648/3548). Полезно, когда хочется:

• человекочитаемый токен без спецсимволов
• строки, которые хорошо переживают URL/QR/копипасту

Пример: сгенерировать «секрет» для ручного ввода

        use Bitrix\Main\Text\Base32;

$secret = Base32::encode(random_bytes(10));

    

Пример: проверить и декодировать вход

        use Bitrix\Main\Text\Base32;

$raw = Base32::decode($input);

    

JsExpression: как «протащить» JS‑код там, где обычно всё экранируется

JsExpression — обёртка над строкой, которая даёт понять коду вокруг: «это не строка, это JS‑выражение, не бери в кавычки».

В ядре это используется, например, в аналитике: если значение параметра — JsExpression, оно вставляется в JS как есть.

Пример: передать JS‑функцию в параметры генератора JS

        use Bitrix\Main\Text\JsExpression;

$params = [
	'user_id' => new JsExpression('function(){return BX.message("USER_ID") ? BX.message("USER_ID") : 0;}'),
];

    

Где полезно:

• генерация JS‑конфигов из PHP, когда часть значений должна быть функциями/выражениями
• аналитика, виджеты, интеграции, где «значение вычисляется на клиенте»