![\"Путь](\"/assets/editorial/2018/bitrix-add-lifecycle.svg\")
Скрипт вызывает CIBlockElement::Add, получает ID и завершает работу. Через несколько минут элемент находится в админке, но каталог не показывает его, импорт не объясняет отказ, а повторный запуск создаёт дубль. Разработчик ищет проблему в шаблоне или кеше. На самом деле часть правил уже выполнил обработчик события, часть не выполнил никто.
Цена такой ошибки — не только одна неверная запись. Команда теряет исходные данные, повторяет операцию вслепую и рискует отправить наружу неполный товар. Если событие после добавления упало, ID уже существует. Если событие до добавления изменило поля, вызывающий код мог не знать об этом. Поэтому одного факта «метод вернул число» недостаточно.
\\nТезис статьи простой: Add — граница записи, а не готовый бизнес-сценарий. Сервис должен подготовить вход, вызвать метод и вернуть диагностируемую ошибку. Обработчик до записи должен защищать только общий инвариант. Обработчик после записи должен запускать отдельную реакцию. Публичную готовность нужно подтвердить отдельной выборкой.
Вызов начинается с массива полей. В нём обычно есть IBLOCK_ID, NAME, CODE, статус, раздел и PROPERTY_VALUES. Bitrix передаёт эти данные в обработчики события до добавления. Обработчик может изменить массив или отменить операцию с сообщением об ошибке.
Если проверка проходит, Bitrix записывает элемент и свойства. При успехе объект CIBlockElement возвращает ID. При ошибке он возвращает false, а причина доступна в LAST_ERROR. После записи вызывается событие OnAfterIBlockElementAdd. Это уже другой этап: элемент существует, даже если последующая реакция не завершилась.
Из этого следуют три разных результата. Первый — запись отклонена до сохранения. Второй — элемент сохранён, но зависимые действия ещё не завершены. Третий — элемент прошёл публичную выборку и готов для пользователя. Нельзя называть эти состояния одним словом «успех».
\\nСервис знает намерение операции. Он понимает, создаёт ли импорт черновик, форма — опубликованный материал, а миграция — временную запись. Поэтому сервис проверяет вход, задаёт значения по умолчанию, подготавливает свойства и связывает ошибку Bitrix с контекстом операции.
\\nOnBeforeIBlockElementAdd видит каждый подходящий вызов. Это хорошее место для инварианта, который нельзя нарушить ни из админки, ни из CLI, ни из endpoint. Например, для одного инфоблока всегда нужен непустой CODE. Но обработчик не знает, нужен ли конкретному импорту файл, цена или внешний HTTP-запрос. Эти правила относятся к вызывающей операции.
Событие после записи подходит для журнала, постановки фоновой задачи или обновления поискового индекса. Оно не должно молча менять смысл успешного Add. Если побочный шаг обязателен перед публикацией, храните состояние «элемент сохранён» отдельно от состояния «элемент готов». Тогда повторный запуск не создаст новую запись только потому, что индексатор временно не ответил.
| Участок | Что проверяет | Чего не делает |
|---|---|---|
| Сервис | Вход, намерение, конфигурацию, внешний ключ и понятный результат | Не подменяет общий инвариант глобальным событием |
| OnBeforeIBlockElementAdd | Обязательное правило для данного инфоблока | Не выполняет тяжёлые HTTP-вызовы и правила одного экрана |
| Add | Сохраняет элемент и переданные свойства | Не обещает цену, остаток, URL и публичную видимость |
| OnAfterIBlockElementAdd | Запускает реакцию после записи и фиксирует ID | Не отменяет уже сохранённую запись чистым возвратом |
| Контрольная выборка | Проверяет поля, свойства и фильтры потребителя | Не исправляет исходные данные автоматически |
Ниже — учебный пример для одного инфоблока. Он не является готовым обработчиком для любого проекта: идентификатор, регистрация события и текст ошибки должны соответствовать вашей конфигурации. Предохранитель проверяет только общий инвариант. Он не создаёт CODE из названия и не делает сетевой запрос.
<?php\\n\\nconst PRODUCT_IBLOCK_ID = 12;\\n\\nAddEventHandler(\\n \"iblock\",\\n \"OnBeforeIBlockElementAdd\",\\n [CatalogElementGuard::class, \"beforeAdd\"]\\n);\\n\\nfinal class CatalogElementGuard\\n{\\n public static function beforeAdd(array &$fields): bool\\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->ThrowException(\\n \"Для элемента каталога нужен символьный код\"\\n );\\n return false;\\n }\\n\\n return true;\\n }\\n}Возврат false здесь означает отказ до записи. Вызывающий код всё равно обязан проверить результат Add и прочитать LAST_ERROR. Нельзя считать, что сообщение из обработчика автоматически попадёт в нужный журнал, ответ API или интерфейс администратора.
Сервис не должен прятать массив полей за глобальным вызовом. Он принимает данные операции, проверяет обязательные значения и передаёт Bitrix только подготовленный контракт. Внешний ключ нужен для повторного запуска: по нему можно решить, создавать запись, обновить черновик или остановиться с конфликтом.
\\n<?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 = [\\n \"IBLOCK_ID\" => PRODUCT_IBLOCK_ID,\\n \"NAME\" => $name,\\n \"CODE\" => $code,\\n \"ACTIVE\" => \"N\",\\n \"PROPERTY_VALUES\" => [\\n \"EXTERNAL_ID\" => $externalId,\\n ],\\n ];\\n\\n $element = new CIBlockElement();\\n $id = $element->Add($fields);\\n\\n if ($id === false) {\\n throw new RuntimeException(\\n \"Не удалось добавить элемент \" . $externalId . \": \" .\\n ($element->LAST_ERROR ?: \"причина не указана\")\\n );\\n }\\n\\n return (int)$id;\\n}Пример учебный. В нём нет транзакции внешней системы, блокировки от конкурентного импорта и политики повторов. В production эти решения зависят от хранилища и контракта источника. Код показывает только границу: ошибка Add становится явным исключением, а ID не выдаётся без проверки.
| Симптом | Причина | Проверка | Действие |
|---|---|---|---|
Add вернул false | Пустое поле, отказ обработчика, права или неверный инфоблок | Сохранить LAST_ERROR, входной внешний ключ и итоговый массив без секретов | Исправить контракт или обработчик; повторять только после понимания отказа |
| ID есть, поле изменилось само | OnBeforeIBlockElementAdd переписал массив | Сравнить поля до вызова с данными контрольного чтения | Оставить изменение только для общего правила или перенести его в сервис |
| Элемент есть, свойства пусты | Неверный код свойства, формат значения или неполный массив | Прочитать конкретные свойства по ID и сверить тип свойства | Исправить PROPERTY_VALUES; не маскировать сбой повторным Add |
| Элемент есть в админке, но не в каталоге | Публичный фильтр исключает статус, дату, раздел, права или зависимые данные | Повторить выборку с фильтрами компонента | Исправить данные или фильтр; кеш проверять последним |
| После сбоя появился дубль | Повторный запуск не проверяет внешний ключ | Найти записи по внешнему идентификатору и журналу операции | Ввести правило идемпотентности до вызова Add |
| Сервис вернул ID, а индекс не обновился | Ошибка в OnAfterIBlockElementAdd или отдельном обработчике | Разделить лог записи и лог реакции после записи | Повторить реакцию по сохранённому ID, не создавать элемент заново |
PROPERTY_VALUES удобно передавать вместе с обязательными полями при создании. Но массив должен соответствовать реальным кодам и типам свойств. Множественное свойство, список, файл и связь с элементом имеют разные форматы. Учебный массив со строкой не доказывает, что такой же формат подходит вашему инфоблоку.
Нельзя использовать точечное обновление как сигнал успеха без чтения результата. Если после создания нужно изменить одно свойство, применяйте поддерживаемый для вашей версии метод и затем читайте это свойство контрольным запросом. Не передавайте неполный набор в операцию, которая может затронуть остальные значения, пока не проверили её семантику на тестовом инфоблоке.
\\nОтрицательный путь начинается там, где правило не выполняется. Нет внешнего ключа — операция останавливается до Bitrix. Нет обязательного CODE — сервис возвращает понятный отказ, а общий обработчик остаётся последней защитой. Add вернул false — запись не считается созданной. ID есть, но после-обработчик упал — запись считается созданной, а реакция получает отдельный статус. Не превращайте эти случаи в один повтор.
OnBeforeIBlockElementAdd и OnAfterIBlockElementAdd для этого инфоблока. Для каждого запишите изменение, отказ и побочный эффект.Add с минимальным массивом, который соответствует контракту инфоблока. Не делайте элемент активным до заполнения зависимых данных.false — отказ. При отказе сохраните LAST_ERROR и не запускайте повтор вслепую.События Bitrix глобальны в пределах приложения. Один обработчик может влиять на админку, импорт и консольный скрипт. Поэтому широкое условие в init.php опаснее локальной проверки сервиса. Ограничивайте обработчик инфоблоком и фиксируйте его контракт рядом с регистрацией.
Успешный Add не проверяет весь каталог. Цена, остаток, торговое предложение, права, кеш, поиск и URL могут жить в других слоях. Не приписывайте методу эффект, которого он не обещает. Контрольная выборка должна повторять реальные фильтры компонента.
Проверка на тестовом инфоблоке не доказывает production-результат. Она подтверждает только выбранный сценарий и формат данных. Конкурентные импорты, права пользователя, версия Bitrix и конфигурация обработчиков требуют отдельных проверок. Если среда не позволяет их проверить, назовите это ограничением.
\\nРабота готова, если другой разработчик без автора может показать четыре доказательства: вызов либо принялся, либо отказал с текстом причины; созданный ID читается с ожидаемыми полями и свойствами; запись проходит публичную выборку с фильтрами потребителя; повтор после сбоя реакции не создаёт новый элемент. В журнале остаются внешний ключ, ID, итоговый статус и причина отказа, если она была.
\\nЕсли есть только ID из ответа, готовности нет. Если админка показывает элемент, но контрольный запрос каталога его исключает, готовности нет. Если событие после записи запускает побочный процесс, но его ошибка теряется, готовности нет. Эти отрицательные результаты не требуют очистки кеша или повторного Add; они указывают на следующий слой проверки.
PROPERTY_VALUES, обработчики, возвращаемый ID и LAST_ERROR.Скрипт вызывает CIBlockElement::Add, получает ID и завершает работу. Через несколько минут элемент находится в админке, но каталог его не показывает, импорт не объясняет отказ, а повторный запуск создаёт дубль. Причина часто не в шаблоне или кеше: часть правил скрыта в обработчиках событий, а часть не принадлежит этому вызову вовсе.
Цена ошибки — не только одна неверная запись. Команда теряет исходные данные, повторяет операцию вслепую и рискует отправить наружу неполный товар. Если Add вернул ID, запись уже создана; ошибка последующей реакции не делает безопасным второй вызов. Если обработчик до записи изменил поля, вызывающий код мог не заметить это изменение. Поэтому число в результате — только одно доказательство.
Граница проходит так: Add сохраняет элемент, сервис формирует намерение и диагностирует результат, обработчик до записи защищает общий инвариант, а обработчик после попытки передаёт результат отдельной реакции. Доступность в пользовательском сценарии подтверждается ещё одной выборкой с его реальными фильтрами.
Вызов начинается с массива полей. В нём обычно есть IBLOCK_ID, NAME, CODE, статус, раздел и PROPERTY_VALUES. Bitrix передаёт массив в обработчики до добавления по ссылке. Такой обработчик может изменить поля или отменить вставку, установив ошибку и вернув false.
Если предварительная проверка не остановила операцию, метод добавляет элемент информационного блока. Свойства передаются через PROPERTY_VALUES; их ключом может быть числовой или символьный код, а формат значения зависит от типа свойства. При успехе CIBlockElement::Add возвращает ID, при ошибке — false, а текст доступен в LAST_ERROR.
Здесь есть важная тонкость. OnAfterIBlockElementAdd вызывается после попытки добавления, в том числе когда обработчик OnBeforeIBlockElementAdd уже отменил вставку. В массиве обработчика нужно проверить RESULT: положительный ID означает созданный элемент, false — отказ; подробность ошибки передаётся в RESULT_MESSAGE. Только после этой проверки можно запускать реакцию для существующей записи.
Сервис знает намерение операции. Он понимает, создаёт ли импорт черновик, форма — опубликованный материал, а миграция — временную запись. Поэтому сервис проверяет вход, задаёт значения по умолчанию, подготавливает свойства и связывает ошибку Bitrix с контекстом операции.
\nOnBeforeIBlockElementAdd видит каждый подходящий вызов и меняет входной массив по ссылке. Это подходящее место для инварианта, который нельзя нарушить ни из админки, ни из консольного скрипта, ни из конечной точки. Например, для одного инфоблока всегда нужен непустой CODE. Файл, цена или внешний HTTP-запрос конкретного импорта относятся к его сервису, а не к глобальному событию.
OnAfterIBlockElementAdd сначала должен разобрать результат попытки. При положительном RESULT он может записать ID в журнал, поставить фоновую задачу или обновить поиск. Если реакция после уже успешного Add не завершилась, повторяют реакцию по сохранённому ID, а не создают элемент заново. При отрицательном результате событие полезно для диагностики, но не должно изображать созданную запись.
| Участок | Что проверяет | Чего не делает |
|---|---|---|
| Сервис | Вход, намерение, конфигурацию, внешний ключ и понятный результат | Не подменяет общий инвариант глобальным событием |
| OnBeforeIBlockElementAdd | Обязательное правило для данного инфоблока | Не выполняет правила одного импорта и тяжёлые HTTP-вызовы |
| Add | Пытается сохранить элемент и переданные свойства | Не обещает цену, остаток, URL и публичную видимость |
| OnAfterIBlockElementAdd | Разбирает RESULT и запускает реакцию только при созданной записи | Не превращает неудачную попытку в успешную запись |
| Контрольная выборка | Проверяет поля, свойства и фильтры потребителя | Не исправляет исходные данные автоматически |
Ниже — учебный пример для одного инфоблока. Идентификатор, регистрация события и текст ошибки должны соответствовать вашей конфигурации. Предохранитель проверяет только общий инвариант: он не создаёт CODE из названия и не делает сетевой запрос.
<?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 &$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->ThrowException(\n 'Для элемента каталога нужен символьный код'\n );\n return false;\n }\n\n return true;\n }\n}Возврат false здесь означает отказ до вставки только вместе с исключением через ThrowException. Вызывающий код всё равно обязан проверить результат Add и прочитать LAST_ERROR. Сообщение обработчика не обязано автоматически попасть в нужный журнал, ответ API или интерфейс администратора.
Сервис не должен прятать массив полей за глобальным вызовом. Он принимает данные операции, проверяет обязательные значения и передаёт Bitrix подготовленный контракт. Внешний ключ нужен для повторного запуска: по нему можно решить, создавать запись, обновить черновик или остановиться с конфликтом.
\n<?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' => PRODUCT_IBLOCK_ID,\n 'NAME' => $name,\n 'CODE' => $code,\n 'ACTIVE' => 'N',\n 'PROPERTY_VALUES' => array(\n 'EXTERNAL_ID' => $externalId,\n ),\n );\n\n $element = new CIBlockElement();\n $id = $element->Add($fields);\n\n if ($id === false) {\n throw new RuntimeException(\n 'Не удалось добавить элемент ' . $externalId . ': ' .\n ($element->LAST_ERROR ?: 'причина не указана')\n );\n }\n\n return (int)$id;\n}Пример учебный. В нём нет транзакции внешней системы, блокировки от конкурентного импорта и политики повторов. Эти решения зависят от хранилища и контракта источника. Код показывает границу: ошибка Add становится явным исключением, а ID не выдаётся без проверки.
Имя OnAfterIBlockElementAdd легко прочитать как «после успешной записи», но это неточно. Обработчик вызывается после попытки и получает служебные поля результата. Поэтому его первая операция должна отделить два случая: RESULT содержит ID или равен false. В первом случае элемент можно читать и передавать в реакцию; во втором нужно работать с RESULT_MESSAGE, а не с несуществующей записью.
Когда Add уже вернул ID, граница хранения пройдена. Сбой индексатора, журнала или фонового задания меняет статус реакции, но не превращает созданный элемент в новую задачу вставки. Для повторов сохраняйте внешний ключ, ID и состояние реакции. Иначе очередной запуск не отличит «запись уже есть, продолжить обработку» от «записи нет, создать».
| Симптом | Причина | Проверка | Действие |
|---|---|---|---|
Add вернул false | Пустое поле, отказ обработчика, права или неверный инфоблок | Сохранить LAST_ERROR, внешний ключ и итоговый массив без секретов | Исправить контракт или обработчик; не повторять вслепую |
OnAfter... получил RESULT=false | Попытка была отменена или завершилась ошибкой | Проверить RESULT_MESSAGE и не читать запись как созданную | Разобрать отказ до запуска реакции |
| ID есть, поле изменилось само | OnBeforeIBlockElementAdd переписал массив по ссылке | Сравнить поля до вызова с данными контрольного чтения | Оставить изменение только для общего правила или перенести его в сервис |
| Элемент есть, свойства пусты | Неверный код свойства, формат значения или неполный массив | Прочитать конкретные свойства по ID и сверить тип | Исправить PROPERTY_VALUES; не маскировать сбой новым Add |
| Элемент есть в админке, но не в каталоге | Публичный фильтр исключает статус, дату, раздел, права или зависимые данные | Повторить выборку с фильтрами компонента | Исправить данные или фильтр; кеш проверять последним |
| После сбоя появился дубль | Повторный запуск не проверяет внешний ключ | Найти записи по внешнему идентификатору и журналу операции | Ввести идемпотентность до вызова Add |
| ID есть, реакция не завершилась | Ошибка в обработчике после попытки или отдельном процессе | Разделить лог записи и лог реакции по одному ID | Повторить реакцию, не создавая элемент заново |
PROPERTY_VALUES удобно передавать вместе с обязательными полями при создании. Но массив должен соответствовать реальным кодам и типам свойств. Множественное свойство, список, файл и связь с элементом имеют разные форматы. Строка для EXTERNAL_ID в учебном примере не доказывает, что такой формат подходит вашему инфоблоку.
Документация отдельно предупреждает: если при сохранении через Add передать не все свойства, остальные значения могут быть удалены. Для точечного изменения уже существующего элемента подходит SetPropertyValuesEx: он принимает только изменяемые свойства и сохраняет неуказанные. Но результат нужно проверить чтением, а формат списка, файла или пустого множественного свойства — сверить с типом свойства.
Отрицательный путь начинается там, где правило не выполняется. Нет внешнего ключа — операция останавливается до Bitrix. Нет обязательного CODE — сервис возвращает понятный отказ, а общий обработчик остаётся последней защитой. Add вернул false — запись не считается созданной. RESULT содержит ID, но реакция упала — запись считается созданной, а реакция получает отдельный статус.
OnBeforeIBlockElementAdd и OnAfterIBlockElementAdd для этого инфоблока. Для каждого запишите изменение, отказ и побочный эффект.Add с минимальным массивом, который соответствует контракту инфоблока. Не делайте элемент активным до заполнения зависимых данных.false — отказ. В обработчике после попытки дополнительно проверьте RESULT и RESULT_MESSAGE.События Bitrix глобальны в пределах приложения. Один обработчик может влиять на админку, импорт и консольный скрипт. Поэтому широкое условие в init.php опаснее локальной проверки сервиса. Ограничивайте обработчик инфоблоком и фиксируйте его контракт рядом с регистрацией.
Успешный Add не проверяет весь каталог. Цена, остаток, торговое предложение, права, кеш, поиск и URL могут жить в других слоях. Не приписывайте методу эффект, которого он не обещает. Контрольная выборка должна повторять реальный фильтр компонента, иначе она докажет только чтение из другого сценария.
Работа готова, если другой разработчик может показать четыре доказательства: вызов либо принялся, либо отказал с текстом причины; созданный ID читается с ожидаемыми полями и свойствами; запись проходит публичную выборку с фильтрами потребителя; повтор после сбоя реакции не создаёт новый элемент. В журнале остаются внешний ключ, ID, итоговый статус и причина отказа, если она была.
\nЕсли есть только ID из ответа, готовности нет. Если админка показывает элемент, а контрольный запрос каталога его исключает, готовности нет. Если событие вызвано после неудачной попытки, но код обработал его как успешную запись, готовности нет. Эти результаты указывают на следующий слой проверки, а не на необходимость повторного Add.
PROPERTY_VALUES, обработчики, возвращаемый ID и LAST_ERROR.RESULT и RESULT_MESSAGE.