Значения свойств элементов инфоблока

Инфоблок хранит значения свойств отдельно от полей элемента, в общей таблице значений или в отдельных таблицах в зависимости от версии хранения. Значения записывают и читают через ORM-класс инфоблока Element{ApiCode}Table:

• set() — задает значение одиночного свойства,

• addTo(), removeFrom() и removeAll() — меняют значения множественного свойства,

• get() — возвращает значение свойства, выбранного в запросе.

Через ORM меняют значения свойств существующего элемента. Новый элемент вместе со значениями свойств создают методом CIBlockElement::Add(), а поля элемента меняют методом CIBlockElement::Update(): ORM-метод save() при создании элемента и изменении его полей выполняет только часть работы классического API. Различия описаны в разделе Выбрать API для записи.

Классический API CIBlockElement нужен и для значений свойств, если проект обрабатывает события классического API. Если на сайте работает модуль поиска, после ORM-записи переиндексируйте элемент методом CIBlockElement::UpdateSearch(), способ описан в разделе Обновить кеш и индексы. Если код проекта уже использует методы SetPropertyValuesEx(), GetProperty() или GetPropertyValues(), их ORM-замены приведены в разделе Если в коде используется классический API.

Перед работой подключите модуль iblock и создайте свойства с заполненным символьным кодом CODE. Создание свойств и вариантов списка описано в разделе Добавить свойства, ограничения кода свойства — в разделе Ограничения при создании и обновлении свойства.

Примеры используют инфоблок новостей с символьным кодом API News и его свойства:

• AUTHOR — Автор, строка,

• KEYWORDS — Ключевые слова, множественная строка,

• SOURCE — Источник, список,

• PHOTO — Фото, файл,

• GALLERY — Галерея, множественный файл,

• SUMMARY — Итог, HTML,

• CATEGORY — Рубрика, справочник — тип S с USER_TYPE directory, хранит UF_XML_ID записи Highload-блока.

Переменная $iblockId содержит идентификатор инфоблока, $elementId — идентификатор элемента. Замените коды свойств на коды своего инфоблока.

Получить ORM-класс элементовПолучить ORM-класс элементов

Для записи и чтения свойств нужен класс элементов конкретного инфоблока Element{ApiCode}Table. Часть {ApiCode} — символьный код API инфоблока, его задают в настройках инфоблока. Это не символьный код CODE инфоблока и не код свойства. Подробнее — в разделе Представление инфоблоков в ORM.

Метод IblockTable::compileEntity() создает ORM-класс по символьному коду API и возвращает его описание или false, если инфоблок не найден. Метод getDataClass() возвращает имя класса.

Пример. Получите класс элементов инфоблока новостей и объект элемента по ID.

use Bitrix\Iblock\IblockTable;
use Bitrix\Main\Loader;

if (!Loader::includeModule('iblock'))
{
    throw new \RuntimeException('Не удалось подключить модуль iblock');
}

$elementEntity = IblockTable::compileEntity('News');

if (!$elementEntity)
{
    throw new \RuntimeException('Не удалось скомпилировать ORM-класс элементов');
}

$elementNewsClass = $elementEntity->getDataClass();

$element = $elementNewsClass::getByPrimary($elementId, [
    'select' => ['ID'],
])
    ->fetchObject()
;

if ($element === null)
{
    throw new \RuntimeException('Элемент не найден');
}

ORM-класс содержит только свойства с заполненным символьным кодом. Свойство без кода недоступно через set() и get().

После компиляции к ORM-классу можно обращаться по полному имени, например \Bitrix\Iblock\Elements\ElementNewsTable. Общий класс Bitrix\Iblock\ElementTable не содержит свойств и не подходит для записи значений.

Примеры ниже используют переменные $elementNewsClass и $element из этого раздела.

Формат значенияФормат значения

Что передать в свойство, зависит от его типа, множественности и опции WITH_DESCRIPTION.

Значение по типу свойстваЗначение по типу свойства

Свойство хранит не отображаемый текст, а идентификатор или строку, которую разработчик передает при записи. Множественное свойство хранит набор таких значений.

Поле USER_TYPE задает пользовательский тип свойства. Пользовательский тип расширяет базовый тип и добавляет свою обработку значения, подробнее — в разделе Пользовательские типы свойств.

ORM записывает значение пользовательского типа без преобразования и не переводит дату из формата сайта во внутренний формат. Поэтому дату передавайте строкой во внутреннем формате, например (new \Bitrix\Main\Type\DateTime())->format('Y-m-d H:i:s'). Формат HTML-свойства описан в разделе Записать HTML-свойство.

Описание значенияОписание значения

Если у свойства включена опция WITH_DESCRIPTION, к каждому значению можно сохранить текстовое описание. Опция доступна для типов Строка, Число и Файл.

Чтобы передать значение вместе с описанием, создайте объект Bitrix\Iblock\ORM\PropertyValue. Первый аргумент конструктора — значение, второй — описание.

use Bitrix\Iblock\ORM\PropertyValue;

$value = new PropertyValue($fileId, 'Главное фото');

Переменная $fileId содержит ID файла, сохраненного методом CFile::SaveFile().

Найти вариант спискаНайти вариант списка

Перед записью в свойство-список получите ID варианта по внешнему коду XML_ID. Внешний код не меняется при переименовании варианта, поэтому ищите вариант по нему, а не по тексту.

ORM-класс Bitrix\Iblock\PropertyEnumerationTable описывает таблицу вариантов списков. Фильтр в примере отбирает варианты по инфоблоку и коду свойства через связь PROPERTY.

Пример. Получите ID варианта списка Источник по внешнему коду из переменной $sourceXmlId.

use Bitrix\Iblock\PropertyEnumerationTable;

$sourceEnum = PropertyEnumerationTable::getList([
    'select' => ['ID'],
    'filter' => [
        '=PROPERTY.IBLOCK_ID' => $iblockId,
        '=PROPERTY.CODE' => 'SOURCE',
        '=XML_ID' => $sourceXmlId,
    ],
    'limit' => 1,
])
    ->fetch()
;

$sourceEnumId = $sourceEnum ? (int)$sourceEnum['ID'] : 0;

if ($sourceEnumId === 0)
{
    throw new \RuntimeException('Вариант списка не найден');
}

Строка варианта содержит поля:

• ID — идентификатор варианта, его передают в set(),

• PROPERTY_ID — ID свойства,

• VALUE — текст варианта,

• XML_ID — внешний код варианта,

• SORT — сортировка варианта,

• DEF — признак значения по умолчанию.

Если варианта с нужным XML_ID нет, создайте его способом из раздела Добавить варианты в существующий список и задайте XML_ID сами.

Записать значенияЗаписать значения

Объект элемента хранит изменения свойств до вызова save(). Метод save() записывает только те свойства, которые код изменил через set(), addTo(), removeFrom() и removeAll(). Значения остальных свойств остаются без изменений.

Задать одиночное значениеЗадать одиночное значение

Метод set() принимает код свойства и новое значение. Если у свойства уже есть значение, метод заменяет его. Метод возвращает объект элемента, поэтому вызовы set() можно объединять в цепочку.

Пример. Задайте автора, вариант списка Источник и рубрику из Highload-блока.

$element
    ->set('AUTHOR', 'Пресс-служба')
    ->set('SOURCE', $sourceEnumId) // ID варианта списка
    ->set('CATEGORY', 'cybersec')  // UF_XML_ID записи Highload-блока
;

Получайте ID варианта способом из раздела Найти вариант списка, а не задавайте число вручную. ORM не проверяет, что переданный ID принадлежит вариантам этого свойства.

Задать значение с описаниемЗадать значение с описанием

Чтобы записать новое значение вместе с описанием, передайте в set() объект PropertyValue.

use Bitrix\Iblock\ORM\PropertyValue;

$element->set('AUTHOR', new PropertyValue('Пресс-служба', 'Автор материала'));

Результат зависит от того, загружено ли текущее значение свойства в объект элемента:

• если значение не загружено, ORM сохранит значение и описание,

• если значение загружено, ORM заменит только значение, а описание останется прежним.

Для инфоблоков, которые хранят свойства в общей таблице, ORM загружает текущее значение перед set() автоматически. Поэтому у существующего элемента такого инфоблока описание через set() не изменится.

Чтобы изменить описание существующего значения, выберите свойство в запросе и задайте поле DESCRIPTION у объекта значения.

Пример. Измените описание автора у существующего элемента.

$element = $elementNewsClass::query()
    ->setSelect(['ID', 'AUTHOR'])
    ->where('ID', $elementId)
    ->fetchObject()
;

if ($element === null)
{
    throw new \RuntimeException('Элемент не найден');
}

$element->get('AUTHOR')?->set('DESCRIPTION', 'Автор материала');
$element->save();

Изменить множественное свойствоИзменить множественное свойство

Множественное свойство в ORM — коллекция значений. Меняйте коллекцию методами объекта элемента, а не передавайте массив в set(), который работает со значением одиночного свойства:

• addTo() — добавляет значение к уже сохраненным,

• removeFrom() — удаляет значение, равное переданному,

• removeAll() — удаляет все значения свойства.

Пример. Замените набор ключевых слов. Код удаляет прежние значения и добавляет новые.

$element->removeAll('KEYWORDS');
$element->addTo('KEYWORDS', 'обновление');
$element->addTo('KEYWORDS', 'безопасность');

Методы addTo(), removeFrom() и removeAll() возвращают null, поэтому вызывайте их отдельными строками, а не цепочкой.

Для строковых и числовых свойств addTo() сохраняет повторяющиеся значения, для остальных типов пропускает значение, которое уже есть в коллекции.

Методы removeFrom() и removeAll() сами загружают текущие значения свойства, если их нет в объекте. Метод removeFrom() удаляет только запись переданного значения и не перезаписывает остальные значения.

Сохранить файлСохранить файл

Файловое свойство в ORM принимает только ID файла. Сначала сохраните файл методом CFile::SaveFile(), затем передайте его ID в свойство.

Пример. Добавьте существующему элементу главное фото и снимок в галерею с описаниями.

use Bitrix\Iblock\ORM\PropertyValue;

$photoId = \CFile::SaveFile(\CFile::MakeFileArray($photoPath), 'iblock');
$galleryFileId = \CFile::SaveFile(\CFile::MakeFileArray($galleryFilePath), 'iblock');

if (!$photoId || !$galleryFileId)
{
    throw new \RuntimeException('Не удалось сохранить файл');
}

$element->set('PHOTO', new PropertyValue($photoId, 'Главное фото'));
$element->addTo('GALLERY', new PropertyValue($galleryFileId, 'Дополнительный снимок'));

$result = $element->save();

if (!$result->isSuccess())
{
    throw new \RuntimeException(implode('; ', $result->getErrorMessages()));
}

Переменные $photoPath и $galleryFilePath содержат пути к существующим файлам, доступным текущему PHP-процессу. Если у свойства уже есть значение, описание задайте способом из раздела Задать значение с описанием.

Новый элемент с файлами создайте методом CIBlockElement::Add(). Метод сам сохраняет файлы, переданные массивом из CFile::MakeFileArray(). Описание передайте массивом с ключами VALUE и DESCRIPTION.

Пример. Создайте новость с главным фото и двумя снимками в галерее.

$elementApi = new \CIBlockElement();

$newElementId = $elementApi->Add([
    'IBLOCK_ID' => $iblockId,
    'NAME' => 'Новость с фото',
    'PROPERTY_VALUES' => [
        'PHOTO' => [
            'VALUE' => \CFile::MakeFileArray($photoPath),
            'DESCRIPTION' => 'Главное фото',
        ],
        'GALLERY' => [
            ['VALUE' => \CFile::MakeFileArray($galleryFilePath), 'DESCRIPTION' => 'Снимок 1'],
            ['VALUE' => \CFile::MakeFileArray($secondFilePath), 'DESCRIPTION' => 'Снимок 2'],
        ],
    ],
]);

if (!$newElementId)
{
    throw new \RuntimeException($elementApi->getLastError());
}

Переменная $secondFilePath содержит путь ко второму снимку. Остальные поля нового элемента описаны в разделе Подготовить поля.

Метод addTo() добавляет файл в галерею и не меняет остальные файлы. Чтобы убрать один файл из множественного свойства, передайте его ID в removeFrom().

ORM не удаляет файлы. После замены или удаления значения прежний файл остается в файловом хранилище. Удалите его методом CFile::Delete() после успешного save(), если файл больше не используется. Чтобы заменить файл одиночного свойства, выберите свойство в запросе и сохраните ID прежнего файла из $element->get('PHOTO')?->getValue() до вызова set().

Пример. Уберите файл из галереи и удалите его из хранилища. Переменная $oldFileId содержит ID удаляемого файла.

$element->removeFrom('GALLERY', (int)$oldFileId);

$result = $element->save();

if ($result->isSuccess())
{
    \CFile::Delete($oldFileId);
}

Записать HTML-свойствоЗаписать HTML-свойство

Компоненты и административный раздел читают значение HTML-свойства как сериализованный массив с ключами TEXT и TYPE. Передайте в set() массив в этом формате, сериализованный функцией serialize(). Ключ TEXT содержит текст, ключ TYPE — его формат, HTML или TEXT.

$element->set('SUMMARY', serialize([
    'TEXT' => '<p>Система обновлена.</p>',
    'TYPE' => 'HTML',
]));

Если передать строку с HTML без сериализации, компоненты прочитают ее как обычный текст с типом TEXT. Страница выведет теги как текст.

При чтении через ORM метод getValue() возвращает сериализованную строку. Чтобы получить HTML, передайте ее в unserialize() и возьмите ключ TEXT.

Сохранить измененияСохранить изменения

Метод save() записывает изменения в базу данных и возвращает объект результата. Проверьте результат методом isSuccess().

$result = $element->save();

if (!$result->isSuccess())
{
    throw new \RuntimeException(
        implode('; ', $result->getErrorMessages())
    );
}

При изменении существующего элемента ORM не проверяет обязательные свойства с опцией IS_REQUIRED. Проверяйте их заполненность в коде приложения.

Ни ORM, ни метод CIBlockElement::Add() не подставляют значение по умолчанию из настроек свойства. Его подставляют формы редактирования элемента в административном разделе и в компоненте bitrix:iblock.element.add.form. Если код создает элемент, передайте значение в PROPERTY_VALUES сами.

Обновить кеш и индексыОбновить кеш и индексы

После записи свойств компоненты и умный фильтр могут показывать прежние значения. Тегированный кеш, фасетный и поисковый индексы хранят данные отдельно от элемента. Кеш ORM-запроса, заданный методом setCacheTtl(), после записи только свойств тоже не сбрасывается, подробнее — в разделе Кешировать запрос.

Класс Element{ApiCode}Table сбрасывает тегированный кеш инфоблока и обновляет фасетный индекс, только если в том же save() изменились поля элемента, например название. Если save() записал только свойства, кеш и индексы останутся прежними. ORM не обновляет поисковый индекс ни в одном случае, поэтому вызывайте UpdateSearch() после любого save(), если на сайте используется модуль поиска.

Пример. Сбросьте кеш и обновите индексы после save(), который изменил только свойства.

use Bitrix\Iblock\PropertyIndex\Manager;
use Bitrix\Main\Application;

Application::getInstance()->getTaggedCache()->clearByTag('iblock_id_' . $iblockId);
Manager::updateElementIndex($iblockId, $element->getId());
\CIBlockElement::UpdateSearch($element->getId(), true); // если используется модуль search

Вызовы в примере обновляют каждое хранилище:

• Метод clearByTag() сбрасывает тегированный кеш с меткой инфоблока. В нем компоненты, например bitrix:news.list, хранят результат. Классический метод CIBlock::clearIblockTagCache($iblockId) сбрасывает тот же тег iblock_id_<ID>, но только если определена константа BX_COMP_MANAGED_CACHE.

• Метод Manager::updateElementIndex() обновляет запись элемента в фасетном индексе. Умный фильтр bitrix:catalog.smart.filter отбирает элементы по этому индексу. Как построить индекс и какие свойства в него попадают, описано в статье Фасетный индекс и умный фильтр.

• Метод CIBlockElement::UpdateSearch() переиндексирует элемент в поисковом индексе модуля search. Второй аргумент true перезаписывает прежнюю запись индекса. Метод относится к классическому API, у модуля поиска нет ORM-метода индексации.

При записи свойств многих элементов обновляйте фасетный и поисковый индексы для каждого элемента, а кеш сбрасывайте один раз после цикла.

Прочитать значенияПрочитать значения

Свойства не попадают в объект без setSelect(). По умолчанию запрос выбирает только поля элемента, а метод get() вернет null для невыбранного свойства.

Чтобы отобрать элементы по значению свойства, укажите в фильтре поле <код>.VALUE. Условия по свойствам разных типов приведены в разделе Отфильтровать по свойству.

Прочитать свойства элементаПрочитать свойства элемента

Метод get() для одиночного свойства возвращает объект значения или null, если значения нет. Для множественного свойства метод возвращает коллекцию, ее можно перебрать через foreach или получить массив объектов методом getAll().

Для свойства-списка добавьте в setSelect() поле <код>.ITEM, например SOURCE.ITEM. Без него метод getItem() вернет null, а getValue() — только ID варианта.

Пример. Прочитайте автора, вариант списка, ключевые слова и главное фото элемента.

$element = $elementNewsClass::query()
    ->setSelect(['ID', 'AUTHOR', 'SOURCE.ITEM', 'KEYWORDS', 'PHOTO'])
    ->where('ID', $elementId)
    ->fetchObject()
;

if ($element === null)
{
    throw new \RuntimeException('Элемент не найден');
}

$author = $element->get('AUTHOR')?->getValue();

$sourceItem = $element->get('SOURCE')?->getItem();
$sourceName = $sourceItem?->getValue();  // текст варианта
$sourceXmlId = $sourceItem?->getXmlId(); // внешний код варианта

$keywords = [];
foreach ($element->get('KEYWORDS') ?? [] as $keyword)
{
    $keywords[] = $keyword->getValue();
}

$photo = $element->get('PHOTO');
$photoUrl = $photo ? \CFile::GetPath($photo->getValue()) : null;
$photoDescription = $photo?->getDescription();

Для файлового свойства метод getValue() возвращает ID файла. Метод CFile::GetPath() возвращает путь к файлу, метод CFile::GetFileArray() — массив данных файла.

У значения свойства-привязки к элементу есть связь ELEMENT, если у связанного инфоблока задан символьный код API. Выберите поле <код>.ELEMENT, чтобы получить поля связанного элемента в том же запросе.

Прочитать свойства многих элементовПрочитать свойства многих элементов

Чтобы получить свойства набора элементов, выберите свойства в запросе с фильтром по ID и получите коллекцию методом fetchCollection().

Пример. Получите автора и ключевые слова для элементов из переменной $elementIds.

$elements = $elementNewsClass::query()
    ->setSelect(['ID', 'AUTHOR', 'KEYWORDS'])
    ->whereIn('ID', $elementIds)
    ->fetchCollection()
;

foreach ($elements as $element)
{
    $author = $element->get('AUTHOR')?->getValue();

    $keywords = [];
    foreach ($element->get('KEYWORDS') ?? [] as $keyword)
    {
        $keywords[] = $keyword->getValue();
    }
}

Переменная $elementIds содержит массив ID элементов, например из выборки компонента.

Если в коде используется классический APIЕсли в коде используется классический API

Классический API CIBlockElement продолжает работать. Для значений свойств существующего элемента в новом коде используйте ORM, а классический API — для переиндексации в модуле поиска и в проекте, где есть обработчики событий классического API. ORM эти события не вызывает, подробнее — в статье События инфоблоков. Создание элемента и изменение его полей остаются за методами CIBlockElement::Add() и Update().

Заменить методы классического APIЗаменить методы классического API

Таблица сопоставляет методы классического API, которые работают со значениями свойств, и их ORM-замены. Колонка «Что учесть» описывает поведение классического метода, важное при замене и при поддержке существующего кода.

Записать значения с событиями классического APIЗаписать значения с событиями классического API

Методы классического API вызывают свои события:

• SetPropertyValuesEx() — события OnIBlockElementSetPropertyValuesEx и OnAfterIBlockElementSetPropertyValuesEx,

• SetPropertyValues() — события OnIBlockElementSetPropertyValues и OnAfterIBlockElementSetPropertyValues,

• Update() — события изменения элемента, например OnBeforeIBlockElementUpdate. С ключом PROPERTY_VALUES метод вызывает еще события SetPropertyValues().

Какие события вызывает каждый способ записи, показано в разделе Какие события вызывает запись.

Записывайте значения тем методом, события которого обрабатывает проект. Если обработчики подписаны на события SetPropertyValuesEx(), используйте метод CIBlockElement::SetPropertyValuesEx(). Метод меняет только переданные свойства.

Ключ массива — код или ID свойства, значение — в формате из раздела Значение по типу свойства, кроме файлов. Файл передайте массивом, который возвращает CFile::MakeFileArray(). Числовой ID файла метод не принимает и молча пропускает такое значение. Дату метод принимает и в формате сайта. Описание значения передайте массивом с ключами VALUE и DESCRIPTION.

Пример. Измените автора и ключевые слова так, чтобы сработали обработчики событий классического API.

\CIBlockElement::SetPropertyValuesEx($elementId, $iblockId, [
    'AUTHOR' => 'Пресс-служба',
    'KEYWORDS' => ['обновление', 'безопасность'], // полный набор значений
]);

Метод ничего не возвращает и не обновляет кеш и индексы. После вызова обновите их способом из раздела Обновить кеш и индексы.

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

Перед публикацией кода выполните на тестовом элементе:

1. Запишите значения одиночного, множественного, списочного и файлового свойств.

2. Прочитайте значения через query() и сравните с исходными данными.

3. Измените одно свойство и убедитесь, что значения остальных свойств сохранились.

4. Измените описание существующего значения и проверьте, что сохранилось новое описание.

5. Уберите файл из галереи и проверьте, что прежний файл удален из хранилища, если код удаляет его.

6. Откройте страницу с компонентом, который выводит элемент, и проверьте, что новые значения видны. Если на странице есть умный фильтр, отберите элемент по новому значению свойства. Если кеш или фильтр показывают прежние значения, обновите их способом из раздела Обновить кеш и индексы.

Ошибки записи и выбор быстрого способа чтения для больших выборок описаны в статье Производительность и частые ошибки.