{
  "index": 359,
  "slug": "editorial-2018-01-mechanism-bitrix-elements",
  "title": "CIBlockElement::Add в Bitrix: где проходит граница между событием и сервисом",
  "excerpt": "Разбираем путь создания элемента инфоблока: обработчики до и после Add, общий инвариант, диагностика LAST_ERROR и проверка результата без скрытой магии init.php.",
  "contentHtml": "<p>Скрипт вызывает <code>CIBlockElement::Add</code>, получает ID и завершает работу. Через несколько минут элемент находится в админке, но каталог его не показывает, импорт не объясняет отказ, а повторный запуск создаёт дубль. Причина часто не в шаблоне или кеше: часть правил скрыта в обработчиках событий, а часть не принадлежит этому вызову вовсе.</p>\n<p>Цена ошибки — не только одна неверная запись. Команда теряет исходные данные, повторяет операцию вслепую и рискует отправить наружу неполный товар. Если <code>Add</code> вернул ID, запись уже создана; ошибка последующей реакции не делает безопасным второй вызов. Если обработчик до записи изменил поля, вызывающий код мог не заметить это изменение. Поэтому число в результате — только одно доказательство.</p>\n<p>Граница проходит так: <code>Add</code> сохраняет элемент, сервис формирует намерение и диагностирует результат, обработчик до записи защищает общий инвариант, а обработчик после попытки передаёт результат отдельной реакции. Доступность в пользовательском сценарии подтверждается ещё одной выборкой с его реальными фильтрами.</p>\n<h2>Механизм: что происходит вокруг Add</h2>\n<p>Вызов начинается с массива полей. В нём обычно есть <code>IBLOCK_ID</code>, <code>NAME</code>, <code>CODE</code>, статус, раздел и <code>PROPERTY_VALUES</code>. Bitrix передаёт массив в обработчики до добавления по ссылке. Такой обработчик может изменить поля или отменить вставку, установив ошибку и вернув <code>false</code>.</p>\n<p>Если предварительная проверка не остановила операцию, метод добавляет элемент информационного блока. Свойства передаются через <code>PROPERTY_VALUES</code>; их ключом может быть числовой или символьный код, а формат значения зависит от типа свойства. При успехе <code>CIBlockElement::Add</code> возвращает ID, при ошибке — <code>false</code>, а текст доступен в <code>LAST_ERROR</code>.</p>\n<p>Здесь есть важная тонкость. <code>OnAfterIBlockElementAdd</code> вызывается после попытки добавления, в том числе когда обработчик <code>OnBeforeIBlockElementAdd</code> уже отменил вставку. В массиве обработчика нужно проверить <code>RESULT</code>: положительный ID означает созданный элемент, <code>false</code> — отказ; подробность ошибки передаётся в <code>RESULT_MESSAGE</code>. Только после этой проверки можно запускать реакцию для существующей записи.</p>\n<figure><img src='/assets/editorial/2018/bitrix-add-lifecycle.svg' alt='Путь создания элемента Bitrix: сервис, событие до попытки вставки, Add, проверка RESULT в событии после попытки и контрольная публичная выборка' loading='lazy' /><figcaption>Схема разделяет подготовку входа, попытку записи, диагностический обработчик и проверку пользовательского результата. Учебная иллюстрация не описывает конкретную production-конфигурацию.</figcaption></figure>\n<h2>Где должно жить правило</h2>\n<p>Сервис знает намерение операции. Он понимает, создаёт ли импорт черновик, форма — опубликованный материал, а миграция — временную запись. Поэтому сервис проверяет вход, задаёт значения по умолчанию, подготавливает свойства и связывает ошибку Bitrix с контекстом операции.</p>\n<p><code>OnBeforeIBlockElementAdd</code> видит каждый подходящий вызов и меняет входной массив по ссылке. Это подходящее место для инварианта, который нельзя нарушить ни из админки, ни из консольного скрипта, ни из конечной точки. Например, для одного инфоблока всегда нужен непустой <code>CODE</code>. Файл, цена или внешний HTTP-запрос конкретного импорта относятся к его сервису, а не к глобальному событию.</p>\n<p><code>OnAfterIBlockElementAdd</code> сначала должен разобрать результат попытки. При положительном <code>RESULT</code> он может записать ID в журнал, поставить фоновую задачу или обновить поиск. Если реакция после уже успешного <code>Add</code> не завершилась, повторяют реакцию по сохранённому ID, а не создают элемент заново. При отрицательном результате событие полезно для диагностики, но не должно изображать созданную запись.</p>\n<div class='table-scroll'><table><caption>Распределение ответственности в жизненном цикле</caption><thead><tr><th scope='col'>Участок</th><th scope='col'>Что проверяет</th><th scope='col'>Чего не делает</th></tr></thead><tbody><tr><td>Сервис</td><td>Вход, намерение, конфигурацию, внешний ключ и понятный результат</td><td>Не подменяет общий инвариант глобальным событием</td></tr><tr><td>OnBeforeIBlockElementAdd</td><td>Обязательное правило для данного инфоблока</td><td>Не выполняет правила одного импорта и тяжёлые HTTP-вызовы</td></tr><tr><td>Add</td><td>Пытается сохранить элемент и переданные свойства</td><td>Не обещает цену, остаток, URL и публичную видимость</td></tr><tr><td>OnAfterIBlockElementAdd</td><td>Разбирает RESULT и запускает реакцию только при созданной записи</td><td>Не превращает неудачную попытку в успешную запись</td></tr><tr><td>Контрольная выборка</td><td>Проверяет поля, свойства и фильтры потребителя</td><td>Не исправляет исходные данные автоматически</td></tr></tbody></table></div>\n<h2>Минимальный предохранитель до записи</h2>\n<p>Ниже — учебный пример для одного инфоблока. Идентификатор, регистрация события и текст ошибки должны соответствовать вашей конфигурации. Предохранитель проверяет только общий инвариант: он не создаёт <code>CODE</code> из названия и не делает сетевой запрос.</p>\n<pre><code>&lt;?php\n\nconst PRODUCT_IBLOCK_ID = 12;\n\nAddEventHandler(\n    'iblock',\n    'OnBeforeIBlockElementAdd',\n    array('CatalogElementGuard', 'beforeAdd')\n);\n\nfinal class CatalogElementGuard\n{\n    public static function beforeAdd(array &amp;$fields)\n    {\n        if ((int)($fields['IBLOCK_ID'] ?? 0) !== PRODUCT_IBLOCK_ID) {\n            return true;\n        }\n\n        if (trim((string)($fields['CODE'] ?? '')) === '') {\n            global $APPLICATION;\n            $APPLICATION-&gt;ThrowException(\n                'Для элемента каталога нужен символьный код'\n            );\n            return false;\n        }\n\n        return true;\n    }\n}</code></pre>\n<p>Возврат <code>false</code> здесь означает отказ до вставки только вместе с исключением через <code>ThrowException</code>. Вызывающий код всё равно обязан проверить результат <code>Add</code> и прочитать <code>LAST_ERROR</code>. Сообщение обработчика не обязано автоматически попасть в нужный журнал, ответ API или интерфейс администратора.</p>\n<h2>Сервис сохраняет контекст ошибки</h2>\n<p>Сервис не должен прятать массив полей за глобальным вызовом. Он принимает данные операции, проверяет обязательные значения и передаёт Bitrix подготовленный контракт. Внешний ключ нужен для повторного запуска: по нему можно решить, создавать запись, обновить черновик или остановиться с конфликтом.</p>\n<pre><code>&lt;?php\n\nfunction addCatalogElement(array $input): int\n{\n    if (!\\Bitrix\\Main\\Loader::includeModule('iblock')) {\n        throw new RuntimeException('Модуль iblock не подключён');\n    }\n\n    $name = trim((string)($input['name'] ?? ''));\n    $code = trim((string)($input['code'] ?? ''));\n    $externalId = trim((string)($input['externalId'] ?? ''));\n\n    if ($name === '' || $code === '' || $externalId === '') {\n        throw new InvalidArgumentException(\n            'Нужны name, code и externalId'\n        );\n    }\n\n    // Учебный пример: ID инфоблока и свойства заданы явно.\n    $fields = array(\n        'IBLOCK_ID' =&gt; PRODUCT_IBLOCK_ID,\n        'NAME' =&gt; $name,\n        'CODE' =&gt; $code,\n        'ACTIVE' =&gt; 'N',\n        'PROPERTY_VALUES' =&gt; array(\n            'EXTERNAL_ID' =&gt; $externalId,\n        ),\n    );\n\n    $element = new CIBlockElement();\n    $id = $element-&gt;Add($fields);\n\n    if ($id === false) {\n        throw new RuntimeException(\n            'Не удалось добавить элемент ' . $externalId . ': ' .\n            ($element-&gt;LAST_ERROR ?: 'причина не указана')\n        );\n    }\n\n    return (int)$id;\n}</code></pre>\n<p>Пример учебный. В нём нет транзакции внешней системы, блокировки от конкурентного импорта и политики повторов. Эти решения зависят от хранилища и контракта источника. Код показывает границу: ошибка <code>Add</code> становится явным исключением, а ID не выдаётся без проверки.</p>\n<h2>После попытки Add: результат важнее названия события</h2>\n<p>Имя <code>OnAfterIBlockElementAdd</code> легко прочитать как «после успешной записи», но это неточно. Обработчик вызывается после попытки и получает служебные поля результата. Поэтому его первая операция должна отделить два случая: <code>RESULT</code> содержит ID или равен <code>false</code>. В первом случае элемент можно читать и передавать в реакцию; во втором нужно работать с <code>RESULT_MESSAGE</code>, а не с несуществующей записью.</p>\n<p>Когда <code>Add</code> уже вернул ID, граница хранения пройдена. Сбой индексатора, журнала или фонового задания меняет статус реакции, но не превращает созданный элемент в новую задачу вставки. Для повторов сохраняйте внешний ключ, ID и состояние реакции. Иначе очередной запуск не отличит «запись уже есть, продолжить обработку» от «записи нет, создать».</p>\n<table><caption>Симптом → причина → проверка → действие</caption><thead><tr><th scope='col'>Симптом</th><th scope='col'>Причина</th><th scope='col'>Проверка</th><th scope='col'>Действие</th></tr></thead><tbody><tr><td><code>Add</code> вернул <code>false</code></td><td>Пустое поле, отказ обработчика, права или неверный инфоблок</td><td>Сохранить <code>LAST_ERROR</code>, внешний ключ и итоговый массив без секретов</td><td>Исправить контракт или обработчик; не повторять вслепую</td></tr><tr><td><code>OnAfter...</code> получил <code>RESULT=false</code></td><td>Попытка была отменена или завершилась ошибкой</td><td>Проверить <code>RESULT_MESSAGE</code> и не читать запись как созданную</td><td>Разобрать отказ до запуска реакции</td></tr><tr><td>ID есть, поле изменилось само</td><td><code>OnBeforeIBlockElementAdd</code> переписал массив по ссылке</td><td>Сравнить поля до вызова с данными контрольного чтения</td><td>Оставить изменение только для общего правила или перенести его в сервис</td></tr><tr><td>Элемент есть, свойства пусты</td><td>Неверный код свойства, формат значения или неполный массив</td><td>Прочитать конкретные свойства по ID и сверить тип</td><td>Исправить <code>PROPERTY_VALUES</code>; не маскировать сбой новым <code>Add</code></td></tr><tr><td>Элемент есть в админке, но не в каталоге</td><td>Публичный фильтр исключает статус, дату, раздел, права или зависимые данные</td><td>Повторить выборку с фильтрами компонента</td><td>Исправить данные или фильтр; кеш проверять последним</td></tr><tr><td>После сбоя появился дубль</td><td>Повторный запуск не проверяет внешний ключ</td><td>Найти записи по внешнему идентификатору и журналу операции</td><td>Ввести идемпотентность до вызова <code>Add</code></td></tr><tr><td>ID есть, реакция не завершилась</td><td>Ошибка в обработчике после попытки или отдельном процессе</td><td>Разделить лог записи и лог реакции по одному ID</td><td>Повторить реакцию, не создавая элемент заново</td></tr></tbody></table>\n<h2>Свойства и отрицательный путь</h2>\n<p><code>PROPERTY_VALUES</code> удобно передавать вместе с обязательными полями при создании. Но массив должен соответствовать реальным кодам и типам свойств. Множественное свойство, список, файл и связь с элементом имеют разные форматы. Строка для <code>EXTERNAL_ID</code> в учебном примере не доказывает, что такой формат подходит вашему инфоблоку.</p>\n<p>Документация отдельно предупреждает: если при сохранении через <code>Add</code> передать не все свойства, остальные значения могут быть удалены. Для точечного изменения уже существующего элемента подходит <code>SetPropertyValuesEx</code>: он принимает только изменяемые свойства и сохраняет неуказанные. Но результат нужно проверить чтением, а формат списка, файла или пустого множественного свойства — сверить с типом свойства.</p>\n<p>Отрицательный путь начинается там, где правило не выполняется. Нет внешнего ключа — операция останавливается до Bitrix. Нет обязательного <code>CODE</code> — сервис возвращает понятный отказ, а общий обработчик остаётся последней защитой. <code>Add</code> вернул <code>false</code> — запись не считается созданной. <code>RESULT</code> содержит ID, но реакция упала — запись считается созданной, а реакция получает отдельный статус.</p>\n<h2>Порядок проверки</h2>\n<ol><li>Опишите источник операции: форма, импорт, консольный скрипт или конечная точка. Запишите внешний ключ и ожидаемое состояние элемента.</li><li>Проверьте обязательные поля и свойства до вызова Bitrix. Отдельно зафиксируйте значения, которые может изменить обработчик.</li><li>Найдите все обработчики <code>OnBeforeIBlockElementAdd</code> и <code>OnAfterIBlockElementAdd</code> для этого инфоблока. Для каждого запишите изменение, отказ и побочный эффект.</li><li>Вызовите <code>Add</code> с минимальным массивом, который соответствует контракту инфоблока. Не делайте элемент активным до заполнения зависимых данных.</li><li>Проверьте результат строго: положительный ID — успех записи, <code>false</code> — отказ. В обработчике после попытки дополнительно проверьте <code>RESULT</code> и <code>RESULT_MESSAGE</code>.</li><li>Прочитайте элемент по ID без публичных ограничений. Проверьте поля, раздел и каждое обязательное свойство.</li><li>Повторите запрос с фильтрами потребителя: активность, даты, права, раздел и товарные данные, если они участвуют в каталоге.</li><li>Проверьте реакцию после записи по тому же ID. Если она не завершилась, поставьте отдельный статус и повторяйте реакцию, а не создание.</li><li>Только после всех проверок переведите элемент в состояние, в котором его должен видеть пользователь.</li></ol>\n<h2>Ограничения и критерий готовности</h2>\n<p>События Bitrix глобальны в пределах приложения. Один обработчик может влиять на админку, импорт и консольный скрипт. Поэтому широкое условие в <code>init.php</code> опаснее локальной проверки сервиса. Ограничивайте обработчик инфоблоком и фиксируйте его контракт рядом с регистрацией.</p>\n<p>Успешный <code>Add</code> не проверяет весь каталог. Цена, остаток, торговое предложение, права, кеш, поиск и URL могут жить в других слоях. Не приписывайте методу эффект, которого он не обещает. Контрольная выборка должна повторять реальный фильтр компонента, иначе она докажет только чтение из другого сценария.</p>\n<p>Работа готова, если другой разработчик может показать четыре доказательства: вызов либо принялся, либо отказал с текстом причины; созданный ID читается с ожидаемыми полями и свойствами; запись проходит публичную выборку с фильтрами потребителя; повтор после сбоя реакции не создаёт новый элемент. В журнале остаются внешний ключ, ID, итоговый статус и причина отказа, если она была.</p>\n<p>Если есть только ID из ответа, готовности нет. Если админка показывает элемент, а контрольный запрос каталога его исключает, готовности нет. Если событие вызвано после неудачной попытки, но код обработал его как успешную запись, готовности нет. Эти результаты указывают на следующий слой проверки, а не на необходимость повторного <code>Add</code>.</p>\n<h2>Проверяемые источники</h2>\n<ul><li><a href='https://dev.1c-bitrix.ru/api_help/iblock/classes/ciblockelement/add.php?print=Y' target='_blank' rel='noopener noreferrer'>Документация Bitrix: CIBlockElement::Add</a> — поля, <code>PROPERTY_VALUES</code>, обработчики, возвращаемый ID и <code>LAST_ERROR</code>.</li><li><a href='https://dev.1c-bitrix.ru/api_help/iblock/events/onbeforeiblockelementadd.php' target='_blank' rel='noopener noreferrer'>Документация Bitrix: OnBeforeIBlockElementAdd</a> — изменение полей по ссылке и отмена вставки с ошибкой.</li><li><a href='https://dev.1c-bitrix.ru/api_help/iblock/events/onafteriblockelementadd.php' target='_blank' rel='noopener noreferrer'>Документация Bitrix: OnAfterIBlockElementAdd</a> — вызов после попытки, поля <code>RESULT</code> и <code>RESULT_MESSAGE</code>.</li><li><a href='https://dev.1c-bitrix.ru/api_help/iblock/classes/ciblockelement/setpropertyvaluesex.php' target='_blank' rel='noopener noreferrer'>Документация Bitrix: CIBlockElement::SetPropertyValuesEx</a> — частичное сохранение значений свойств.</li></ul>"
}