CIBlockProperty в Битрикс: чтение и запись свойств

Свойства элементов инфоблока — один из самых частых источников путаницы в API Битрикса: формат значения меняется в зависимости от типа свойства и множественности. Разберём CIBlockProperty, чтение и запись значений через PROPERTY_VALUES и типичные грабли с форматом данных.

Получение списка свойств инфоблока

<?php

$result = CIBlockProperty::GetList(
    ['SORT' => 'ASC'],
    ['IBLOCK_ID' => $iblockId]
);

while ($property = $result->GetNext()) {
    echo $property['CODE'] . ' (' . $property['PROPERTY_TYPE'] . ')' . PHP_EOL;
}

PROPERTY_TYPE определяет формат значения: S — строка, N — число, L — список (со ссылкой на таблицу вариантов), F — файл, E — привязка к элементу, G — привязка к разделу.

Чтение значения одиночного свойства

<?php

$element = CIBlockElement::GetList(
    [],
    ['ID' => $elementId],
    false,
    false,
    ['ID', 'PROPERTY_COLOR']
)->GetNext();

echo $element['PROPERTY_COLOR_VALUE'];

При выборке через GetList значение свойства попадает в поле с суффиксом _VALUE, а не просто PROPERTY_COLOR — эта деталь регулярно вызывает путаницу у тех, кто переходит от чтения документации сразу к коду.

Нужна помощь с Битрикс?

Множественные свойства

<?php

$element = CIBlockElement::GetList(
    [], ['ID' => $elementId], false, false, ['ID', 'PROPERTY_SIZE']
)->GetNext();

// для множественного свойства _VALUE — массив, а не скаляр
foreach ($element['PROPERTY_SIZE_VALUE'] as $size) {
    echo $size . ', ';
}

Код, написанный без учёта множественности, падает на попытке использовать массив как строку или молча теряет все значения, кроме первого, — стоит заранее знать, какие свойства инфоблока настроены как множественные.

Запись значения через Update

<?php

$el = new CIBlockElement;

$el->Update($elementId, [
    'PROPERTY_VALUES' => [
        'COLOR' => 'Красный',
        'SIZE' => ['S', 'M', 'L'], // множественное свойство — просто массив
    ],
]);

Для обычной записи достаточно передать значение как строку (одиночное свойство) или массив строк (множественное). Более сложный формат с явными ключами понадобится только при работе с существующими значениями по их внутреннему ID.

Обновление конкретного значения по ID записи свойства

<?php

$el->Update($elementId, [
    'PROPERTY_VALUES' => [
        'SIZE' => [
            ['VALUE' => 'M', 'ID' => 145], // заменить существующую запись 145
            ['VALUE' => 'XL'],              // добавить новую
        ],
    ],
]);

Формат с массивом ['VALUE' => ..., 'ID' => ...] нужен, когда важно не просто заменить весь набор значений, а точечно изменить конкретную существующую запись, сохранив её внутренний идентификатор (например, если на него ссылаются извне).

Свойства типа "Список" и их варианты

<?php

$enumResult = CIBlockPropertyEnum::GetList(
    ['SORT' => 'ASC'],
    ['IBLOCK_ID' => $iblockId, 'CODE' => 'COLOR']
);

while ($enumValue = $enumResult->GetNext()) {
    echo $enumValue['XML_ID'] . ' — ' . $enumValue['VALUE'] . PHP_EOL;
}

Для свойств типа "Список" сохранённое значение в PROPERTY_VALUES при записи — это ID конкретного варианта из CIBlockPropertyEnum, а не сам текст. При чтении через GetList с _VALUE Битрикс уже подставляет читаемый текст варианта, но при прямой записи важно передать именно ID нужного варианта, а не строку с его названием.

Частые ошибки

Не учтена множественность свойства. Код ожидает строку там, где приходит массив, или наоборот.
Забыт суффикс _VALUE при чтении через GetList. Обращение к PROPERTY_CODE вместо PROPERTY_CODE_VALUE возвращает пусто.
Для списка передана строка вместо ID варианта. Значение не сохраняется или создаётся новый вариант с тем же текстом.
Замена всего набора вместо точечного обновления. Теряются ID существующих записей множественного свойства, на которые могли ссылаться извне.

Итог

Работа со свойствами инфоблока требует точного понимания трёх вещей: типа свойства (PROPERTY_TYPE), его множественности и формата значения при записи. Для списков значением при записи всегда выступает ID варианта из CIBlockPropertyEnum, а не текст, который видит пользователь на сайте.

Теги: API Инфоблоки Разработка