Номера телефонов в Bitrix D7: Parser, Formatter и нормализация

Зачем не изобретать свой разбор

В ядре main уже подключена обёртка над Google libphonenumber: \Bitrix\Main\PhoneNumber\Parser и набор констант формата \Bitrix\Main\PhoneNumber\Format. Это даёт предсказуемое поведение для международных номеров, кодов стран и валидации — важно для CRM, SMS-шлюзов и дублей в базе.

Разбор строки в объект

Любой ввод пользователя (с пробелами, скобками или без плюса) удобно прогнать через singleton-парсер. Результат — объект с методами форматирования и метаданными страны:

use Bitrix\Main\PhoneNumber\Parser;

$rawDial = '+7 (999) 999-99-99';
$parsed = Parser::getInstance()->parse($rawDial);

Если строка вообще не похожа на телефон, поведение зависит от версии libphonenumber и контекста; для бизнес-логики опирайтесь на isValid() ниже, а не только на факт успешного вызова parse().

Форматы вывода

Метод format() принимает одну из констант перечисления формата. Три самых полезных варианта:

\Bitrix\Main\PhoneNumber\Format::E164 — канонический «+79999999999» для API и уникальных ключей.
\Bitrix\Main\PhoneNumber\Format::INTERNATIONAL — привычный международный вид с пробелами, например «+7 999 999-99-99».
\Bitrix\Main\PhoneNumber\Format::NATIONAL — национальное представление для отображения в интерфейсе конкретной страны (для РФ часто «8 (999) 999-99-99»).

use Bitrix\Main\PhoneNumber\Format;

$e164 = $parsed->format(Format::E164);
$intl = $parsed->format(Format::INTERNATIONAL);
$nat = $parsed->format(Format::NATIONAL);

Страна и код страны

Для маршрутизации по региону или фильтров в админке:

$alpha2 = $parsed->getCountry();      // например "RU"
$digitsCc = $parsed->getCountryCode(); // например "7"

Проверка валидности

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

if ($parsed->isValid()) {
    // можно нормализовать и записывать
}

Страна по умолчанию из настроек

В настройках главного модуля есть опция phone_number_default_country (ISO Alpha-2). Её же отдаёт API:

$fallbackAlpha2 = Parser::getDefaultCountry();

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

Нормализация одной строкой

Если нужен только E164 без промежуточных шагов, есть ярлык:

$normalized = Parser::getInstance()->normalizePhoneNumber($rawDial);

Используйте его там, где не нужны промежуточные форматы и проверки; для сценариев «покажи ошибку пользователю» чаще удобнее полный объект после parse() и вызов isValid().

На что обратить внимание в проекте

При интеграциях сохраняйте в базе именно E164 — проще искать дубли и строить уникальные индексы.
Не смешивайте форматирование на уровне шаблонов со строковой склейкой в PHP для одних и тех же полей.
После смены «страны по умолчанию» в админке перепроверьте разбор локальных номеров в формах, где пользователь не вводит «+».

Итог

Parser и Format закрывают типовой контур «ввели как попало → нормализовали → проверили → отдали провайдеру или в интерфейс». Это надёжнее ручных preg_replace и совпадает с логикой полей телефона внутри экосистемы Битрикс.