Недокументированный Битрикс. Метод CIBlock::ReplaceDetailUrl() — полное руководство

CIBlock::ReplaceDetailUrl() — это «скрытый» помощник Битрикса, который заменяет плейс-холдеры в масках URL-ов элементов и разделов инфоблоков на реальные значения. Он понимает такие маркеры, как #SECTION_CODE_PATH#, #ELEMENT_CODE#, #SERVER_NAME#, умеет строить ссылку на товар через #PRODUCT_URL#, а в финале упорядочивает слэши, чтобы не было «/catalog///item/». Ниже — подробное описание работы функции и production-ready примеры.

Где лежит и как выглядит метод

Файл ядра: bitrix/modules/iblock/classes/general/iblock.php

public static function ReplaceDetailUrl(
    string $url,
    array  $arr,
    bool   $server_name = false,
    string $arrType = false   // 'E' — элемент, 'S' — раздел, любое|false — универсально
): string

Метод существует со времён Битрикс 9, но в официальной документации его до сих пор нет.

Поддерживаемые плейс-холдеры

Параметры метода

Полезные примеры (проверены на PHP 8.1 + Bitrix 23)

1. «Чистый» URL элемента на классическом API

<?php
$element = CIBlockElement::GetList(
    [],
    ['ID' => $ID],
    false,
    false,
    [
        'ID', 'IBLOCK_ID', 'IBLOCK_SECTION_ID',
        'DETAIL_PAGE_URL', 'CODE', 'EXTERNAL_ID',
        // эти поля нужны для плейс-холдеров
        'IBLOCK_TYPE_ID', 'IBLOCK_CODE', 'IBLOCK_EXTERNAL_ID',
    ]
)->GetNext();

$element['DETAIL_PAGE_URL'] = CIBlock::ReplaceDetailUrl(
    $element['DETAIL_PAGE_URL'], // маска
    $element,                    // данные
    true,                        // подставить SERVER_NAME
    'E'                          // работаем с элементом
);

// Результат: например https://site.ru/catalog/shoes/krossovki-nike/
echo $element['DETAIL_PAGE_URL'];
?>

2. D7-ORM: товар + SEO-чПУ

<?php
use Bitrix\Iblock\Elements\ElementCatalogTable;

$item = ElementCatalogTable::query()
    ->setSelect([
        '*',
        'IBLOCK.DETAIL_PAGE_URL',   // поле с маской
        'IBLOCK_SECTION_ID',
    ])
    ->where('ID', $productId)
    ->fetchObject();

$data = $item->collectValues(true);           // массив всех полей
$data['DETAIL_PAGE_URL'] = CIBlock::ReplaceDetailUrl(
    $data['IBLOCK_ELEMENT_DETAIL_PAGE_URL'],  // маска
    $data,
    true,
    'E'
);

echo $data['DETAIL_PAGE_URL'];
?>

3. Получить URL раздела (D7)

<?php
use Bitrix\Iblock\SectionTable;

$section = SectionTable::query()
    ->setSelect([
        '*',
        'IBLOCK.SECTION_PAGE_URL',
    ])
    ->where('ID', $sectionId)
    ->fetch();

$section['SECTION_PAGE_URL'] = CIBlock::ReplaceDetailUrl(
    $section['IBLOCK_SECTION_SECTION_PAGE_URL'],
    $section,
    true,
    'S'
);

echo $section['SECTION_PAGE_URL'];  // /catalog/shoes/
?>

4. Каноническая ссылка для OpenGraph

<?php
global $APPLICATION;

/** @var array $arResult из компонента news.detail */
$canonicalUrl = CIBlock::ReplaceDetailUrl(
    $arResult['DETAIL_PAGE_URL'],
    $arResult,
    true,
    'E'
);
$APPLICATION->SetPageProperty('og:url', $canonicalUrl);
?>

5. Мультиязычный магазин (ручная подстановка LANG_DIR)

<?php
$langDir = (defined('LANG_DIR_CUSTOM') ? LANG_DIR_CUSTOM : SITE_DIR);
$item['LANG_DIR'] = $langDir;

$link = CIBlock::ReplaceDetailUrl(
    $item['DETAIL_PAGE_URL'],
    $item,
    true,
    'E'
);
?>

Частые ошибки и их решения

Полезные приёмы

1. Обработка списка элементов и разделов. Если в одном запросе выводите и элементы, и разделы, сначала вызовите ReplaceDetailUrl() с типом 'S' для разделов, затем 'E' для элементов. Метод лёгкий и практически не влияет на производительность.
2. #PRODUCT_URL# для SKU. При выводе торговых предложений (SKU) подставляйте ссылку на товар-родитель, передавая массив данных товара в $arr и устанавливая $arrType = 'E'. Метод сам заменит плейс-холдер.
3. Удаление лишних слэшей. В самом конце функция выполняет preg_replace("'(?<!:)/+'s", '/', $url), убирая повторяющиеся слэши, но не трогая протокол https://.

Итог

CIBlock::ReplaceDetailUrl() — компактный инструмент ядра 1С-Битрикс, который экономит время при генерации дружелюбных URL-ов. Используйте его вместо ручных str_replace и регулярных выражений: передавайте корректный тип сущности, включайте SERVER_NAME, когда это нужно для SEO, и держите данные элемента/раздела в полном виде — метод сделает всё остальное.