CIBlockPropertyEnum это класс ядра Битрикса для работы с пунктами свойств типа «Список». Если у элемента инфоблока есть свойство «Цвет» или «Тип страницы» с выпадающим списком, то сами варианты («Красный», «Синий») лежат не в элементе, а в отдельной таблице, и достаются именно через этот класс. Ниже разбираю, как выбрать все значения списка, как найти нужное по XML_ID, как добавлять и править пункты кодом и что делать в D7, где у класса есть аналог.
Где хранятся значения списка и зачем нужен CIBlockPropertyEnum
У свойства типа «Список» есть две сущности. Первая это само свойство (таблица b_iblock_property), вторая это набор его пунктов (таблица b_iblock_property_enum). У каждого пункта есть числовой ID, текст VALUE, символьный XML_ID, сортировка SORT и флаг DEF (значение по умолчанию). У элемента в значении свойства хранится только ID пункта.
Отсюда частая путаница. Когда вы берёте элемент через CIBlockElement::GetList и просите PROPERTY_COLOR, вы получаете текст выбранного пункта, а когда нужен весь перечень вариантов, например, чтобы построить фильтр на сайте или выпадающий список в форме, элемент вам не поможет. Для этого и нужен CIBlockPropertyEnum.
Ключ в том, что класс работает с пунктами независимо от элементов: получить, добавить, обновить, удалить. Элементы он не трогает.
Как получить все значения списка через CIBlockPropertyEnum::GetList
Метод принимает сортировку и фильтр. В фильтре я чаще всего использую IBLOCK_ID и CODE (символьный код свойства), потому что ID свойства на разных окружениях (разработка и боевой сайт) обычно отличается, а код один.
<?php
CModule::IncludeModule('iblock');
$items = [];
$res = CIBlockPropertyEnum::GetList(
['SORT' => 'ASC', 'VALUE' => 'ASC'],
['IBLOCK_ID' => 5, 'CODE' => 'COLOR']
);
while ($row = $res->GetNext()) {
$items[] = [
'ID' => $row['ID'],
'VALUE' => $row['VALUE'],
'XML_ID' => $row['XML_ID'],
];
}
Метод возвращает объект результата, поэтому цикл через GetNext() обязателен. Прямо присваивать результат массиву нельзя. Если в значениях есть спецсимволы и вы выводите их в HTML, GetNext() заодно экранирует поля, а для служебной логики (сравнение, запись) мне удобнее Fetch(), который отдаёт сырые данные.
В строке результата приходят поля пункта (ID, VALUE, XML_ID, SORT, DEF, PROPERTY_ID), плюс данные свойства вроде PROPERTY_CODE и PROPERTY_NAME.
Фильтр по XML_ID и по тексту
Когда пункт нужно найти по внешнему коду, в фильтр добавляется XML_ID. Это самый надёжный способ, потому что текст пункта редактор может переименовать, а XML_ID остаётся.
<?php
$enum = CIBlockPropertyEnum::GetList(
[],
['IBLOCK_ID' => 5, 'CODE' => 'COLOR', 'XML_ID' => 'red']
)->Fetch();
if ($enum) {
$enumId = (int)$enum['ID'];
}
По тексту можно искать через ключ VALUE, но я так делаю только в одноразовых скриптах миграции, где другого идентификатора нет.
Значение списка конкретного элемента: ENUM_ID, VALUE и XML_ID
Задача «получить значения свойства-списка у элемента» решается без CIBlockPropertyEnum. В CIBlockElement::GetList, если указать в выборке PROPERTY_<КОД>, в результате появятся поля PROPERTY_<КОД>_VALUE (текст), PROPERTY_<КОД>_ID (код значения у элемента) и PROPERTY_<КОД>_ENUM_ID (ID пункта списка). Код свойства в этих ключах пишется в верхнем регистре, даже если в настройках инфоблока он задан в нижнем. Обязательно просить ID и IBLOCK_ID, иначе выборка работает некорректно.
<?php
$res = CIBlockElement::GetList(
['SORT' => 'ASC'],
['IBLOCK_ID' => 5, 'ACTIVE' => 'Y'],
false,
['nPageSize' => 20],
['ID', 'IBLOCK_ID', 'NAME', 'PROPERTY_COLOR']
);
while ($el = $res->GetNext()) {
echo $el['NAME'] . ': ' . $el['PROPERTY_COLOR_VALUE']
. ' (enum ' . $el['PROPERTY_COLOR_ENUM_ID'] . ')';
}
Если нужен именно XML_ID выбранного пункта, то в выборке элемента его нет, и вторым шагом я беру ENUM_ID и запрашиваю пункт через CIBlockPropertyEnum::GetByID($enumId). Этот метод возвращает массив с полями пункта, в том числе XML_ID. На списке из 20 элементов делать запрос на каждый пункт расточительно, поэтому я заранее собираю карту «ENUM_ID в XML_ID» одним вызовом GetList и ищу по ней.
Фильтр элементов по значению списка
В документации к CIBlockElement::GetList для свойств типа «Список» фильтр PROPERTY_<КОД> работает как числовой, то есть сравнивается с ID пункта. Вариант PROPERTY_<КОД>_VALUE ищет по строковому значению списка, а не по идентификатору.
| Ключ фильтра | Что сравнивается | Когда брать |
|---|---|---|
PROPERTY_COLOR |
ID пункта | ID известен и стабилен, нужна скорость |
PROPERTY_COLOR_VALUE |
текст пункта | в коде есть только название, разовая выборка |
PROPERTY_COLOR_ENUM_ID |
ID пункта (используется в выборке) | вывод в результатах, а не в условиях |
Практический вывод: в коде, который живёт долго, сначала находим ID пункта по XML_ID через CIBlockPropertyEnum::GetList, затем подставляем его в фильтр элементов. Так переименование пункта редактором ничего не ломает.
Бесплатный материал
🎁 Полезный скрипт в подарок
Подпишитесь на Telegram - пришлю готовый скрипт по этой теме.
Без спама. Отписка в 1 клик.
Добавление и изменение пунктов списка кодом
В проектах, где одно и то же свойство надо завести на нескольких окружениях, я не рисую пункты руками в админке. Свойство создаётся через CIBlockProperty::Add, а пункты через CIBlockPropertyEnum::Add. Прямой INSERT в таблицы b_iblock_property и b_iblock_property_enum у меня однажды потребовал ручной чистки каталога bitrix/managed_cache/MYSQL/b_iblock, а API делает это сам.
<?php
$prop = CIBlockProperty::GetList(
[],
['IBLOCK_ID' => 5, 'CODE' => 'COLOR']
)->Fetch();
$enumId = CIBlockPropertyEnum::Add([
'PROPERTY_ID' => $prop['ID'],
'VALUE' => 'Красный',
'XML_ID' => 'red',
'SORT' => 100,
'DEF' => 'N',
]);
if (!$enumId) {
echo 'Пункт не добавлен';
}
Add возвращает ID нового пункта, поэтому проверка на ложное значение здесь работает. Для изменения и удаления есть CIBlockPropertyEnum::Update($id, ['VALUE' => 'Алый']) и CIBlockPropertyEnum::Delete($id). Перед удалением проверьте, не выбран ли пункт у элементов, иначе у них останется ссылка на несуществующее значение.
Отдельная ловушка относится к записи значения в элемент. Метод CIBlockElement::SetPropertyValuesEx ничего не возвращает, поэтому проверка вида if (!CIBlockElement::SetPropertyValuesEx(...)) печатает ложную «ошибку записи» при том, что данные записаны. Результат я проверяю повторной выборкой.
<?php
CIBlockElement::SetPropertyValuesEx(
$elementId,
5,
['COLOR' => $enumId]
);
Для свойства-списка в значение передаётся ID пункта, а не текст.
D7: PropertyEnumerationTable вместо старого класса
Оба ядра живут в продукте одновременно, и старый CIBlockPropertyEnum никуда не делся. Тем не менее в новом коде я предпочитаю D7: у ORM есть единый синтаксис select / filter / order / limit и связь со свойством. Таблица пунктов описана классом \Bitrix\Iblock\PropertyEnumerationTable.
<?php
use Bitrix\Main\Loader;
use Bitrix\Iblock\PropertyEnumerationTable;
Loader::includeModule('iblock');
$items = PropertyEnumerationTable::getList([
'select' => ['ID', 'VALUE', 'XML_ID', 'SORT', 'PROPERTY_ID'],
'filter' => [
'=PROPERTY.IBLOCK_ID' => 5,
'=PROPERTY.CODE' => 'COLOR',
],
'order' => ['SORT' => 'ASC'],
])->fetchAll();
Метод getList возвращает объект результата, у которого есть fetch() и fetchAll(), поэтому отдельный цикл не нужен. Фильтр в ORM строится с префиксами: = для точного совпадения, %= для поиска по маске.
Осторожнее с одним моментом: если вы меняете пункты или свойства мимо API (например, SQL-скриптом), метаданные инфоблока остаются в кэше. Тогда нужно вручную очистить bitrix/managed_cache/MYSQL/b_iblock.
Когда какой вариант брать
| Вариант | Плюсы | Минусы |
|---|---|---|
CIBlockPropertyEnum::GetList |
короткий вызов, знаком большинству старых проектов | процедурный стиль, результат нужно обходить циклом |
PropertyEnumerationTable::getList |
единый стиль D7, связь со свойством в фильтре, fetchAll() |
нужно подключать модуль через Loader, нет методов записи с очисткой кэша, как в старом API |
CIBlockPropertyEnum::Add / Update / Delete |
сами сбрасывают кэш метаданных | только старое ядро |
Чтение у меня идёт через D7, запись пунктов через CIBlockPropertyEnum, потому что про очистку кэша думать не приходится.
Типовые сценарии: фильтр на сайте, шаблон страницы, миграции
Выпадающий список в собственном фильтре
Когда на странице каталога нужен фильтр по «Цвету», я собираю варианты одним запросом к пунктам списка и вывожу как select. В значении option хожу с ID, в подписи с VALUE. Пришедший в GET ID потом идёт в фильтр элементов как PROPERTY_COLOR. Так я не экспонирую внутренние тексты в URL и не зависим от их переименования.
Выбор шаблона детальной страницы через список
Один из рабочих приёмов: свойство типа «Список» DETAIL_TEMPLATE у элементов инфоблока, а у пунктов латинский XML_ID. В detail.php комплексного компонента news читаем XML_ID выбранного значения у текущего элемента, и, если в шаблонах компонента news.detail есть папка с таким именем, передаём это имя вторым аргументом IncludeComponent. Иначе передаём пустое имя, то есть .default. Новый шаблон это новый пункт списка плюс новая папка.
Ловушка тут в пустом коде. Искать элемент нужно только при заданных ELEMENT_ID или ELEMENT_CODE, иначе фильтр =CODE => '' возвращает первый попавшийся элемент, и чужой шаблон уезжает на страницу раздела. Ещё одно замечание: news.detail показывает только активные элементы, поэтому превью неактивного через шаблон не откроется.
Скрипты миграции между окружениями
Если свойство и его пункты нужно воспроизвести на боевом сайте, я пишу скрипт: сначала ищу свойство по коду, при отсутствии создаю, затем для каждого пункта проверяю наличие по XML_ID и добавляю только недостающие. Скрипт можно запускать повторно без дублей. Из консоли ядро поднимается через prolog_before.php с константами NO_KEEP_STATISTIC и NOT_CHECK_PERMISSIONS. На shared-хостинге версия PHP в CLI и в вебе может различаться: на проекте с ядром 22.0.300 из CLI ядро падало под PHP 8.0-8.2 и поднималось только под бинарником PHP 7.4, поэтому первым делом проверяйте, какие версии PHP есть на хостинге.
Частые ошибки при работе с пунктами списка
- Сравнение по тексту вместо XML_ID. Редактор переименовал «Красный» в «Алый», и условие в коде перестало срабатывать.
- Вызов
GetListбезIBLOCK_IDилиCODE. Возвращаются пункты всех списков сразу, и в выборке появляются лишние значения. - Присваивание результата без обхода. И старый, и новый
GetListвозвращают объект, массива там нет. - Диагностика через
print_r. В объектах результата вродеCDBResultвложено подключение к БД с паролем. Выводите только скалярные поля изFetch(), а не сам объект. - Неактуальные данные на сайте. Если компонент закэширован, а пункт списка поменяли, вывод не обновится до истечения
CACHE_TIME. На сайте, где управляемый кэш выключен, правка элемента в админке не сбрасывает кэшnews.detailиnews.list. Помогает обработчикOnAfterIBlockElementUpdate, который чистит кэш компонента для нужных инфоблоков. - Дубли при фильтре по множественному свойству. Документация
CIBlockElement::GetListпредупреждает: на Oracle и MSSQL фильтрация по нескольким значениям множественного свойства может дать дублирование.
Если задача выросла из «достать пункт» в переделку каталога, фильтров и обменов, то доработка и поддержка 1С-Битрикс у меня идёт от 3 000 ₽/час, срок от 1 часа на задачу.
Условия и возможности 1С-Битрикса меняются, поэтому перед внедрением я сверяюсь с актуальной документацией на dev.1c-bitrix.ru.
Частые вопросы
Чем CIBlockPropertyEnum::GetList отличается от CIBlockProperty::GetList?
CIBlockProperty::GetList возвращает сами свойства инфоблока: название, код, тип. CIBlockPropertyEnum::GetList возвращает пункты списка, то есть конкретные варианты значений у свойства типа «Список». Чтобы получить варианты, свойство сначала можно найти по коду, а затем запросить его пункты.
Как получить XML_ID выбранного значения у элемента?
В выборке элемента через CIBlockElement::GetList приходит PROPERTY_КОД_ENUM_ID. Это ID пункта. По нему вызывается CIBlockPropertyEnum::GetByID, который возвращает массив с полем XML_ID. Если элементов много, лучше один раз собрать карту всех пунктов свойства и искать по ней.
Можно ли использовать D7 вместо CIBlockPropertyEnum?
Для чтения можно: класс PropertyEnumerationTable из пространства Bitrix\Iblock отдаёт те же поля пунктов и поддерживает фильтр по свойству. Старый класс при этом остаётся в ядре и не отменяется, а его методы Add, Update и Delete удобны тем, что сами сбрасывают кэш метаданных инфоблока.
Почему после добавления пункта через базу он не виден в админке?
Метаданные инфоблоков лежат в управляемом кэше, и при записи мимо API он не сбрасывается. Решение в том, чтобы добавлять пункты через CIBlockPropertyEnum::Add, а при уже выполненной правке SQL очистить каталог bitrix/managed_cache/MYSQL/b_iblock.