Модули коробки / Инфоблоки | Битрикс дилетант

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

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

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

<?php

use Bitrix\Main\Loader;

Loader::includeModule('iblock');

<?php

use Bitrix\Main\Loader;

/**
 * Подключает модуль iblock.
 */
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;

Loader::includeModule('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;

Loader::includeModule('iblock');

/**
 * Получает элемент инфоблока по ID.
 */
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;

Loader::includeModule('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;

Loader::includeModule('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;

Loader::includeModule('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;

Loader::includeModule('iblock');

/**
 * Получает элементы через D7.
 */
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;

Loader::includeModule('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;

Loader::includeModule('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;

Loader::includeModule('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;

Loader::includeModule('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;

Loader::includeModule('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;

Loader::includeModule('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;

Loader::includeModule('iblock');

/**
 * Переиндексирует элемент инфоблока для поиска.
 */
function updateElementSearchIndex(int $element_id): void
{
    if ($element_id <= 0) {
        return;
    }

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

updateElementSearchIndex($element_id);