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

При работе с текстом и строками в 1С-Битрикс довольно часто встаёт задача преобразовать символы в верхний или нижний регистр. В классической версии Bitrix (до появления D7) для этого существовали функции ToUpper и ToLower. Они корректно обрабатывают как латиницу, так и кириллицу, что особенно актуально для русского языка. Однако обратите внимание:

Несмотря на то, что обе функции имеют статус deprecated, кратко рассмотрим их. Я не нашёл аналоги этих функций в Битрикс D7. Вероятно, разработчики предлагают использовать стандартные функции PHP для таких преобразований.

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

ToUpper

string ToUpper(
    string text,
    string lang = false
);

Назначение

Функция ToUpper переводит все символы в переданной строке в верхний регистр. При этом корректно обрабатывается кириллица (русские буквы), что иногда вызывает проблемы при использовании стандартной PHP-функции strtoupper на некоторых хостингах.

Параметры

• text: Исходная строка, которую нужно преобразовать.
• lang: Идентификатор языка (по умолчанию false). Параметр появился с версии 10.0.11, но в большинстве случаев можно обойтись без него.

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

<?
$upper = ToUpper("абвгд abcdef");
echo "Верхний регистр: " . $upper;
// Результат: "Верхний регистр: АБВГД ABCDEF"
?>

В результате все буквы (как кириллические, так и латинские) станут заглавными.

Реализация в Bitrix (из bitrix/modules/main/tools.php)

/**
 * @deprecated
 * @param $str
 * @param false $lang
 * @return string
 */
function ToUpper($str, $lang = false)
{
    if(!defined("BX_CUSTOM_TO_UPPER_FUNC"))
    {
        return mb_strtoupper($str);
    }
    else
    {
        $func = BX_CUSTOM_TO_UPPER_FUNC;
        return $func($str);
    }
}

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

Дополнительные примеры

1. Использование в компоненте

   <?
   // Предположим, у нас есть название товара, которое нужно вывести в верхнем регистре
   $arResult['PRODUCT_NAME'] = ToUpper($arResult['PRODUCT_NAME']);
   ?>

2. Обработка нескольких языков

   В большинстве случаев ToUpper корректно работает с кириллицей и латиницей без указания параметра языка. Если требуется учесть специфичные символы других алфавитов, можно теоретически использовать lang, но на практике обычно достаточно настройки mb_internal_encoding.

ToLower

string ToLower(
    string text,
    string lang = false
);

Назначение

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

Параметры

• text: Исходная строка, которую необходимо преобразовать в нижний регистр.
• lang: Идентификатор языка (по умолчанию false). Также появился с версии 10.0.11.

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

<?
$lower = ToLower("АБВГД ABCDEF");
echo "Нижний регистр: " . $lower;
// Результат: "Нижний регистр: абвгд abcdef"
?>

В результате все буквы, включая русские, станут строчными.

Реализация в Bitrix (из bitrix/modules/main/tools.php)

/**
 * @deprecated
 * @param $str
 * @param false $lang
 * @return string
 */
function ToLower($str, $lang = false)
{
    if(!defined("BX_CUSTOM_TO_LOWER_FUNC"))
    {
        return mb_strtolower($str);
    }
    else
    {
        $func = BX_CUSTOM_TO_LOWER_FUNC;
        return $func($str);
    }
}

Аналогично ToUpper, если не определена константа BX_CUSTOM_TO_LOWER_FUNC, то используется mb_strtolower.

Дополнительные примеры

1. Использование в шаблоне компонента

   <?
   /**
    * Допустим, нам нужно привести к нижнему регистру имена пользователей,
    * которые мы получаем в массиве $arResult['USERS'].
    */
   foreach ($arResult['USERS'] as $key => $user)
   {
       $arResult['USERS'][$key]['NAME'] = ToLower($user['NAME']);
   }
   ?>

2. Проверка пользовательского ввода

   <?
   // Например, приводим электронную почту к нижнему регистру,
   // чтобы избежать ошибок при сравнении
   $email = ToLower($_POST['USER_EMAIL'] ?? '');
   ?>

Почему функции объявлены как @deprecated?

Формально в новом ядре D7 не предусмотрены аналоги ToUpper и ToLower. Разработчики 1С-Битрикс рекомендуют использовать встроенные функции PHP или расширения mbstring, то есть mb_strtoupper или mb_strtolower, которые отлично справляются с задачей преобразования регистра и корректно обрабатывают Unicode.

Скорее всего, историческая причина существования этих функций в Bitrix — необходимость обеспечения корректной работы с кириллицей до широкого распространения mbstring и настройки кодировок. Сейчас, когда PHP достаточно стабилен в вопросе обработки многобайтных строк, использование «bitrix-обёрток» в большинстве случаев не нужно.

Резюме

Функции ToUpper и ToLower в 1С-Битрикс обеспечивают корректную работу с многобайтными символами, в том числе с кириллицей. Однако они помечены как @deprecated, и в современном коде на D7 рекомендуется использовать стандартные PHP-функции — в частности, mb_strtoupper и mb_strtolower.

Тем не менее, если ваш проект работает в «старом» окружении или вы сталкиваетесь с проблемами при преобразовании кириллицы, использование ToUpper и ToLower может оказаться удобным решением. Стоит также помнить о возможности определить собственные функции через константы BX_CUSTOM_TO_UPPER_FUNC и BX_CUSTOM_TO_LOWER_FUNC, если вам необходимо расширить или изменить логику преобразования.

Надеюсь, эта статья прояснила нюансы использования ToUpper и ToLower в 1С-Битрикс. Если вы начинаете новые проекты или переносите старые на D7, рассматривайте переход на стандартные функции PHP для обработки строк и управляйте кодировками с помощью расширения mbstring, чтобы обеспечить корректную работу с Unicode во всех окружениях.