Как получить ID списочного свойства в Битрикс через CIBlockPropertyEnum?

Типичная ошибка на практике: импорт из CSV подставил в свойство текст «В наличии», Update отработал без ошибок, а фильтр в каталоге не работает — карточка пустая. Знакомо? В списочных свойствах 1С-Битрикс: Управление сайтом в элемент записывается не подпись из файла, а числовой ID варианта из справочника. Ниже разберем CIBlockPropertyEnum::GetList, D7 PropertyEnumerationTable и чек-лист, который спасает от пустых списков и дублей перед выкладкой на прод.

CIBlockPropertyEnum - это классический API 1С-Битрикс (с версии 3.1.3) для работы с вариантами свойств типа "Список" в таблице b_iblock_property_enum: GetList и GetByID читают справочник, Add/Update/Delete меняют его, а в элемент передается числовой ID варианта, не текст VALUE. Сегодня: подключите модуль iblock, получите enum ID по IBLOCK_ID+CODE, постройте карту XML_ID для CSV и запишите ID через SetPropertyValuesEx - не строку из файла.

Речь про CMS на вашем хостинге, не про облачный Bitrix24. Списочное свойство (тип L) хранит у элемента ссылку на строку справочника enum: в админке "В наличии", в коде - числовой ID.

На стейдже колонка CSV называлась VALUE, скрипт писал "В наличии" в PROPERTY_VALUES. Update без ошибок, карточка пустая, фильтр молчит. После GetList с IBLOCK_ID, CODE и XML_ID всё встало за один проход.

Уточните, что такое списочное свойство и CIBlockPropertyEnum

Списочное свойство - это поле элемента с фиксированным набором вариантов ("В наличии", "Под заказ", "Красный"). Варианты живут в справочнике b_iblock_property_enum, а CIBlockPropertyEnum - класс для чтения и правки этого справочника с 2005 года (API 3.1.3). Когда нужно: импорт, фильтры, генерация select на сайте. Когда не нужно: правка одного текстового поля или UF-поля пользователя - там другие классы.

Разберите, когда нужен CIBlockPropertyEnum

Класс нужен, когда вы читаете или меняете справочник вариантов "Список": форма, фильтр каталога, импорт CSV или 1С. У свойства есть PROPERTY_ID; у каждого варианта - ID enum, VALUE (текст) и XML_ID (внешний код). Три разных "ID" путают чаще всего:

Сделайте: перед любым GetList зафиксируйте IBLOCK_ID и символьный CODE свойства. Не делайте: не фильтруйте только по VALUE - в другом инфоблоке может быть такой же текст, и вы получите чужой enum ID.

Получите варианты через CIBlockPropertyEnum::GetList

GetList читает справочник по фильтрам IBLOCK_ID, CODE, PROPERTY_ID, XML_ID, VALUE. Без Loader::includeModule('iblock') список пустой.

1. Подключите модуль: \Bitrix\Main\Loader::includeModule('iblock').
2. Задайте фильтр с непустым IBLOCK_ID и CODE свойства (или PROPERTY_ID, если CODE неудобен).
3. Отсортируйте по SORT или VALUE: ['SORT' => 'ASC', 'VALUE' => 'ASC'].
4. Обойдите результат через while ($row = $rs->GetNext()) и соберите массив ID => VALUE; на стейдже сверьте, что ID только из вашего инфоблока.

$rs = CIBlockPropertyEnum::GetList(
    ['SORT' => 'ASC'],
    ['IBLOCK_ID' => 5, 'CODE' => 'AVAILABILITY']
);
$enums = [];
while ($row = $rs->GetNext()) {
    $enums[$row['ID']] = $row['VALUE'];
}

В реальном проекте часто ломается импорт, когда в фильтре GetList пустой IBLOCK_ID: тянутся варианты из соседних инфоблоков с тем же VALUE — «два Красный» с разными enum ID. Всегда фильтруйте IBLOCK_ID + CODE.

Найдите enum по GetByID и XML_ID для обмена

GetByID отдает поля варианта по enum ID - для отладки. Для CSV и 1С надежнее XML_ID: стабилен между средами, VALUE может отличаться регистром.

CSV/XML_ID → GetList (IBLOCK_ID + CODE + XML_ID) → enum ID → SetPropertyValuesEx → проверка GetByID

Соберите за один GetList карты BY_ID и BY_XML_ID - не дергайте базу на каждой строке импорта.

$rs = CIBlockPropertyEnum::GetList(
    [],
    ['IBLOCK_ID' => 5, 'CODE' => 'COLOR', 'XML_ID' => 'red']
);
if ($row = $rs->GetNext()) {
    $enumId = (int)$row['ID']; // этот ID пойдет в элемент
}

Сделайте: заведите XML_ID у каждого варианта до первого импорта. Не делайте: не матчите CSV только по VALUE - "В наличии" и "в наличии" дадут разный результат или пустоту.

Запишите enum ID в элемент, а не текст VALUE

SetPropertyValuesEx для "Списка" принимает только ID варианта. Текст вместо ENUM_ID может записаться без привязки - метод вернет true, значение пропадет при чтении.

CIBlockElement::SetPropertyValuesEx(
    $elementId,
    $iblockId,
    ['AVAILABILITY' => $enumId]  // число, не "В наличии"
);

В Update и PROPERTY_VALUES те же правила: код свойства в верхнем регистре, значение - enum ID. Логируйте ID и VALUE после записи и проверьте карточку в админке - true от Update еще не гарантия. Полный разбор Update - в гайде как обновить элемент инфоблока через CIBlockElement::Update; здесь только справочник enum.

Добавьте и измените варианты через Add, Update, Delete

Если варианта нет - Add с PROPERTY_ID, VALUE, XML_ID; Update/Delete - по enum ID, не по PROPERTY_ID свойства.

1. Найдите PROPERTY_ID через CIBlockProperty::GetList.
2. Add с VALUE и XML_ID, привяжите enum ID через SetPropertyValuesEx.
3. Rename VALUE через Update — привязки не рвутся; Delete только если вариант не используется в элементах.

Выберите между legacy GetList и D7 PropertyEnumerationTable

С 14.0.0 есть D7 PropertyEnumerationTable для той же таблицы: join с PROPERTY, кеш, validateXmlId.

use Bitrix\Iblock\PropertyEnumerationTable;

$rows = PropertyEnumerationTable::getList([
    'filter' => [
        'PROPERTY.IBLOCK_ID' => 5,
        'PROPERTY.CODE' => 'COLOR',
    ],
    'select' => ['ID', 'VALUE', 'XML_ID'],
    'order' => ['SORT' => 'ASC'],
    'cache' => ['ttl' => 3600],
])->fetchAll();

Мигрировать весь проект не обязательно - достаточно helper с картой XML_ID⇄ID на GetList или PropertyEnumerationTable.

Проверьте типичные сбои по чек-листу до деплоя

Перед выкладкой прогоните пять проверок - они закрывают типичные тикеты с форума и Habr Q&A по ciblockpropertyenum getlist.

1. Модуль iblock подключен? Без Loader::includeModule GetList молчит.
2. IBLOCK_ID в фильтре не пустой? Иначе дубли VALUE из чужих инфоблоков.
3. В PROPERTY_VALUES число enum ID, не строка VALUE? Сверьте с GetByID.
4. CODE свойства в верхнем регистре в SetPropertyValuesEx и Update совпадает с админкой?
5. XML_ID в CSV есть в справочнике? Пустой GetList по XML_ID - сигнал добавить вариант через Add.

Пустой GetList при верном CODE - проверьте тип свойства (L, не строка). Поле ID в строке GetList - то, что пишете в элемент, не PROPERTY_ID.

С импортом каталога поможем - обсудить задачу. Кейсы по Битрикс - в портфолио.

Автор: Максим Мольков, разработчик 1С-Битрикс.
Источники: документация CIBlockPropertyEnum, PropertyEnumerationTable D7, SetPropertyValuesEx.

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