Безопасное обновление свойства элемента инфоблока

Нужно изменить одно или несколько свойств элемента инфоблока (в обработчике формы, агенте, API), не перезаписывая остальные. CIBlockElement::SetPropertyValues перезаписывает все свойства элемента — при передаче неполного набора остальные обнуляются. Проблема: точечное обновление без потери данных и без лишних запросов. Симптомы: после обновления одного свойства пропадают другие; ошибки при неверном типе значения (список, файл, множественное). Ниже — безопасная функция с проверкой элемента и свойства, использование SetPropertyValuesEx, подготовка значения по типу и проверка результата.

Решение

Безопасное обновление свойств элемента инфоблока без полной перезаписи. Используйте в обработчиках форм, агентах, API для точечного изменения значений.

use Bitrix\Main\Loader;

/**
 * Безопасно обновить свойство элемента
 * @param int $elementId ID элемента
 * @param int $iblockId ID инфоблока
 * @param string $propertyCode Код свойства
 * @param mixed $value Новое значение (строка, массив для множественных)
 * @return bool Успешно ли обновлено
 */
function updateElementPropertySafe($elementId, $iblockId, $propertyCode, $value) {
    if (!Loader::includeModule('iblock')) {
        return false;
    }

    $element = CIBlockElement::GetByID($elementId)->Fetch();
    if (!$element || $element['IBLOCK_ID'] != $iblockId) {
        return false;
    }

    $property = CIBlockProperty::GetByID($propertyCode, $iblockId)->Fetch();
    if (!$property) {
        return false;
    }

    $propertyId = $property['ID'];
    $propertyType = $property['PROPERTY_TYPE'];

    $propertyValue = [];
    if ($propertyType == 'L' && is_numeric($value)) {
        $propertyValue[$propertyId] = ['VALUE' => $value];
    } elseif ($propertyType == 'F' && is_numeric($value)) {
        $propertyValue[$propertyId] = ['VALUE' => $value];
    } elseif ($property['MULTIPLE'] == 'Y') {
        $values = is_array($value) ? $value : [$value];
        $propertyValue[$propertyId] = [];
        foreach ($values as $val) {
            $propertyValue[$propertyId][] = ['VALUE' => $val];
        }
    } else {
        $propertyValue[$propertyId] = ['VALUE' => $value];
    }

    $result = CIBlockElement::SetPropertyValuesEx(
        $elementId,
        $iblockId,
        $propertyValue
    );

    return ($result !== false);
}

Пример вызова:

// Одно свойство
if (updateElementPropertySafe(123, 5, 'PRICE', 1500)) {
    echo 'Свойство обновлено';
} else {
    echo 'Ошибка обновления';
}

// Множественное свойство
updateElementPropertySafe(123, 5, 'TAGS', ['tag1', 'tag2', 'tag3']);

SetPropertyValuesEx обновляет только переданные свойства; для файлов передавайте ID из CFile::SaveFile().

Проверка

1. Элемент и инфоблок — перед вызовом убедитесь, что элемент существует и принадлежит нужному инфоблоку. В коде это проверяется через GetByID и сравнение IBLOCK_ID. При неверном инфоблоке функция вернёт false.

2. Значение в админке — после успешного вызова откройте элемент в админке (Контент → Инфоблоки → элемент). Изменившееся свойство должно содержать новое значение; остальные свойства не должны измениться.

3. Программная проверка — получите элемент с полями и свойствами после обновления и проверьте значение:

   $el = CIBlockElement::GetList([], ['ID' => 123], false, false, ['ID', 'NAME']);
   $el->SetUrlTemplates();
   $props = CIBlockElement::GetProperty($iblockId, 123, [], ['CODE' => 'PRICE']);
   $prop = $props->Fetch();
   // $prop['VALUE'] должно быть новое значение

Типичные ошибки

• Использование SetPropertyValues вместо SetPropertyValuesEx — первый перезаписывает все свойства элемента; при неполном массиве остальные обнуляются. Для точечного обновления всегда используйте SetPropertyValuesEx.
• Неверный тип для списка (L) или файла (F) — для списка передавайте ID значения списка (число), для файла — ID файла после CFile::SaveFile(). Строка для типа F может не сработать.
• Множественное свойство — передавайте массив значений; для одного значения можно [$value]. Формат в коде выше: массив элементов ['VALUE' => $val].
• Отсутствие проверки модуля и элемента — без includeModule('iblock') и проверки элемента возможны фатальные ошибки или обновление «чужого» инфоблока. Всегда проверяйте возврат функции.

Где применять

• Обработчики форм, агенты, API: точечное обновление свойств по событию (заявка, статус, импорт). Продакшн и dev — везде, где используется инфоблок.
• Импорт/синхронизация: обновление одного поля без перезаписи всего элемента. См. Элементы с пагинацией, Безопасная проверка прав и редирект.

Связанные сниппеты: Список элементов с пагинацией, Идемпотентный агент с блокировкой, Смена статуса заказа D7.