Модули коробки / Инфоблоки

Один вызов Fetch() для результата GetProperty() возвращает только очередное значение. Для множественного свойства собирайте все строки. Примеры записи через старое API здесь не означают, что ElementTable поддерживает тот же набор изменений; новые ORM-сущности инфоблоков — отдельный механизм.

Примеры внутреннего PHP API предназначены для коробки с подключённым ядром. Прямое чтение таблиц здесь — административная диагностика: оно само по себе не проверяет доступ пользователя к найденным объектам. Не публикуйте такой код как открытый HTTP-обработчик.

Общее понимание

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

Подключение модуля

<?php

use Bitrix\Main\Loader;

if (!Loader::includeModule('iblock')) {
    throw new \RuntimeException('Модуль iblock не загружен');
}

<?php

use Bitrix\Main\Loader;

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

requireIblockModule();

Старое API и D7

API	Когда использовать
`CIBlockElement`	Добавление, изменение, удаление элементов, работа со свойствами.
`CIBlockSection`	Разделы инфоблока.
`ElementTable`	Чтение элементов через D7 ORM.
`SectionTable`	Чтение разделов через D7 ORM.

Главное правило: если нужно менять элементы и свойства, не спеши заменять старый API на D7. В инфоблоках D7-подход имеет ограничения.

Карта методов

Метод	Что делает	Когда использовать
`CIBlockElement::GetList()`	Получает список элементов.	Основной способ выборки элементов и полей.
`CIBlockElement::GetByID()`	Получает элемент по ID.	Быстро посмотреть элемент без фильтра активности.
`$element->Add()`	Добавляет элемент.	Создание элементов с полями и свойствами.
`$element->Update()`	Изменяет элемент.	Обновление полей элемента.
`CIBlockElement::Delete()`	Удаляет элемент.	Служебное удаление элемента.
`CIBlockElement::GetProperty()`	Получает свойства элемента.	Когда нужны значения свойств.
`CIBlockElement::SetPropertyValues()`	Сохраняет значения свойств.	Когда передаётся полный набор значений.
`CIBlockElement::SetPropertyValuesEx()`	Обновляет свойства без сброса неуказанных.	Точечное изменение свойств.
`CIBlockElement::SetPropertyValueCode()`	Обновляет одно свойство по коду.	Быстро изменить одно свойство.
`CIBlockElement::GetElementGroups()`	Получает разделы элемента.	Проверить, где лежит элемент.
`CIBlockElement::UpdateSearch()`	Переиндексирует элемент для поиска.	После служебных изменений, если нужен поиск.
`CIBlockSection::GetList()`	Получает разделы.	Дерево разделов и фильтрация по разделам.

Что хранится в инфоблоке

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

Элементы

Базовая работа с элементами через старый API.

Получить элементы через CIBlockElement

<?php

use Bitrix\Main\Loader;

if (!Loader::includeModule('iblock')) {
    throw new \RuntimeException('Модуль iblock не загружен');
}

function fetchIblockElements(int $iblock_id): array {
    if ($iblock_id <= 0) {
        return [];
    }

    $elements = [];

    $element_result = \CIBlockElement::GetList(
        [
            'ID' => 'ASC',
        ],
        [
            'IBLOCK_ID' => $iblock_id,
            'ACTIVE' => 'Y',
        ],
        false,
        [
            'nTopCount' => 100,
        ],
        [
            'ID',
            'IBLOCK_ID',
            'NAME',
            'ACTIVE',
            'DATE_CREATE',
        ]
    );

    while ($element = $element_result->Fetch()) {
        $elements[] = $element;
    }

    return $elements;
}

$elements = fetchIblockElements($iblock_id);

print_r($elements);

Получить элемент по ID

<?php

use Bitrix\Main\Loader;

if (!Loader::includeModule('iblock')) {
    throw new \RuntimeException('Модуль iblock не загружен');
}

function fetchIblockElementById(int $element_id): array {
    if ($element_id <= 0) {
        return [];
    }

    $element = \CIBlockElement::GetByID($element_id)->Fetch();

    return is_array($element) ? $element : [];
}

$element = fetchIblockElementById($element_id);

print_r($element);

GetByID() не заменяет полноценный фильтр через GetList(), если нужно учитывать активность элемента и другие условия.

Добавить элемент

<?php

use Bitrix\Main\Loader;

if (!Loader::includeModule('iblock')) {
    throw new \RuntimeException('Модуль iblock не загружен');
}

function addIblockElement(int $iblock_id, string $name, array $property_values = []): array {
    if ($iblock_id <= 0 || $name === '') {
        return [
            'is_success' => false,
            'element_id' => 0,
            'error_messages' => ['Не заполнены обязательные поля'],
        ];
    }

    $element = new \CIBlockElement();

    $element_fields = [
        'IBLOCK_ID' => $iblock_id,
        'NAME' => $name,
        'ACTIVE' => 'Y',
        'PROPERTY_VALUES' => $property_values,
    ];

    $element_id = (int) $element->Add($element_fields);

    return [
        'is_success' => $element_id > 0,
        'element_id' => $element_id,
        'error_messages' => $element_id > 0 ? [] : [$element->LAST_ERROR],
    ];
}

$result = addIblockElement(
    $iblock_id,
    $name,
    [
        'COLOR' => 'red',
    ]
);

print_r($result);

Изменить элемент

<?php

use Bitrix\Main\Loader;

if (!Loader::includeModule('iblock')) {
    throw new \RuntimeException('Модуль iblock не загружен');
}

function updateIblockElement(int $element_id, array $element_fields): array {
    if ($element_id <= 0) {
        return [
            'is_success' => false,
            'error_messages' => ['ID элемента не заполнен'],
        ];
    }

    $element = new \CIBlockElement();

    $is_updated = $element->Update($element_id, $element_fields);

    return [
        'is_success' => (bool) $is_updated,
        'error_messages' => $is_updated ? [] : [$element->LAST_ERROR],
    ];
}

$result = updateIblockElement($element_id, [
    'NAME' => $name,
    'ACTIVE' => 'Y',
]);

print_r($result);

Удалить элемент

<?php

use Bitrix\Main\Loader;

if (!Loader::includeModule('iblock')) {
    throw new \RuntimeException('Модуль iblock не загружен');
}

function deleteIblockElement(int $element_id): bool {
    if ($element_id <= 0) {
        return false;
    }

    return (bool) \CIBlockElement::Delete($element_id);
}

$is_deleted = deleteIblockElement($element_id);

var_dump($is_deleted);

Свойства и разделы

D7 можно использовать для чтения, а свойства часто проще читать и менять через старый API.

ElementTable для чтения

<?php

use Bitrix\Main\Loader;
use Bitrix\Iblock\ElementTable;

if (!Loader::includeModule('iblock')) {
    throw new \RuntimeException('Модуль iblock не загружен');
}

function fetchIblockElementsByD7(int $iblock_id): array {
    if ($iblock_id <= 0) {
        return [];
    }

    return ElementTable::getList([
        'select' => [
            'ID',
            'IBLOCK_ID',
            'NAME',
            'ACTIVE',
            'DATE_CREATE',
        ],
        'filter' => [
            '=IBLOCK_ID' => $iblock_id,
            '=ACTIVE' => 'Y',
        ],
        'order' => [
            'ID' => 'ASC',
        ],
        'limit' => 100,
    ])->fetchAll();
}

$elements = fetchIblockElementsByD7($iblock_id);

print_r($elements);

Для добавления и изменения элементов лучше использовать CIBlockElement, если нет отдельной проверенной D7-схемы под конкретный тип инфоблока.

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

<?php

use Bitrix\Main\Loader;

if (!Loader::includeModule('iblock')) {
    throw new \RuntimeException('Модуль iblock не загружен');
}

function fetchElementProperties(int $iblock_id, int $element_id): array {
    if ($iblock_id <= 0 || $element_id <= 0) {
        return [];
    }

    $properties = [];

    $property_result = \CIBlockElement::GetProperty(
        $iblock_id,
        $element_id,
        [
            'sort' => 'asc',
        ],
        []
    );

    while ($property = $property_result->Fetch()) {
        $properties[] = $property;
    }

    return $properties;
}

$properties = fetchElementProperties($iblock_id, $element_id);

print_r($properties);

Получить одно свойство

<?php

use Bitrix\Main\Loader;

if (!Loader::includeModule('iblock')) {
    throw new \RuntimeException('Модуль iblock не загружен');
}

function fetchElementPropertyValue(int $iblock_id, int $element_id, string $property_code) {
    if ($iblock_id <= 0 || $element_id <= 0 || $property_code === '') {
        return null;
    }

    $property_result = \CIBlockElement::GetProperty(
        $iblock_id,
        $element_id,
        [
            'sort' => 'asc',
        ],
        [
            'CODE' => $property_code,
        ]
    );

    $property = $property_result->Fetch();

    return is_array($property) ? $property['VALUE'] : null;
}

$value = fetchElementPropertyValue($iblock_id, $element_id, 'COLOR');

var_dump($value);

Обновить свойства

Для точечного обновления свойств обычно удобнее SetPropertyValuesEx(), потому что он не требует передавать полный набор свойств элемента.

<?php

use Bitrix\Main\Loader;

if (!Loader::includeModule('iblock')) {
    throw new \RuntimeException('Модуль iblock не загружен');
}

function updateElementProperties(int $iblock_id, int $element_id, array $property_values): void {
    if ($iblock_id <= 0 || $element_id <= 0 || empty($property_values)) {
        return;
    }

    \CIBlockElement::SetPropertyValuesEx(
        $element_id,
        $iblock_id,
        $property_values
    );
}

updateElementProperties($iblock_id, $element_id, [
    'COLOR' => 'red',
    'SIZE' => 'XL',
]);

Обновить свойство по коду

<?php

use Bitrix\Main\Loader;

if (!Loader::includeModule('iblock')) {
    throw new \RuntimeException('Модуль iblock не загружен');
}

function updateElementPropertyByCode(int $element_id, string $property_code, $property_value): void {
    if ($element_id <= 0 || $property_code === '') {
        return;
    }

    \CIBlockElement::SetPropertyValueCode(
        $element_id,
        $property_code,
        $property_value
    );
}

updateElementPropertyByCode($element_id, 'COLOR', 'red');

Разделы элемента

<?php

use Bitrix\Main\Loader;

if (!Loader::includeModule('iblock')) {
    throw new \RuntimeException('Модуль iblock не загружен');
}

function fetchElementSectionIds(int $element_id): array {
    if ($element_id <= 0) {
        return [];
    }

    $section_ids = [];

    $section_result = \CIBlockElement::GetElementGroups(
        $element_id,
        true,
        [
            'ID',
            'IBLOCK_ELEMENT_ID',
        ]
    );

    while ($section = $section_result->Fetch()) {
        $section_ids[] = (int) $section['ID'];
    }

    return $section_ids;
}

$section_ids = fetchElementSectionIds($element_id);

print_r($section_ids);

Разделы инфоблока

<?php

use Bitrix\Main\Loader;

if (!Loader::includeModule('iblock')) {
    throw new \RuntimeException('Модуль iblock не загружен');
}

function fetchIblockSections(int $iblock_id): array {
    if ($iblock_id <= 0) {
        return [];
    }

    $sections = [];

    $section_result = \CIBlockSection::GetList(
        [
            'LEFT_MARGIN' => 'ASC',
        ],
        [
            'IBLOCK_ID' => $iblock_id,
            'ACTIVE' => 'Y',
        ],
        false,
        [
            'ID',
            'IBLOCK_ID',
            'NAME',
            'IBLOCK_SECTION_ID',
            'DEPTH_LEVEL',
        ]
    );

    while ($section = $section_result->Fetch()) {
        $sections[] = $section;
    }

    return $sections;
}

$sections = fetchIblockSections($iblock_id);

print_r($sections);

Переиндексация поиска

<?php

use Bitrix\Main\Loader;

if (!Loader::includeModule('iblock')) {
    throw new \RuntimeException('Модуль iblock не загружен');
}

function updateElementSearchIndex(int $element_id): void {
    if ($element_id <= 0) {
        return;
    }

    \CIBlockElement::UpdateSearch($element_id, true);
}

updateElementSearchIndex($element_id);