Как записать свойства элемента инфоблока в Битрикс через SetPropertyValues?

Импорт вызвал SetPropertyValues($id, $iblockId, ['PRICE' => 999]) без четвертого параметра - в админке пропали бренд, фото и артикул. Каталог опустел, бекап спас ситуацию. Без PROPERTY_CODE метод ждет полный набор и стирает неуказанные свойства. Ниже - decision-tree: SetPropertyValues с 4-м параметром, SetPropertyValuesEx, SetPropertyValueCode и ловушка Update(PROPERTY_VALUES). Получите чек-лист записи без сброса остальных полей.

CIBlockElement::SetPropertyValues, SetPropertyValuesEx и SetPropertyValueCode - три способа программно записать свойства элемента инфоблока в 1С-Битрикс: полная перезапись (опасно без полного набора), частичное обновление по CODE и запись одного свойства по символьному коду соответственно. Сегодня: прочитайте текущие свойства через GetProperty, выберите метод по таблице ниже, передавайте enum ID для списков, и после записи сверьте незатронутые поля.

Речь про 1С-Битрикс: Управление сайтом на вашем хостинге, не про Bitrix24 CRM. Свойства элемента - цена, бренд, фото, артикул в карточке товара или новости. Сначала прочитайте карточку через GetPropertyValues и GetList, затем записывайте. Создали элемент через CIBlockElement::Add - эта статья про обновление уже существующей записи.

Разберите, почему SetPropertyValues сбрасывает остальные свойства

Официальная справка CIBlockElement::SetPropertyValues прямо говорит: если четвертый параметр PROPERTY_CODE не передан, массив PROPERTY_VALUES должен содержать полный набор свойств элемента. Все неуказанные свойства удаляются из базы. Это не баг, а контракт метода.

Та же логика у CIBlockElement::Update с PROPERTY_VALUES: передали только PRICE - остальные обнулятся. Типичный кейс: меняют SORT через Update и случайно кладут неполный PROPERTY_VALUES.

Сделайте: для точечной правки одного поля передавайте четвертый параметр PROPERTY_CODE или используйте SetPropertyValuesEx. Не делайте: SetPropertyValues($id, $ib, ['PRICE' => 999]) без CODE - получите "пустой" каталог.

Что такое SetPropertyValues, SetPropertyValuesEx и SetPropertyValueCode

Три статические методы класса CIBlockElement отвечают на вопрос "как записать свойство элемента инфоблока битрикс программно":

• SetPropertyValues - базовый метод. Без 4-го параметра = полная перезапись всех свойств. С 4-м параметром PROPERTY_CODE = обновление одного свойства по ID или символьному коду.
• SetPropertyValuesEx (с версии 6.0.0) - частичное обновление: неуказанные свойства сохраняются. Рекомендуемый выбор для импорта и cron.
• SetPropertyValueCode - записать одно свойство по символьному коду без IBLOCK_ID в вызове. Удобен для быстрых сниппетов, но для файлов работает иначе чем Ex.

Нужны эти методы, когда PHP-код, агент по расписанию (cron) или REST-обработчик меняет свойства без ручной правки в админке. Не нужны, если правите одну карточку глазами - админка безопаснее для разовых задач.

Выберите метод записи: таблица и decision-tree

Схема выбора:
Прочитали GetProperty → одно свойство? → SetPropertyValues+CODE или SetPropertyValueCode → несколько по CODE? → SetPropertyValuesEx → нужна полная замена? → SetPropertyValues без CODE (с полным массивом) → меняете SORT/NAME? → Update без PROPERTY_VALUES + Ex для свойств

Детали Update и PROPERTY_VALUES - в гайде по CIBlockElement::Update, здесь фокус на write-API.

Обновите одно свойство через 4-й параметр PROPERTY_CODE

Когда нужно изменить только цену или артикул, четвертый параметр SetPropertyValues превращает опасный метод в безопасный:

1. Прочитайте baseline: GetProperty($iblockId, $elementId) или GetPropertyValues - зафиксируйте текущие BRAND, PHOTOS, ARTICLE.
2. Подготовьте массив: только целевое свойство, например ['PRICE' => 999] или ['n123' => 999] по ID свойства.
3. Вызовите с CODE: CIBlockElement::SetPropertyValues($elementId, $iblockId, $props, 'PRICE') - четвертый аргумент = символьный код или ID свойства.
4. Проверьте: GetProperty снова - BRAND и PHOTOS должны совпасть с baseline.
5. Ошибки: если false - CIBlockElement::GetLastError() и проверка существования элемента и кода свойства.

Loader::includeModule('iblock');
CIBlockElement::SetPropertyValues(4821, 15, ['PRICE' => 999], 'PRICE');
if ($err = CIBlockElement::GetLastError()) { /* лог */ }

Сделайте: логируйте массив до и после записи на staging. Не делайте: путать символьный код свойства с кодом значения списка - для enum нужен ID из CIBlockPropertyEnum.

Запишите несколько полей через SetPropertyValuesEx

SetPropertyValuesEx - стандарт для импорта: передаете только измененные свойства по символьному коду, остальные не затрагиваются. Справка: SetPropertyValuesEx.

CIBlockElement::SetPropertyValuesEx(
    $elementId,
    $iblockId,
    [
        'PRICE' => 1290,
        'ARTICLE' => 'SKU-2026-08',
        'BRAND' => 42, // ID enum для списка, не текст
    ]
);

Для очистки множественного [] не работает - нужен false:

CIBlockElement::SetPropertyValuesEx($elementId, $iblockId, ['PHOTOS' => false]);

Сделайте: SetPropertyValuesEx в агентах импорта и API-обработчиках. Не делайте: Update с PROPERTY_VALUES для смены одного поля - риск обнуления каталога.

Подготовьте VALUE по типу: списки, файлы и множественные

Формат VALUE зависит от типа свойства. Ошибка формата - свойство "записалось", но фильтр каталога не видит значение.

Файлы одного свойства - один вызов. Второй SetPropertyValues для PHOTOS сотрет первый. SetPropertyValueCode для множественных файлов дополняет, а SetPropertyValuesEx перезаписывает - для полной замены берите Ex.

Сделайте: перед импортом списков получите enum ID через CIBlockPropertyEnum::GetList. Не делайте: SetPropertyValueCode для массовой замены файлов - получите дубликаты.

Проверьте результат и отладьте через LAST_ERROR

После любой записи - контрольный цикл read-back:

1. GetProperty - целевые обновились, остальные совпадают с baseline.
2. GetLastError() - пустая строка после вызова.
3. GetByID - элемент есть, IBLOCK_ID верный, CODE свойства не перепутан.
4. Кэш и фасет: clearIblockTagCache после массового импорта; переиндексация, если фильтр молчит.
5. OnBeforeIBlockElementUpdate - обработчик мог изменить PROPERTY_VALUES.

Перед массовым импортом: тест на одном элементе, бекап, dry-run на staging. Нужна помощь - обсудим задачу.

Автор: Максим Мольков, разработчик 1С-Битрикс.
Источники: SetPropertyValues, SetPropertyValuesEx, SetPropertyValueCode на dev.1c-bitrix.ru (проверено 02.08.2026).

Частые вопросы

Что дальше: CRUD Add → read → write → Update без PROPERTY_VALUES. Enum-списки - CIBlockPropertyEnum. Аудит импорта - контакты.