{
  "index": 362,
  "slug": "bitrix-api-функция-для-генерации-кода-элемент",
  "title": "Bitrix API: как сгенерировать символьный код элемента и не сломать URL",
  "excerpt": "CUtil::translit создаёт только кандидата для CODE. Разбираем нормализацию, проверку уникальности, ограничение длины, обновление элемента и безопасное поведение при смене публичного адреса.",
  "contentHtml": "<p>В тестовом каталоге редактор импортирует два элемента с названием «Телефон Samsung». Оба получают кандидат <code>telefon-samsung</code>, а затем один и тот же код сохраняется в инфоблоке. Страница товара то открывает первую найденную карточку, то отдаёт 404 после смены правил маршрута. При массовом импорте такая ошибка превращается в дубли адресов и ручное восстановление ссылок.</p>\n<p>Есть и второй симптом. Редактор исправляет опечатку в названии опубликованного товара, обработчик снова вызывает генератор, а старая ссылка перестаёт вести на эту запись. Первое предположение — проблема в транслитерации. Проверка показывает другую границу: <code>CUtil::translit</code> преобразует строку, но не знает занятые коды, область поиска и судьбу уже опубликованного URL.</p>\n<p>Поэтому разделим две задачи. При создании элемента нужно получить нормализованный кандидат, проверить его в том же контексте, где работает каталог, и только потом сохранить. При редактировании уже опубликованной записи нужно отдельно решить, разрешена ли смена <code>CODE</code>. Это не косметика: код одновременно становится данными элемента и частью публичного адреса.</p>\n<h2>Что делает CUtil::translit</h2>\n<p><code>CUtil::translit</code> — статический метод старого API Bitrix с сигнатурой «строка, язык, параметры». Официальная документация описывает его как транслитерацию строки, а не как генератор уникального идентификатора. В параметрах можно явно задать максимальную длину, регистр, замену пробелов и прочих символов, а также удаление повторяющихся замен.</p>\n<p>Для русского названия в примере задаём язык <code>ru</code>, нижний регистр и дефис как замену. На входе «Телефон Samsung» получится читаемый кандидат. Но «Телефон Samsung» и «Телефон—Samsung» вполне могут привести к одному результату. Строка из знаков пунктуации может стать пустой, а ограничение <code>max_len</code> само по себе не добавит суффикс и не проверит его в базе.</p>\n<p>Есть ещё одна деталь для исторического примера. Исходная статья написана для legacy-классов Bitrix. В документации <code>CIBlockElement::GetList</code> отдельно отмечены изменения ключей и возможностей начиная с версии 18.6.200 модуля «Информационные блоки». Перед переносом кода в текущий проект нужно сверить версию модуля и фактический слой доступа; совпадение имени метода ещё не доказывает совпадение контракта.</p>\n<figure><img src=\"/assets/illustrations/bitrix-translit-api.svg\" alt=\"Поток создания CODE: название, транслитерация, нормализация, проверка уникальности и URL\" /><figcaption>Транслитерация даёт кандидата. Область уникальности, лимит длины и правило для старого URL задаёт приложение.</figcaption></figure>\n<h2>Где проверять уникальность</h2>\n<p>Область уникальности определяется не названием поля, а путём чтения. Если компонент ищет элемент по <code>IBLOCK_ID</code> и <code>CODE</code>, проверяйте именно эту пару. Если публичный маршрут добавляет раздел, сайт или язык, разберите фильтр компонента и решите, может ли один элемент принадлежать нескольким разделам. Одинаковые коды допустимы только тогда, когда полный маршрут действительно различает записи.</p>\n<p>Для простого каталога безопасное правило выглядит так: код уникален внутри конкретного инфоблока. Это не универсальная настройка SEO, а выбранный контракт примера. Если проект строит глобальный URL без раздела, область может оказаться шире инфоблока. Если код нужен ещё для API или импорта, эти потребители тоже должны быть учтены до первой публикации.</p>\n<p>При редактировании фильтр должен исключать ID текущего элемента. Иначе запись с уже сохранённым кодом будет считаться конфликтом сама с собой, и каждое сохранение начнёт превращать <code>item</code> в <code>item-2</code>, затем в <code>item-3</code>. Для нового элемента ID равен нулю, поэтому исключение не скрывает существующие записи.</p>\n<p>Нормализация должна завершаться до проверки: сжать повторные дефисы, удалить дефисы по краям и задать резервный префикс для пустого результата. Суффикс нужно учитывать в том же лимите. Если <code>max_len</code> равен 80, база длиной 80 символов плюс <code>-2</code> уже не укладывается в ограничение. Сначала оставьте место под суффикс, затем проверяйте готовый кандидат.</p>\n<h2>Симптом → причина → проверка → действие</h2>\n<div class=\"table-scroll\"><table><thead><tr><th scope=\"col\">Симптом</th><th scope=\"col\">Причина</th><th scope=\"col\">Проверка</th><th scope=\"col\">Действие</th></tr></thead><tbody><tr><td>Две карточки имеют один <code>CODE</code></td><td>Проверили только транслитерацию</td><td>Посчитать записи по той же области и коду</td><td>Добавлять суффикс до сохранения и исправить существующие конфликты</td></tr><tr><td>При редактировании код меняется сам</td><td>Генератор запускается для любого сохранения</td><td>Сравнить старый код, новый код и режим операции</td><td>Генерировать только при создании, пустом поле или явной команде</td></tr><tr><td>Код пустой или начинается с дефиса</td><td>После замены не осталось допустимых символов</td><td>Проверить результат после сжатия и обрезки</td><td>Выбрать резервный префикс и проверить его тем же запросом</td></tr><tr><td>Суффикс вышел за лимит длины</td><td>Лимит применили до добавления <code>-2</code></td><td>Проверить длину каждого готового кандидата</td><td>Оставлять место под суффикс до проверки уникальности</td></tr><tr><td>Проверка прошла, но запись конфликтует позже</td><td>Две операции выполняются параллельно</td><td>Повторить создание одновременно и разобрать ошибку записи</td><td>Сериализовать операцию или повторить выбор после отказа</td></tr><tr><td>Старый адрес отвечает 404</td><td>Опубликованный <code>CODE</code> изменили без миграции</td><td>Открыть старый URL и проверить маршрут</td><td>Сохранить историю адресов, настроить редирект или запретить смену</td></tr></tbody></table></div>\n<h2>Учебная реализация</h2>\n<p>Ниже — учебный вариант для legacy API. Функция <code>codeExists</code> оставлена отдельным адаптером, чтобы было видно её контракт: она ищет точный код в заданном инфоблоке и не считает конфликтом редактируемый элемент. Запрос на проверку не заменяет обработку ошибки записи.</p>\n<pre><code>&lt;?php\n\nfunction makeElementCode($name, $iblockId, $elementId = 0)\n{\n    $maxLength = 80;\n    $base = CUtil::translit((string)$name, 'ru', array(\n        'max_len' =&gt; $maxLength,\n        'change_case' =&gt; 'L',\n        'replace_space' =&gt; '-',\n        'replace_other' =&gt; '-',\n        'delete_repeat_replace' =&gt; true,\n    ));\n\n    $base = trim(preg_replace('/-+/', '-', $base), '-');\n    $base = $base !== '' ? $base : 'item';\n    $base = trim(substr($base, 0, $maxLength), '-');\n\n    for ($suffix = 1; $suffix &lt;= 1000; $suffix++) {\n        $suffixText = $suffix === 1 ? '' : '-' . $suffix;\n        $stemLength = $maxLength - strlen($suffixText);\n        $stem = rtrim(substr($base, 0, $stemLength), '-');\n        $candidate = $stem . $suffixText;\n\n        if (!codeExists($iblockId, $candidate, $elementId)) {\n            return $candidate;\n        }\n    }\n\n    throw new RuntimeException('Не найден свободный CODE за 1000 попыток');\n}\n\nfunction codeExists($iblockId, $code, $elementId = 0)\n{\n    $filter = array(\n        'IBLOCK_ID' =&gt; (int)$iblockId,\n        '=CODE' =&gt; $code,\n        '!ID' =&gt; (int)$elementId,\n    );\n\n    $result = CIBlockElement::GetList(\n        array(),\n        $filter,\n        false,\n        array('nTopCount' =&gt; 1),\n        array('ID')\n    );\n\n    return (bool)$result-&gt;Fetch();\n}</code></pre>\n<p>Вызов с <code>$suffix = 1</code> сначала проверяет исходный кандидат. При занятом <code>telefon-samsung</code> проверяются <code>telefon-samsung-2</code> и следующие значения. Перед каждой проверкой код уже укладывается в 80 символов. Ограничение в 1000 попыток — не гарантия свободного значения, а явный предел, после которого обработчик должен вернуть ошибку и привлечь оператора или отдельную стратегию импорта.</p>\n<p>В фильтре указаны тот же <code>IBLOCK_ID</code>, точное сравнение <code>=CODE</code> и исключение <code>!ID</code>. Если проект использует другой слой доступа, переносите не синтаксис целиком, а эти три условия. Сначала проверьте, что компонент и генератор считают область одинаково; иначе локально корректная функция всё равно даст конфликт на публичном маршруте.</p>\n<h2>Сохраняем и обновляем элемент</h2>\n<p>После генерации код передают в тот же массив полей, который используется для создания элемента. Метод <code>CIBlockElement::Add</code> возвращает ID при успехе и <code>false</code> при ошибке; текст причины доступен в <code>LAST_ERROR</code>. Поэтому результат нужно проверять, а не считать вызов успешным только потому, что запрос завершился без исключения.</p>\n<pre><code>&lt;?php\n\n$element = new CIBlockElement();\n$fields = array(\n    'IBLOCK_ID' =&gt; 12,\n    'NAME' =&gt; $name,\n    'CODE' =&gt; makeElementCode($name, 12),\n    'ACTIVE' =&gt; 'N',\n);\n\n$id = $element-&gt;Add($fields);\nif ($id === false) {\n    throw new RuntimeException($element-&gt;LAST_ERROR);\n}</code></pre>\n<p>Этот фрагмент не решает гонку. Два параллельных процесса могут оба увидеть свободный код между <code>GetList</code> и <code>Add</code>. Для последовательного ручного ввода этого наблюдения достаточно, но массовый импорт должен иметь дополнительный контракт: блокировку или очередь, транзакционную стратегию, доступное проекту ограничение либо повторный выбор кандидата после ошибки записи. Какой вариант допустим, зависит от версии Bitrix и базы данных; предварительную проверку нельзя называть атомарной гарантией.</p>\n<p>Для существующей опубликованной записи не пересчитывайте код при каждом изменении названия. Если поле уже заполнено, оставьте его, а новый код применяйте только при создании, пустом значении или явном согласованном действии. При намеренной смене сначала сохраните старый адрес и правило перехода, затем измените запись и проверьте оба URL. Операция <code>Update</code> также должна проверять возвращённый результат и <code>LAST_ERROR</code>.</p>\n<h2>Проверяем URL после записи</h2>\n<p>Перечитать элемент по <code>IBLOCK_ID</code> и <code>CODE</code> полезно, но этого недостаточно. Каталог может дополнительно фильтровать по активности, сайту, разделу или правам. Финальная проверка должна повторить путь чтения: получить ожидаемый ID, собрать фактический адрес тем же шаблоном и открыть его на тестовых данных.</p>\n<p>ЧПУ в Bitrix обрабатываются отдельными правилами сайта в <code>urlrewrite.php</code>. В режиме компонента с ЧПУ участвуют, среди прочего, <code>SEF_MODE</code> и <code>SEF_FOLDER</code>; порядок правил и их условие тоже влияют на результат. Поэтому смена функции транслитерации не исправит неправильную папку или более раннее совпадающее правило.</p>\n<p>Для опубликованного адреса заранее выберите одно из трёх состояний: код стабилен и не меняется вместе с названием; история старых кодов ведёт на текущую запись; старый путь намеренно закрывается с согласованным ответом. Нельзя одновременно обещать стабильный URL и автоматически строить его из редактируемого имени.</p>\n<h2>Порядок проверки</h2>\n<ol><li>Зафиксировать всех потребителей <code>CODE</code>: компонент, API, импорт, sitemap и внешние ссылки.</li><li>Определить область уникальности и проверить, совпадает ли она с фильтром публичного чтения.</li><li>Получить кандидата через <code>CUtil::translit</code> с явными языком, регистром, заменами и длиной.</li><li>Сжать повторные дефисы, убрать крайние дефисы и обработать пустой результат.</li><li>Оставить место под суффикс, проверить готовый кандидат и исключить ID текущего элемента.</li><li>При конфликте перебирать значения до явного лимита и не скрывать исчерпание попыток.</li><li>Передать код в <code>CIBlockElement::Add</code> или <code>Update</code>, проверить ID или <code>LAST_ERROR</code> и перечитать запись.</li><li>Открыть URL на тестовом элементе и отдельно проверить старый адрес опубликованной записи.</li><li>Для параллельного импорта воспроизвести гонку и проверить согласованный путь повторной записи.</li></ol>\n<h2>Отрицательные случаи и границы</h2>\n<p>Тест с одинаковыми названиями должен показать разные коды. Тест с изменением пробелов и знаков — одинакового кандидата до суффикса. Тест с пустым результатом — резервный <code>item</code>, прошедший ту же проверку. Тест с длинным именем и занятым первым кандидатом — готовый код не длиннее 80 символов. Повторное сохранение существующей записи должно сохранить её код.</p>\n<p>Отдельно проверьте связь с разделами. Если элемент может быть привязан к нескольким разделам, правило «уникально внутри раздела» может быть недостаточным для URL. Сначала зафиксируйте полный маршрут, затем выбирайте область проверки. Нельзя выводить область уникальности из одного поля формы.</p>\n<p>Суффикс подходит для технического разрешения совпадения, но не всегда подходит для бизнес-идентификатора. Для артикула, ключа поставщика или интеграции стабильнее использовать внешний идентификатор, а транслитерацию имени оставить запасным вариантом. Язык тоже задавайте явно: смена языка может создать другой код и новый публичный адрес.</p>\n<p>Решение готово, когда два одинаковых названия в выбранной области получают разные значения, существующий элемент не конфликтует сам с собой, длина каждого готового кода укладывается в контракт, ошибка параллельной записи не скрывается, а URL открывает именно ожидаемый ID. Для уже опубликованной записи поведение старого адреса должно быть проверено отдельно.</p>\n<h2>Проверяемые источники</h2>\n<ul><li><a href=\"https://dev.1c-bitrix.ru/api_help/main/reference/cutil/translit.php\" target=\"_blank\" rel=\"noopener\">Документация 1С-Битрикс: CUtil::translit</a> — сигнатура метода и параметры длины, регистра и замен.</li><li><a href=\"https://dev.1c-bitrix.ru/api_help/iblock/classes/ciblockelement/getlist.php?print=Y\" target=\"_blank\" rel=\"noopener\">Документация 1С-Битрикс: CIBlockElement::GetList</a> — фильтры <code>IBLOCK_ID</code>, <code>CODE</code>, <code>ID</code> и версияционные оговорки.</li><li><a href=\"https://dev.1c-bitrix.ru/api_help/iblock/classes/ciblockelement/add.php?print=Y\" target=\"_blank\" rel=\"noopener\">Документация 1С-Битрикс: CIBlockElement::Add</a> — поле <code>CODE</code>, возвращаемый ID и <code>LAST_ERROR</code>.</li><li><a href=\"https://dev.1c-bitrix.ru/api_help/main/general/urlrewrite.php\" target=\"_blank\" rel=\"noopener\">Документация 1С-Битрикс: обработка адресов</a> — <code>urlrewrite.php</code>, правила URL и параметры ЧПУ.</li></ul>"
}