Функции для генерации и обработки случайных строк в 1С-Битрикс: randString и \Bitrix\Main\Security\Random

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

1. Устаревшая, но до сих пор присутствующая в коде функция randString().
2. Современный, рекомендуемый для использования класс \Bitrix\Main\Security\Random.

Кроме описания, вы увидите примеры, узнаете о типичных подводных камнях (например, невидимые спецсимволы при копировании из документации), а также о том, как правильно генерировать строки с требуемым набором символов.

1. Функция randString()

Сигнатура:

string randString(
    int $pass_len = 10,
    bool|array $pass_chars = false
);

• $pass_len – длина результирующей случайной строки.
• $pass_chars – набор символов. Может быть:
  • false (по умолчанию) – тогда используется стандартный набор символов (латинские буквы верхнего и нижнего регистра и цифры).
  • строка – тогда символы берутся непосредственно из этой строки.
  • массив (например, из нескольких строк-«классов» символов) – в таком случае в итоговую строку обязательно попадёт по хотя бы одному символу из каждого элемента массива.

Важно: функция randString() считается устаревшей (deprecated). Разработчикам рекомендуется переходить на новый класс \Bitrix\Main\Security\Random. Однако во многих старых проектах randString() всё ещё может активно использоваться.

1.1. Пример использования по умолчанию

Самый простой пример – сгенерировать 7-символьную строку:

<?php
$new_password = randString(7);
echo "Новый пароль: " . $new_password;
// Пример вывода: Новый пароль: fK4ftTP
?>

Функция вернёт комбинацию (по умолчанию) из цифр и букв (верхнего и нижнего регистра).

1.2. Передача конкретного набора символов в виде строки

Если вам нужно ограничить набор символов, например, только буквами нижнего регистра и цифрами:

<?php
// Сгенерирует случайную строку длиной 10
// только из символов: abcdefg...xyz0123456789
$code = randString(10, "abcdefghijklmnopqrstuvwxyz0123456789");
echo $code;
?>

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

Если вы хотите, чтобы в итоговой строке гарантированно был хотя бы один символ из каждого подмассива, воспользуйтесь массивом. Например, в итоговый пароль гарантированно попадёт:

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

<?php
$password = randString(12, [
    "abcdefghijklnmopqrstuvwxyz",  // Строчные буквы
    "ABCDEFGHIJKLNMOPQRSTUVWXYZ",  // Заглавные буквы
    "0123456789",                  // Цифры
    "!@#$%^&*()"                   // Спецсимволы
]);
echo $password;
?>

Обратите внимание, что при таком использовании функция сама перетасует символы, чтобы «разложить» их по случайным позициям, и гарантированно возьмёт по одному символу из каждого класса.

1.4. Осторожнее с копированием набора символов!

В документации и некоторых примерах по Битрикс можно встретить строку:

abcdefghijklnmopqrstuvwxyzABCDEFGHIJKLNMOPQRSTUVWXYZ01234567­89

В ней могут содержаться невидимые спецсимволы (так называемые «мягкие переносы», \u00AD или похожие), из-за которых при копировании набор искажается. В результате в коде появляются «крокозябры» и функция выдаёт непредвиденные результаты.

• Рекомендуется перепечатать или перепроверить строку вручную.
• Убедиться, что не пропущены некоторые буквы (иногда теряется o, или встречается дополнительный символ).
• Не использовать русские символы или символы с несколькими байтами: из-за внутренних особенностей (используется strlen(), а не mb_strlen()) это приведёт к некорректной генерации.

1.5. Статус deprecated и альтернатива

Функция randString() помечена как устаревшая (deprecated) и в будущем может быть удалена из ядра. Рекомендуемый способ генерации случайных строк – это использование класса \Bitrix\Main\Security\Random.

Кстати, внутри randString() при вызове с разными типами $pass_chars всё равно «под капотом» подключаются методы класса Random. Посмотрим на них подробнее.

2. Класс \Bitrix\Main\Security\Random

Современный подход к генерации строк, чисел и байтов в 1С-Битрикс – это статические методы класса \Bitrix\Main\Security\Random. Он находится по пути:

bitrix/modules/main/lib/security/random.php

2.1. Основные методы

1. getString(int $length, bool $caseSensitive = false) Генерирует случайную буквенно-цифровую строку (0–9, a–z). При установленном флажке $caseSensitive = true добавляются и заглавные буквы (A–Z).
2. getStringByAlphabet(int $length, int $alphabet) Позволяет выбирать «алфавит» по специальным битовым маскам:
   • Random::ALPHABET_NUM (цифры 0–9),
   • Random::ALPHABET_ALPHALOWER (строчные латинские буквы),
   • Random::ALPHABET_ALPHAUPPER (заглавные латинские буквы),
   • Random::ALPHABET_SPECIAL (набор спецсимволов),
   • Random::ALPHABET_ALL (все вышеперечисленные).
   Можно комбинировать (например, Random::ALPHABET_NUM | Random::ALPHABET_ALPHALOWER).
3. getStringByCharsets(int $length, string $charsetList) Генерирует строку по переданному списку символов (ASCII). Аналог randString($len, $pass_chars) в простом случае.
4. getStringByArray(int $length, array $charsetList): string Здесь принимается массив строк (каждая строка — это свой «класс» символов). Метод гарантирует включение в итоговую строку хотя бы одного символа из каждого элемента массива (при условии, что итоговая строка по длине позволяет вместить все символы).
5. getInt(int $min, int $max = \PHP_INT_MAX) Возвращает случайное целое число в диапазоне от $min до $max. Удобно для генерации числовых кодов, случайных идентификаторов или индексов.
6. getBytes(int $length) Возвращает случайную последовательность байтов (не обязательно человекочитаемых). Полезно для криптографии, солей (salt), ключей и других низкоуровневых вещей.

2.2. Примеры использования \Bitrix\Main\Security\Random

2.2.1. Генерация короткой строки

<?php

use Bitrix\Main\Security\Random;

$randomString = Random::getString(8);
echo $randomString;
// Например, 'a0b1c2d3'
?>

По умолчанию будут цифры и буквы в нижнем регистре.

2.2.2. Генерация чувствительной к регистру строки

<?php

use Bitrix\Main\Security\Random;

$randomStringCase = Random::getString(12, true);
echo $randomStringCase;
// Например, 'kL1Qp9wTr4Nh'
?>

Здесь уже включены и прописные, и строчные буквы плюс цифры.

2.2.3. Генерация строки по конкретной «алфавитной маске»

<?php

use Bitrix\Main\Security\Random;

// Возьмём: цифры + все буквы + спецсимволы
$alphabetMask = Random::ALPHABET_NUM
              | Random::ALPHABET_ALPHALOWER
              | Random::ALPHABET_ALPHAUPPER
              | Random::ALPHABET_SPECIAL;

$randomAll = Random::getStringByAlphabet(10, $alphabetMask);
echo $randomAll;
// Пример: 'vE7#R3pQ)a'
?>

2.2.4. Генерация строки из чётко заданного набора символов

<?php

use Bitrix\Main\Security\Random;

$charset = "ABCxyz123";
$code = Random::getStringByCharsets(6, $charset);
echo $code;
// Пример: 'x1zA3C'
?>

2.2.5. Гарантированно взять хотя бы по одному символу из каждого набора

Например, требуется, чтобы пароль обязательно содержал:

• хотя бы одну цифру,
• хотя бы одну букву,
• хотя бы один спецсимвол и т.д.

<?php

use Bitrix\Main\Security\Random;

$charsetArray = [
    "0123456789",                 // хотя бы одна цифра
    "abcdefghijklnmopqrstuvwxyz", // хотя бы одна строчная буква
    "ABCDEFGHIJKLNMOPQRSTUVWXYZ", // хотя бы одна заглавная буква
    "!@#$%^&*()_-+=[]{}"          // хотя бы один спецсимвол
];

// Сформируем 12-символьную строку:
$password = Random::getStringByArray(12, $charsetArray);
echo $password;
// Пример: 'Q5ua(fzHC19)'
?>

Важно: длины достаточно, чтобы вместить хотя бы по одному символу из каждого массива (иначе метод не сможет выполнить условие).

2.2.6. Генерация случайного целого числа в диапазоне

<?php

use Bitrix\Main\Security\Random;

$min = 1000;
$max = 9999;
$randomInt = Random::getInt($min, $max);
echo $randomInt;
// Пример: 3482
?>

2.2.7. Получение случайных байтов

<?php

use Bitrix\Main\Security\Random;

$bytes = Random::getBytes(16);
echo bin2hex($bytes);
// Пример: 5e4c3af029aac8ebb321d1ef8d6e8de3
?>

Такой код часто используется при создании криптостойких ключей, секретов для токенов, «солей» для хеширования паролей и прочего.

3. Важные замечания при работе с \Bitrix\Main\Security\Random

1. ASCII vs мультибайтовые символы. Внутри многих методов используется strlen(), а не mb_strlen(). Поэтому при передаче русских или иных символов Unicode может произойти некорректная генерация (появляются «кракозябры»). Если нужна лотерея среди русских букв или эмодзи – лучше искать другие решения или дополнять логику.
2. Невидимые спецсимволы в документации. Будьте внимательны к копированию строк из документации. Там нередко «закрадываются» не видимые невооружённым глазом символы переноса, которые ломают генерацию.
3. Безопасность. Методы Random стараются использовать криптостойкие источники случайности (например, openssl_random_pseudo_bytes, /dev/urandom) и при недоступности надежного источника делают «резервный» вариант (через mt_rand()). Для большинства задач это более чем достаточно.
4. Совместимость. Если у вас старая версия 1С-Битрикс, и методы класса Random в ней отсутствуют, можно временно остаться на randString(). Но при обновлении ядра всё-таки рекомендуется перейти на современный API.

4. Итог: что использовать и когда

• Новые проекты Сразу используйте \Bitrix\Main\Security\Random. Это гибче, надёжнее и соответствует рекомендациям 1С-Битрикс.
• Старые проекты Если уже активно применяется randString() и нет возможности внести правки — можно оставить, но помните: в будущем разработчики ядра могут отказаться от этой функции, и вам всё равно придётся мигрировать на Random.
• Особые требования Когда нужен сложный набор символов, обязательно используйте методы getStringByArray() либо смешанный подход в getStringByAlphabet(). Так вы сможете гибко гарантировать включение нужного «класса» символов (цифры, спецсимволы и т.д.).
• Случайные числа Random::getInt() – простой способ получить безопасное число в нужном диапазоне.
• Случайная последовательность байтов Random::getBytes() — для генерации криптографических ключей, токенов и «солей».

Заключение

Работа с генерацией случайных строк (паролей, кодов, ключей) в 1С-Битрикс может быть организована как через устаревшую функцию randString(), так и через современный класс \Bitrix\Main\Security\Random. С практической точки зрения имеет смысл переходить на новый класс, ведь он более гибок и потенциально безопаснее. При этом не забывайте о подводных камнях: аккуратно копируйте символы, не используйте мультибайтовые буквы и проверяйте, что ваша версия Битрикс поддерживает нужный функционал.

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