Руководство по работе с классом \Bitrix\Main\UrlRewriterRuleMaker для настройки SEF-переадресаций в Битрикс D7

В современных веб-проектах на 1С-Битрикс часто требуется настраивать удобные, “человеко-понятные” ссылки (SEF — Search Engine Friendly URLs). При этом для управления схемой переадресации и парсинга URL разработчикам доступен специальный функционал ядра Битрикс. Один из полезных инструментов — класс \Bitrix\Main\UrlRewriterRuleMaker, расположенный в файле bitrix/modules/main/lib/urlrewriter.php.

$Работа с классом \Bitrix\Main\UrlRewriterRuleMaker$

Ниже вы найдёте подробное руководство по использованию UrlRewriterRuleMaker. Мы разберём назначение и реализацию основных методов, покажем, как формировать правила для ЧПУ (человеко-понятных URL), а также приведём несколько практических примеров, которые можно адаптировать под свой проект.

1. Класс UrlRewriterRuleMaker: назначение и структура

Класс \Bitrix\Main\UrlRewriterRuleMaker предназначен для генерации полей CONDITION и RULE — ключевых элементов SEF-правил в 1С-Битрикс. Эти поля затем могут использоваться в массиве $arUrlRewrite[] или других структурах настройки ЧПУ.

Основная идея работы:

Вы передаёте в метод process() некий “шаблон” SEF — строку, содержащую плейсхолдеры вида #ID#, #ELEMENT_ID#, #ANYTHING_PATH# и т. п.
UrlRewriterRuleMaker автоматически разбирает такой шаблон и формирует из него регулярное выражение (CONDITION) и правило для подстановки переменных (RULE).
Далее, при сопоставлении URL с шаблоном, движок 1С-Битрикс будет знать, как вычленить переменные и передать их в компонент.

1.1 Взаимодействие с другими пространствами имён

Хотя сам класс UrlRewriterRuleMaker находится в пространстве \Bitrix\Main, при работе над проектом и внедрении SEF-логики часто требуется задействовать и другие модули/классы/пространства имён:

\Main\Component — для реализации компонентов, где настраивается SEF_MODE.
\Main\IO — для чтения/записи файлов urlrewrite.php или других конфигурационных файлов.
\Main\Config — для управления общими настройками ядра и получения значений из конфига.

Однако непосредственно в данном классе задействуются только стандартные функции PHP и внутренние методы ядра Битрикс.

2. Обзор методов класса

Ключевые методы, которые чаще всего используются при работе с SEF, — getCondition() и getRule(). Они возвращают соответствующие поля будущего правила переадресации.

2.1 public function getCondition(): string

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

Сигнатура:

public function getCondition()
{
    return $this->condition;
}

Пример возвращаемого значения:
```
#^/news/([^/]+?)/([^/]+?)/\\??(.*)#
```
или
```
#^/catalog/(.+?)/\\??(.*)#
```
в зависимости от того, какие плейсхолдеры были найдены.

2.2 public function getRule(): string

Описание: Возвращает строку (RULE), которая определяет, как “раскрыть” найденные переменные и подставить их в строку запроса ($_REQUEST).

Сигнатура:

public function getRule()
{
    return $this->rule;
}

Пример возвращаемого значения:
```
SECTION_ID=$1&ELEMENT_ID=$2&$3
```
То есть указывает, что первая найденная группа - это SECTION_ID, вторая - ELEMENT_ID, а остаток запроса передаётся как есть.

2.3 public function process($sefRule): void

Описание: Основной метод, с помощью которого вы “кормите” класс входным шаблоном (например, '/news/#SECTION_ID#/#ELEMENT_ID#/'). Внутри метода:
1. Из плейсхолдеров вида #NAME# формируются группы регулярного выражения.
2. Запоминаются названия переменных.
3. Строятся поля $this->condition и $this->rule.

Пример:

$urlRewriter = new \Bitrix\Main\UrlRewriterRuleMaker();
$urlRewriter->process('/news/#SECTION_ID#/#ELEMENT_ID#/');

Тогда:

$urlRewriter->getCondition() может вернуть:
```
#^/news/([^/]+?)/([^/]+?)\\??(.*)#
```
$urlRewriter->getRule() может вернуть:
```
SECTION_ID=$1&ELEMENT_ID=$2&$3
```

2.4 Вспомогательный метод _callback(array $match): string

Описание: Закрытый (protected) метод, который вызывается внутри process() при разборе регулярных выражений. Именно он отвечает за то, как плейсхолдер #SOMETHING# превращается в ([^/]+?) или (.+?) (если оканчивается на _PATH#).
Вам, как пользователю класса, обычно не нужно напрямую вызывать _callback. Но важно понимать, что при наличии в шаблоне подстроки _PATH# класс настроит регулярное выражение под “жадный” матч на несколько директорий: (.+?).

3. Пошаговый пример настройки SEF-правил

Рассмотрим классический случай, когда в 1С-Битрикс (в компоненте новостей) вы хотите сделать ссылки вида:

/news/cinema/123/
/news/auto/456/

где:

cinema, auto — это SECTION_ID (строковой код или ID раздела)
123, 456 — это ELEMENT_ID

3.1 Создание экземпляра класса и генерация правил

<?php
use \Bitrix\Main\UrlRewriterRuleMaker;

// 1. Создаём объект
$urlRewriter = new UrlRewriterRuleMaker();

// 2. Передаём шаблон
$sefRule = '/news/#SECTION_ID#/#ELEMENT_ID#/';
$urlRewriter->process($sefRule);

// 3. Получаем результат
$condition = $urlRewriter->getCondition();
$rule = $urlRewriter->getRule();

echo $condition; // например: #^/news/([^/]+?)/([^/]+?)\??(.*)#
echo $rule;      // например: SECTION_ID=$1&ELEMENT_ID=$2&$3

3.2 Регистрация правила в файле urlrewrite.php

Обычно в 1С-Битрикс правила ЧПУ регистрируют в файле /bitrix/urlrewrite.php (либо /urlrewrite.php в корне сайта, в зависимости от структуры). В простейшем случае туда добавляется:

$arUrlRewrite = array(
   // ... уже существующие правила ...

   array(
      "CONDITION" => $condition,      // например: #^/news/([^/]+?)/([^/]+?)\??(.*)#
      "RULE"      => $rule,          // SECTION_ID=$1&ELEMENT_ID=$2&$3
      "ID"        => "",             // ID компонента (можно оставить пустым)
      "PATH"      => "/news/index.php", // путь к файлу, обрабатывающему запрос
   ),
);

Таким образом, при обращении к URL вида /news/cinema/123/, движок сопоставит его с регуляркой из CONDITION, извлечёт SECTION_ID=cinema, ELEMENT_ID=123, а остаток (если он был бы в query string) передаст дальше.

4. Дополнительные примеры использования

Ниже рассмотрим разные ситуации, где класс может оказаться полезным.

4.1 Множественные плейсхолдеры и _PATH#

Предположим, у вас есть необходимость “собрать” множество директорий в один параметр. Тогда в шаблоне можно использовать _PATH#, например: '/docs/#SECTION_CODE#/#FILE_PATH#/'.

$urlRewriter = new \Bitrix\Main\UrlRewriterRuleMaker();
$urlRewriter->process('/docs/#SECTION_CODE#/#FILE_PATH#/');

echo $urlRewriter->getCondition();
// #^/docs/([^/]+?)/(.+?)\??(.*)#
//    ^^^^^^^^^^^  ^^^^^
//    SECTION_CODE FILE_PATH (жадный матч)

echo $urlRewriter->getRule();
// SECTION_CODE=$1&FILE_PATH=$2&$3

Так как класс видит, что плейсхолдер называется #FILE_PATH# и заканчивается на _PATH#, то он подставляет в регулярку (.+?), что позволяет “захватывать” любую вложенность каталогов до следующего слэша или конца строки.

4.2 Генерация динамичных правил для нескольких компонентов

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

$rules = [
   [
      'SEF_RULE' => '/catalog/#SECTION_ID#/#ELEMENT_ID#/',
      'COMPONENT_FILE' => '/catalog/index.php',
   ],
   [
      'SEF_RULE' => '/blogs/#BLOG_CODE#/#POST_ID#/',
      'COMPONENT_FILE' => '/blogs/index.php',
   ],
   // ... другие правила ...
];

foreach ($rules as $r) {
   $maker = new \Bitrix\Main\UrlRewriterRuleMaker();
   $maker->process($r['SEF_RULE']);

   $arUrlRewrite[] = [
      'CONDITION' => $maker->getCondition(),
      'RULE'      => $maker->getRule(),
      'ID'        => '',
      'PATH'      => $r['COMPONENT_FILE'],
   ];
}

В итоге $arUrlRewrite наполнится готовыми массивами правил, которые останется только сохранить в urlrewrite.php.

4.3 Использование в пользовательском роутинге

Иногда в проектах на 1С-Битрикс требуется кастомный роутинг без стандартного механизма SEF. Например, вы сами пишете роутер, который анализирует URL, определяет нужный компонент или контроллер. Даже в этом случае UrlRewriterRuleMaker может пригодиться для быстрой сборки регулярного выражения:

// Пример "самописного" роутера
function customRouter($url)
{
    $router = new \Bitrix\Main\UrlRewriterRuleMaker();
    $router->process('/api/v1/#METHOD_NAME#/#PARAMS_PATH#/');

    $pattern = $router->getCondition(); // #^/api/v1/([^/]+?)/(.+?)\??(.*)#

    if (preg_match($pattern, $url, $matches)) {
        // $matches[1] => METHOD_NAME
        // $matches[2] => PARAMS_PATH
        // ...
        // Обработка ...
    } else {
        // 404 или другая логика
    }
}

Здесь класс помогает не вручную составлять регулярку под каждый параметр, а использовать единый шаблон SEF.

5. Резюме

Класс \Bitrix\Main\UrlRewriterRuleMaker — это удобный инструмент для разработчиков 1С-Битрикс, упрощающий работу с SEF-правилами. Его основные возможности:

Анализ шаблона SEF и автоматическая генерация регулярных выражений (CONDITION), позволяющих сопоставлять URL со структурой, заданной плейсхолдерами #VAR_NAME#.
Формирование строки RULE, отражающей, какие именно GET-параметры нужно записать при совпадении.
Поддержка _PATH# для жадного захвата нескольких подпапок.
Гибкая интеграция — класс можно использовать как в стандартных сценариях ЧПУ (запись в urlrewrite.php), так и в кастомном роутинге.

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

Не забывайте, что при обновлении/добавлении правил в urlrewrite.php требуется очистить кеш, чтобы изменения гарантированно вступили в силу.
Если вы используете стандартный компонент новостей (или любой другой с SEF_MODE), то в нём уже есть механизмы для автоматического формирования правил. Но в ряде случаев бывает удобнее (или нужно) управлять правилами вручную, и тут UrlRewriterRuleMaker — ваш помощник.

6. Заключение

Работа с ЧПУ — важная часть оптимизации сайта для пользователей и поисковых систем. Класс \Bitrix\Main\UrlRewriterRuleMaker избавляет от рутины ручного написания регулярных выражений и значительно ускоряет процесс настройки SEF. Используйте его возможности в паре с механикой 1С-Битрикс для написания чистых, удобных и легко поддерживаемых URL.

Надеемся, что это руководство поможет вам быстро освоить класс UrlRewriterRuleMaker и применять его во множестве сценариев разработки на 1С-Битрикс. Удачи в реализации проектов!

Теги: руководство, D7