Функции для обработки строк и текста: htmlspecialcharsEx, htmlspecialcharsback и htmlspecialcharsbx

В рамках этой статьи мы подробно расскажем о таких функциях обработки строк и текста, как htmlspecialcharsEx, htmlspecialcharsBack и htmlspecialcharsbx. Эти функции широко используются в проектах на 1С-Битрикс для обеспечения корректного отображения текстовых данных, а также для защиты от нежелательных HTML-вставок.

Функции для обработки строк и текста в 1С-Битрикс

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

В 1С-Битрикс есть свои методы для экранирования и обратного преобразования строк:

• htmlspecialcharsEx
• htmlspecialcharsBack
• htmlspecialcharsbx

1. htmlspecialcharsEx

Описание и назначение

Функция htmlspecialcharsEx переводит строку в HTML-безопасный вид, заменяя специальные символы на их HTML-сущности. Она похожа на классическую PHP-функцию htmlspecialchars(), но работает корректнее в контексте 1С-Битрикс и допускает использование символов в виде &код_символа;.

Это означает, что при передаче строки в функцию 1С-Битрикс пытается не «испоганить» уже экранированные HTML-сущности, а только привести опасные символы к безопасной форме.

Сигнатура

string htmlspecialcharsEx(
    string $text
);

Параметры

• $text – текст, который нужно преобразовать в безопасный для HTML-вывода.

Результат

• Возвращает строку, в которой все специальные символы <, >, ", & и т. д. заменены на их HTML-аналог.

Таблица замен

Но благодаря внутренней логике в 1С-Битрикс, уже экранированные сущности вроде & не преобразуются дважды, а обрабатываются корректно (подробнее об этом ниже).

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

<?php
// Исходный текст
$text = '"если a>b и b>c, то a>c"';

// Преобразуем
$res = htmlspecialcharsEx($text);

// $res будет содержать:
// &quot;если a&gt;b и b&gt;c, то a&gt;c&quot;

// Но при выводе на экран интерпретатор преобразует сущности обратно,
// и мы увидим на странице тот же самый текст:
// "если a>b и b>c, то a>c"

echo $res;
?>

Важные детали

• В отличие от стандартной htmlspecialchars() из PHP, функция 1С-Битрикс корректнее обрабатывает уже закодированные сущности вида &код_символа;, не ломая их.
• В самом движке 1С-Битрикс функция htmlspecialcharsEx может быть определена так (упрощенный пример из bitrix/modules/main/tools.php), где используются списки поиска и замены:

function htmlspecialcharsEx($str)
{
    static $search =  array(
        "&", "<", ">", """, """, """,
        "'", "'", "<", ">", """
    );

    static $replace = array(
        "&amp;", "&lt;", "&gt;", "&quot;", "&#34;", "&#x22;",
        "&#39;", "&#x27;", "<", ">", """
    );

    return \Bitrix\Main\Text\StringHelper::str_replace($search, $replace, $str);
}

Обратите внимание на то, что & преобразуется в & и т. д., а уже существующие <, > и прочие сущности не дублируются некорректно, а переводятся в корректные HTML-последовательности.

2. htmlspecialcharsBack

Описание и назначение

Функция htmlspecialcharsBack делает обратное действие: берет строку с HTML-сущностями и превращает ее в «неэкранированный» вид, заменяя HTML-сущности на соответствующие символы. Это полезно, когда требуется отобразить в интерфейсе или использовать в логике уже очищенный ранее текст без HTML-тегов, а затем «раскодировать» его.

Сигнатура

string htmlspecialcharsBack(
    string $text
);

Параметры

• $text – текст, который нужно преобразовать обратно в исходные символы.

Результат

• Возвращает строку, в которой сущности вроде <, >, ", & снова становятся <, >, " и &.

Таблица замен

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

<?php
// Допустим, у нас есть уже экранированная строка
$str = '&quot;если a&gt;b и b&gt;c, то a&gt;c&quot;';

// Преобразуем ее обратно
$res = htmlspecialcharsBack($str);

// Теперь $res будет:
// "если a>b и b>c, то a>c"

// На экран выведется исходный текст
echo $res;
?>

Важные детали реализации

Внутри 1С-Битрикс функция может выглядеть так (упрощенно из тех же файлов ядра):

function htmlspecialcharsback($str)
{
    static $search =  array("<", ">", """, "'", "&");
    static $replace = array("<",    ">",    """, "'", "&");

    return \Bitrix\Main\Text\StringHelper::str_replace($search, $replace, $str);
}

Таким образом, < превращается в <, а & становится &.

3. htmlspecialcharsbx

Описание и назначение

Функция htmlspecialcharsbx — это еще один вариант экранирования, разработанный специально для PHP 5.4+, где по умолчанию кодировка — UTF-8. Она в основном повторяет логику встроенной htmlspecialchars(), но с учетом ряда особенностей 1С-Битрикс:

• Учитывается глобальная константа BX_UTF, определяющая, используется ли UTF-8.
• При отсутствии BX_UTF происходит fallback к «ISO-8859-1» или другой кодировке (но сейчас в большинстве проектов по умолчанию уже включен UTF-8).

Сигнатура

function htmlspecialcharsbx($string, $flags = ENT_COMPAT, $doubleEncode = true)
{
    return htmlspecialchars(
        (string)$string,
        $flags,
        (defined("BX_UTF") ? "UTF-8" : "ISO-8859-1"),
        $doubleEncode
    );
}

• $string – строка для экранирования.
• $flags – флаги для htmlspecialchars(). По умолчанию ENT_COMPAT экранирует двойные кавычки.
• $doubleEncode – если установлено в false, уже преобразованные сущности повторно не кодируются.

Когда использовать

• Если вы точно знаете, что ваш проект работает в UTF-8 или вам нужно гарантированно получить результат в конкретной кодировке.
• Если нет явной необходимости использовать расширенную логику htmlspecialcharsEx, а вы предпочитаете «стандартное» поведение PHP-функций в связке с Bitrix.

Где и как использовать функции

1. В компонентах

При выводе данных (например, заголовков, пользовательских полей, введенных в форму значений) используйте htmlspecialcharsEx или htmlspecialcharsbx для экранирования, чтобы обезопасить страницу от XSS и сохранить структуру HTML.

2. В шаблонах

Когда выводите переменные в шаблонах .default/template.php, часто удобно использовать <?= htmlspecialcharsEx($arResult['SOME_FIELD']) ?>.

3. При обработке форм

Перед сохранением в базу или перед выводом вводимых значений. Вы можете экранировать опасные символы, а затем при необходимости «вернуть все назад» через htmlspecialcharsBack (например, если нужно отобразить в форме редактирования исходный текст).

4. При работе с внешними данными (API, интеграции)

Если вы не уверены, что приходит извне — лишняя проверка и экранирование не повредят.

Практические примеры

1. Безопасный вывод данных пользователя

<?php
// Предположим, пользователь присылает в GET какую-то строку
$userInput = $_GET['message'] ?? '';

// Если сразу вывести без экранирования, можно получить XSS
// <script>alert('Уязвимость!');</script>

// Поэтому корректно:
$safeInput = htmlspecialcharsEx($userInput);
echo "<div>{$safeInput}</div>";
?>

2. Сохранение и обратное преобразование

<?php
// Сохраняем данные в экранированном виде, чтобы в базе не хранить потенциальный вред
$userComment = htmlspecialcharsEx($_POST['comment']);
// ... запись в БД

// Когда достаем данные из БД и хотим показать форму редактирования — возвращаем назад
$originalComment = htmlspecialcharsBack($userComment);
?>
<textarea name="comment"><?= $originalComment ?></textarea>

3. Разница между htmlspecialcharsEx и htmlspecialcharsbx

<?php
// Допустим, у нас есть строка на русском языке (UTF-8)
define("BX_UTF", true);

$str = "Пример: a > b";

// htmlspecialcharsbx
$encodedBx = htmlspecialcharsbx($str);
// Результат: "Пример: a &gt; b"
// с правильным указанием кодировки (UTF-8)

// htmlspecialcharsEx
$encodedEx = htmlspecialcharsEx($str);
// Здесь будет более «расширенная» логика замены
// которая гарантирует, что предыдущие HTML-сущности
// также не будут «сломаны», и при этом опасные символы
// корректно преобразуются.

echo $encodedBx;
echo "<br>";
echo $encodedEx;
?>

Основные отличия от стандартных PHP-функций

• Обработка уже экранированных сущностей

Функции от 1С-Битрикс аккуратно работают с теми фрагментами, которые уже были преобразованы в HTML-сущности, чтобы избежать повторной некорректной «двойной» замены. Стандартный htmlspecialchars() может повторно закодировать одни и те же символы, если не передать ему параметр $double_encode = false.

• Учет кодировок

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

• Проверенная интеграция с ядром 1С-Битрикс

Эти функции активно используются в компонентах ядра, модулях, шаблонах и тестировались в разных сценариях, что делает их максимально надежными и удобными в экосистеме Bitrix.

Заключение

При разработке на 1С-Битрикс безопасная обработка текстовых данных — одна из ключевых задач. Используя htmlspecialcharsEx, htmlspecialcharsBack и htmlspecialcharsbx, вы гарантируете корректное отображение данных в браузере и повышаете общую безопасность приложения, исключая уязвимости, связанные с HTML и JavaScript-вставками.

Резюмируя:

• Для вывода любых «внешних» данных в шаблонах/компонентах используйте экранирование (самый простой и чаще всего применяемый вариант — htmlspecialcharsEx).
• Если нужно вернуть экранированный текст в «необработанный» вид (например, отобразить в форме ввода), примените htmlspecialcharsBack.
• Если в проекте используете PHP 5.4+ и у вас включен UTF-8, удобно применять htmlspecialcharsbx.

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

Совет: Всегда проверяйте и фильтруйте данные на входе. Использование функций экранирования — часть комплексного подхода к безопасности, включающего проверку типов, длины, допустимых значений и т. д.

Надеемся, что эта статья поможет вам лучше разобраться в нюансах функций для обработки строк и текста в 1С-Битрикс, и вы будете увереннее использовать их в своих проектах!