Схема работы инфоблоков и основные объекты

ORM D7 дает доступ к внутренней структуре инфоблоков.

Основные пространства имен модуляОсновные пространства имен модуля

Архитектура D7 организует классы по пространствам имен. Для работы с инфоблоками через ORM используйте соответствующие пространства имен.

use Bitrix\Iblock\TypeTable;            // Типы инфоблоков
        use Bitrix\Iblock\IblockTable;          // Инфоблоки
        use Bitrix\Iblock\SectionTable;         // Разделы
        use Bitrix\Iblock\ElementTable;         // Элементы
        use Bitrix\Iblock\PropertyTable;        // Свойства
        

Генерируемые классы: структура и иерархияГенерируемые классы: структура и иерархия

Для инфоблока с заполненным API_CODE система автоматически создает три связанных ORM-класса в пространстве имен \Bitrix\Iblock\Elements\.

1. Element{ApiCode}Table — статический класс-таблица. Главный интерфейс для операций с базой данных: add(), update(), getList(), delete().

2. EO_Element{ApiCode} — класс-объект. Представляет одну запись. Через него выполняется работа с полями: $element->getName(), $element->setName(), $element->save().

3. EO_Element{ApiCode}_Collection — класс-коллекция. Представляет набор объектов-записей. Позволяет перебирать записи в цикле и выполнять групповые операции.

Для разделов создается аналогичная тройка классов, но в именах используется ID инфоблока: Section{ID}Table, EO_Section{ID}, EO_Section{ID}_Collection.

Пример работы c разными классами:

use Bitrix\Iblock\Elements\ElementClothesTable;
        
        // 1. Table: получаем данные
        $collection = ElementClothesTable::getList()->fetchCollection();
        
        // 2. Collection: работаем с набором
        foreach ($collection as $element)
        {
            // 3. Object: меняем каждую запись
            $element->setSort(100);
        }
        
        // 4. Collection: сохраняем все изменения
        $collection->save();
        

Архитектура наследованияАрхитектура наследования

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

1. Повторное использование кода. Стандартная логика CRUD-операций (Create, Read, Update and Delete) реализована в базовых классах.

2. Специализация. Ваш класс автоматически знает структуру именно вашего инфоблока: свойства и поля.

3. Расширяемость. Вы можете унаследовать сгенерированный класс и добавить свою логику.

Схема наследования для элементов.

\Bitrix\Iblock\ElementTable — общая таблица для элементов
                 ↑
        \Bitrix\Iblock\Elements\ElementTable — база для генерации
                 ↑
        \Bitrix\Iblock\Elements\Element{ApiCode}Table — ваш класс для работы с элементами конкретного инфоблока
        

Схема наследования для разделов.

\Bitrix\Iblock\SectionTable — общая таблица разделов
                 ↑
        \Bitrix\Iblock\Section{ID}Table — ваш класс для работы с разделами конкретного инфоблока
        

Пример. Расширение класса для инфоблока с API_CODE = Clothes.

// Создаем свой класс на основе сгенерированного
        class MyClothesTable extends \Bitrix\Iblock\Elements\ElementClothesTable
        {
            public static function getActiveClothes()
            {
                return static::getList([
                    'filter' => ['ACTIVE' => 'Y'],
                    'order' => ['SORT' => 'ASC']
                ])->fetchCollection();
            }
        }
        

Карты классовКарты классов

Каждый ORM-класс содержит метод getMap(). Он возвращает описание структуры таблицы: поля, типы полей, связи с другими сущностями и правила валидации. Система использует карту класса для следующих задач:

• строит SQL-запросы,

• преобразует данные между PHP и базой данных,

• проверяет типы данных при сохранении,

• организует связи между таблицами.

Классы вида Element{ApiCode}Table получают расширенную карту: базовые поля элементов и все пользовательские свойства инфоблока как связи ORM.

Формат ответаФормат ответа

Метод getMap() возвращает данные в одном из двух форматов, в зависимости от реализации класса.

1. Индексированный массив объектов полей — современный формат. Каждый элемент массива — объект, который наследуется от Bitrix\Main\ORM\Fields\Field. Например, StringField, IntegerField, Reference и так далее. Имя поля задается в конструкторе объекта и не зависит от ключа массива.

   Подход обеспечивает строгую типизацию, поддержку валидаторов, модификаторов, связей и расширяемость.

2. Ассоциативный массив с именами полей в качестве ключей — устаревший формат. Каждый ключ — имя поля, значение — массив с описанием data_type, title, validation и так далее. Не поддерживает сложные типы полей и объектную логику.

Пример ответа метода getMap() для ElementTable.

Array
        (
            [ID] => Bitrix\Main\ORM\Fields\IntegerField Object
                (
                    [name:protected] => ID
                    [dataType:protected] => 
                    [initialParameters:protected] => Array
                        (
                            [primary] => 1
                            [autocomplete] => 1
                            [title] => Идентификатор
                        )
        
                    [title:protected] => Идентификатор
                    [validation:protected] => 
                    [validators:protected] => 
                    [additionalValidators:protected] => Array()
        
                    [fetchDataModification:protected] => 
                    [fetchDataModifiers:protected] => 
                    [additionalFetchDataModifiers:protected] => Array()
        
                    [saveDataModification:protected] => 
                    [saveDataModifiers:protected] => 
                    [additionalSaveDataModifiers:protected] => Array()
        
                    [isSerialized:protected] => 
                    [parentField:protected] => 
                    [entity:protected] => 
                    [connection:protected] => 
                    [is_primary:protected] => 1
                    [is_unique:protected] => 
                    [is_required:protected] => 
                    [is_autocomplete:protected] => 1
                    [is_private:protected] => 
                    [is_nullable:protected] => 
                    [is_binary:protected] => 
                    [is_fulltext:protected] => 
                    [column_name:protected] => ID
                    [default_value:protected] => 
                    [size:protected] => 4
                )
        
            [TIMESTAMP_X] => Bitrix\Main\ORM\Fields\DatetimeField Object
                (
                    [name:protected] => TIMESTAMP_X
                    ...
                )
            ...
        )
        

Описание полей классов таблицОписание полей классов таблиц

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

ID — это числовой ключ сущности. У каждого типа, инфоблока, раздела, элемента и свойства есть уникальный ID. По этому ключу система связывает данные между таблицами.

Тип информационного блокаТип информационного блока

Класс Bitrix\Iblock\TypeTable работает с таблицей типов инфоблоков. Типы определяют категории для группировки инфоблоков — например, news для новостей или catalog для товаров. Параметры применяются ко всем инфоблокам одного типа.

Информационный блокИнформационный блок

Класс Bitrix\Iblock\IblockTable хранит основные настройки каждого инфоблока. Каждый инфоблок ссылается на свой тип через поле IBLOCK_TYPE_ID.

Привязка инфоблока к сайтамПривязка инфоблока к сайтам

Класс Bitrix\Iblock\IblockSiteTable управляет доступностью инфоблоков на разных сайтах. Один инфоблок может принадлежать нескольким сайтам — для каждой связи создают отдельную запись. Это позволяет использовать общий каталог товаров или новостей в рамках нескольких проектов.

Инфоблок может принадлежать нескольким сайтам. Для каждой связи создают отдельную строку.

РазделыРазделы

Класс Bitrix\Iblock\SectionTable работает с иерархической структурой разделов. Разделы организуют элементы в дерево — например, категории товаров или разделы статей. Таблица хранит основные данные разделов и технические поля для работы с вложенностью.

ЭлементыЭлементы

Класс Bitrix\Iblock\ElementTable хранит основные данные элементов — товаров, новостей, статей. Здесь находятся общие для всех типов элементов поля: названия, описания, изображения, даты и флаги активности. Специфичные данные система хранит в свойствах.

Привязка элементов к разделамПривязка элементов к разделам

Класс Bitrix\Iblock\SectionElementTable управляет связями между элементами и разделами. Один элемент может принадлежать к нескольким разделам одновременно — например, товар может быть в категориях Ноутбуки и Распродажа. Каждую такую связь система хранит отдельной строкой.

Свойства инфоблокаСвойства инфоблока

Класс Bitrix\Iblock\PropertyTable определяет дополнительные поля для элементов и разделов. Свойства расширяют базовую структуру — добавляют цвета к товарам, файлы к документам, теги к статьям. В таблице хранятся тип свойства, обязательность, множественность и другие параметры.

Значения списочных свойствЗначения списочных свойств

Класс Bitrix\Iblock\PropertyEnumerationTable хранит варианты значений для свойств типа Список. Например, варианты цвета или статусы заказа.

СвойстваСвойства

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

Базовые типы свойствБазовые типы свойств

Строка Строка S

Значение хранится как текст. Длина текста ограничена типом поля базы данных.

В форме редактирования можно задавать визуальные ограничения через поля ROW_COUNT и COL_COUNT. Значение по умолчанию должно быть строкой, числом или булевым значением. Массивы не поддерживаются.

Число Число N

Значение хранится как число. Операции сортировки и сравнения работают с числами.

Пустое значение система воспринимает как NULL. Строку, которую нельзя привести к числу, система не принимает и отдает ошибку при фильтрации или сохранении. Значение по умолчанию должно быть числом или строкой, которую можно привести к числу.

Список Список L

Значения списка хранятся в отдельной таблице b_iblock_property_enum. Пользователь выбирает значение из заранее заданного списка.

Каждое значение списка VALUE должно содержать непустой текст. Поле XML_ID должно быть уникальным в рамках одного свойства. Система проверяет, используют ли элементы значения списка, перед их удалением или изменением.

Файл Файл F

Значение хранит идентификатор файла из таблицы b_file. Вы можете ограничивать типы загружаемых файлов через маску в поле FILE_TYPE.

Каждый загружаемый файл проходит проверку через систему CFile. Система проверяет размер файла, расширение и другие параметры.

Привязка к элементу Привязка к элементу E

Значение — ID элемента другого инфоблока. Если в настройках свойства задано поле LINK_IBLOCK_ID, то значение должно ссылаться на элемент существующего инфоблока.

Система проверяет существование элемента при сохранении. Некоторые настройки становятся недоступны при использовании этого свойства в умном фильтре.

Привязка к разделу Привязка к разделу G

Значение — ID раздела инфоблока. Система проверяет, что раздел существует и принадлежит указанному инфоблоку. Работает аналогично типу E.

Пользовательские типы свойствПользовательские типы свойств

Система предоставляет дополнительные типы свойств. Они расширяют базовые типы и добавляют специальную логику.

Типы Главного модуляТипы Главного модуля

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

• Date и DateTime — для работы с датами и временем. Используют виджеты выбора даты.

• ElementXmlID — привязка к элементу по внешнему идентификатору XML_ID для обмена данными.

• FileMan — путь к файлу в структуре сайта. Использует диалог выбора файлов.

• HTML — текст в формате HTML с визуальным редактором. Не поддерживает множественные значения.

• EList — выпадающий список элементов из другого инфоблока. Аналогичен типу Привязка к элементу E , но с отдельным интерфейсом.

• Sequence — автоматический счетчик. Значение увеличивается при создании каждого нового элемента.

• EAutocomplete и SectionAuto — привязка к элементам и разделам с автодополнением.

Типы других модулейТипы других модулей

Специализированные модули добавляют свои типы свойств. Эти типы становятся доступны после установки соответствующего модуля и обеспечивают интеграцию с его функциональностью.

• SKU — связь с торговыми предложениями из модуля Торговый каталог.

• ECrm — привязка к объектам CRM: лидам, сделкам, контактам, компаниям и так далее.

• Money — денежная сумма с указанием валюты.

• DiskFile — файл из модуля Диск.

• map_google, map_yandex — координаты на карте.

• TopicID — привязка к теме форума.

• directory — связь с highload-блоком.

• UserID — привязка к пользователям.

• employee — привязка к сотрудникам.

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

Система проверяет свойства при сохранении. Основные ограничения:

• Поле NAME обязательное и не может быть пустым.

• Поле CODE должно соответствовать правилам:

  • не может начинаться с цифры,

  • может содержать только латинские буквы, цифры и символ подчеркивания,

  • должно быть уникальным в пределах инфоблока.

• Поле IBLOCK_ID должно ссылаться на существующий инфоблок.

• Для простых типов без USER_TYPE значение DEFAULT_VALUE должно быть скалярным — массив или объект вызовут ошибку.

• Если свойство обязательное IS_REQUIRED = 'Y', система проверяет, чтобы значение было заполнено при сохранении элемента.

Особенности привязки к элементам и разделамОсобенности привязки к элементам и разделам

Для типов свойств привязка к элементу E и привязка к разделу G действуют дополнительные правила.

• Система ожидает целочисленный ID элемента или раздела.

• Если задан LINK_IBLOCK_ID, значение должно ссылаться на объект из указанного инфоблока.

• Для множественных свойств значения хранятся в специальных таблицах.

• ORM представляет эти связи как отношения между сущностями.

Эти ограничения обеспечивают целостность данных и правильную работу фильтрации и сортировки.

Как выбрать тип свойстваКак выбрать тип свойства

Выбор типа свойства влияет на хранение данных, производительность и возможности фильтрации.

Число или строкаЧисло или строка

Используйте тип Число N:

• для сортировки значений по величине,

• применения диапазонных фильтров,

• вычислений или агрегации данных.

Примеры: цены, веса, рейтинги, вычисление суммы или средних значений.

Используйте тип Строка S, если:

• значение содержит буквы и специальные символы,

• важнее поиск по подстроке, чем числовые операции,

• значение имеет сложный формат.

Примеры: артикулы, коды, сложные значения вида A-001-2025.

Список, справочник или привязкаСписок, справочник или привязка

Обычный список L подходит:

• для небольшого набора значений,

• значений, которые редко меняются,

• простого управления через форму свойства.

Примеры: статусы, типы, цвета из короткого списка.

Справочник на highload-блоке directory используйте:

• для большого количества значений в сотнях или тысячах,

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

• сложных классификаторов, которые требуют отдельного управления.

Привязку к элементам E или разделам G рекомендуется использовать, когда:

• значение представляет собой самостоятельный объект с собственной логикой,

• нужны обратные связи и сложные выборки через ORM,

• значение имеет свою карточку с дополнительными полями.

Когда применять пользовательские типыКогда применять пользовательские типы

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

• HTML — для текста с форматированием: описания, статьи.

• Date/DateTime — для отдельных дат: дата поставки, начало акции.

• Sequence — для автоматической нумерации: номера заказов, документов.

• ElementXmlID — для интеграции с внешними системами по внешним ключам.

• ECrm, UserID — для связи с объектами CRM или пользователями.

• map_* — для хранения координат на карте.

Множественные значения и описанияМножественные значения и описания

Опция MULTIPLE = 'Y' дает возможность указывать для свойства несколько значений, например, цветов, размеров, связанных товаров. Если свойство множественное, можно дополнительно включить опцию WITH_DESCRIPTION = 'Y'. Она позволяет добавить текстовый комментарий к каждому отдельному значению

Обратная совместимостьОбратная совместимость

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

API работы с элементамиAPI работы с элементами

При добавлении, изменении, удалении элементов отдельно нужно реализовывать:

• ресайз изображений PREVIEW_PICTURE и DETAIL_PICTURE,

• автоматическое обновление фасетного индекса,

• автоматическое обновление SEO-параметров элемента,

• автоматический сброс тегированного кеша,

• установку прав доступа,

• поддержку документооборота,

• проверку дисковой квоты для файловых свойств,

• пересчет доступности товаров с торговыми предложениями,

• пересчет цен для сортировки товаров с торговыми предложениями,

• индексацию модулем поиска,

• логирование операций с элементами,

• автоматическую генерацию символьного кода.

При получении списков элементов:

• проверку прав доступа,

• автоматическую фильтрацию неопубликованных элементов при использовании документооборота.

API работы с разделамиAPI работы с разделами

При добавлении, изменении, удалении разделов отдельно нужно реализовывать:

• автоматический пересчет полей иерархии LEFT_MARGIN, RIGHT_MARGIN, GLOBAL_ACTIVE, DEPTH_LEVEL,

• ресайз изображений раздела,

• обновление фасетного индекса,

• обновление SEO-параметров раздела и его дочерних объектов,

• сброс тегированного кеша,

• установку прав доступа на раздел и его содержимое,

• проверку дисковой квоты для файловых полей,

• индексацию модулем поиска,

• автоматическую привязку свойств к разделам,

• логирование операций с разделами,

• автоматическую генерацию символьного кода.

При получении списков разделов:

• проверку прав доступа.