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

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

Highload-блоки часто используют для справочников, настроек и больших простых таблиц.

Что такое highload-блок

HL-блок хранит описание таблицы, а сами элементы лежат в отдельной таблице. Поля элементов обычно являются пользовательскими полями и имеют коды вида UF_NAME, UF_XML_ID, UF_SORT.

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

<?php

use Bitrix\Main\Loader;

Loader::includeModule('highloadblock');

<?php

use Bitrix\Main\Loader;

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

requireHighloadBlockModule();

Когда использовать

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

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

Метод	Что делает	Когда использовать
`HighloadBlockTable::getList()`	Ищет HL-блоки.	Найти блок по имени таблицы или другим полям.
`HighloadBlockTable::getById()`	Получает HL-блок по ID.	Когда ID блока уже известен.
`HighloadBlockTable::add()`	Создаёт HL-блок.	Миграции и установка модуля.
`HighloadBlockTable::update()`	Изменяет параметры HL-блока.	Переименование или служебное изменение.
`HighloadBlockTable::delete()`	Удаляет HL-блок.	Удаление тестовых или модульных таблиц.
`HighloadBlockTable::compileEntity()`	Компилирует ORM-сущность элементов.	Перед работой с элементами.
`HighloadBlockTable::compileEntityId()`	Возвращает ENTITY_ID пользовательских полей.	Добавление и поиск UF-полей HL-блока.
`$data_class::getList()`	Получает элементы HL-блока.	Справочники, настройки, отчёты.
`$data_class::add()`	Добавляет элемент.	Заполнение справочника.
`$data_class::update()`	Изменяет элемент.	Обновление значения справочника.
`$data_class::delete()`	Удаляет элемент.	Удаление записи HL-блока.

HighloadBlockTable

Через HighloadBlockTable работают с самим HL-блоком как с описанием таблицы.

Получить HL-блок по ID

<?php

use Bitrix\Main\Loader;
use Bitrix\Highloadblock\HighloadBlockTable;

Loader::includeModule('highloadblock');

/**
 * Получает описание HL-блока по ID.
 */
function fetchHighloadBlockById(int $highload_block_id): array
{
    if ($highload_block_id <= 0) {
        return [];
    }

    $highload_block = HighloadBlockTable::getById($highload_block_id)->fetch();

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

$highload_block = fetchHighloadBlockById($highload_block_id);

print_r($highload_block);

Найти HL-блок по таблице

<?php

use Bitrix\Main\Loader;
use Bitrix\Highloadblock\HighloadBlockTable;

Loader::includeModule('highloadblock');

/**
 * Получает HL-блок по имени таблицы.
 */
function fetchHighloadBlockByTableName(string $table_name): array
{
    if ($table_name === '') {
        return [];
    }

    $highload_block = HighloadBlockTable::getList([
        'select' => [
            'ID',
            'NAME',
            'TABLE_NAME',
        ],
        'filter' => [
            '=TABLE_NAME' => $table_name,
        ],
        'limit' => 1,
    ])->fetch();

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

$highload_block = fetchHighloadBlockByTableName('b_hlbd_colors');

print_r($highload_block);

Создать HL-блок

<?php

use Bitrix\Main\Loader;
use Bitrix\Highloadblock\HighloadBlockTable;

Loader::includeModule('highloadblock');

/**
 * Создаёт HL-блок.
 */
function addHighloadBlock(string $name, string $table_name): array
{
    if ($name === '' || $table_name === '') {
        return [
            'is_success' => false,
            'highload_block_id' => 0,
            'error_messages' => ['Не заполнены имя или таблица'],
        ];
    }

    $result = HighloadBlockTable::add([
        'NAME' => $name,
        'TABLE_NAME' => $table_name,
    ]);

    return [
        'is_success' => $result->isSuccess(),
        'highload_block_id' => (int) $result->getId(),
        'error_messages' => $result->getErrorMessages(),
    ];
}

$result = addHighloadBlock('Colors', 'b_hlbd_colors');

print_r($result);

Изменить HL-блок

<?php

use Bitrix\Highloadblock\HighloadBlockTable;

/**
 * Изменяет имя HL-блока.
 */
function updateHighloadBlockName(int $highload_block_id, string $name): array
{
    if ($highload_block_id <= 0 || $name === '') {
        return [
            'is_success' => false,
            'error_messages' => ['Не заполнены данные'],
        ];
    }

    $result = HighloadBlockTable::update($highload_block_id, [
        'NAME' => $name,
    ]);

    return [
        'is_success' => $result->isSuccess(),
        'error_messages' => $result->getErrorMessages(),
    ];
}

$result = updateHighloadBlockName($highload_block_id, 'Colors');

print_r($result);

Удалить HL-блок

<?php

use Bitrix\Highloadblock\HighloadBlockTable;

/**
 * Удаляет HL-блок.
 */
function deleteHighloadBlock(int $highload_block_id): array
{
    if ($highload_block_id <= 0) {
        return [
            'is_success' => false,
            'error_messages' => ['ID HL-блока не заполнен'],
        ];
    }

    $result = HighloadBlockTable::delete($highload_block_id);

    return [
        'is_success' => $result->isSuccess(),
        'error_messages' => $result->getErrorMessages(),
    ];
}

$result = deleteHighloadBlock($highload_block_id);

print_r($result);

DataClass и поля

Для работы с элементами нужен DataClass конкретного HL-блока.

compileEntity

<?php

use Bitrix\Highloadblock\HighloadBlockTable;

/**
 * Компилирует сущность HL-блока.
 */
function compileHighloadBlockEntity(array $highload_block)
{
    if (empty($highload_block)) {
        return null;
    }

    return HighloadBlockTable::compileEntity($highload_block);
}

$entity = compileHighloadBlockEntity($highload_block);

Получить DataClass

<?php

use Bitrix\Highloadblock\HighloadBlockTable;

/**
 * Получает DataClass HL-блока.
 */
function fetchHighloadBlockDataClass(int $highload_block_id): string
{
    $highload_block = fetchHighloadBlockById($highload_block_id);

    if (empty($highload_block)) {
        return '';
    }

    $entity = HighloadBlockTable::compileEntity($highload_block);

    return $entity->getDataClass();
}

$data_class = fetchHighloadBlockDataClass($highload_block_id);

echo $data_class;

ENTITY_ID пользовательских полей

<?php

use Bitrix\Highloadblock\HighloadBlockTable;

/**
 * Получает ENTITY_ID пользовательских полей HL-блока.
 */
function fetchHighloadBlockUserFieldEntityId(int $highload_block_id): string
{
    if ($highload_block_id <= 0) {
        return '';
    }

    return HighloadBlockTable::compileEntityId($highload_block_id);
}

$entity_id = fetchHighloadBlockUserFieldEntityId($highload_block_id);

echo $entity_id;

Добавить пользовательское поле

<?php

use Bitrix\Main\Loader;
use Bitrix\Highloadblock\HighloadBlockTable;

Loader::includeModule('highloadblock');

/**
 * Добавляет строковое пользовательское поле к HL-блоку.
 */
function addHighloadBlockStringField(int $highload_block_id, string $field_name, string $label): int
{
    if ($highload_block_id <= 0 || $field_name === '') {
        return 0;
    }

    $entity_id = HighloadBlockTable::compileEntityId($highload_block_id);

    $user_type_entity = new \CUserTypeEntity();

    $field_id = $user_type_entity->Add([
        'ENTITY_ID' => $entity_id,
        'FIELD_NAME' => $field_name,
        'USER_TYPE_ID' => 'string',
        'XML_ID' => $field_name,
        'SORT' => 100,
        'MULTIPLE' => 'N',
        'MANDATORY' => 'N',
        'SHOW_FILTER' => 'I',
        'SHOW_IN_LIST' => 'Y',
        'EDIT_IN_LIST' => 'Y',
        'IS_SEARCHABLE' => 'N',
        'EDIT_FORM_LABEL' => [
            'ru' => $label,
            'en' => $label,
        ],
        'LIST_COLUMN_LABEL' => [
            'ru' => $label,
            'en' => $label,
        ],
        'LIST_FILTER_LABEL' => [
            'ru' => $label,
            'en' => $label,
        ],
    ]);

    return (int) $field_id;
}

$field_id = addHighloadBlockStringField(
    $highload_block_id,
    'UF_COLOR_NAME',
    'Название цвета'
);

echo $field_id;

Элементы HL-блока

После получения DataClass элементы читаются и изменяются как обычная ORM-таблица.

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

<?php

use Bitrix\Main\Loader;

Loader::includeModule('highloadblock');

const HIGHLOAD_BLOCK_LIMIT = 100;

/**
 * Получает элементы HL-блока.
 */
function fetchHighloadBlockItems(int $highload_block_id, array $filter = []): array
{
    $data_class = fetchHighloadBlockDataClass($highload_block_id);

    if ($data_class === '') {
        return [];
    }

    return $data_class::getList([
        'select' => [
            'ID',
            'UF_NAME',
            'UF_XML_ID',
        ],
        'filter' => $filter,
        'order' => [
            'ID' => 'ASC',
        ],
        'limit' => HIGHLOAD_BLOCK_LIMIT,
    ])->fetchAll();
}

$items = fetchHighloadBlockItems($highload_block_id, [
    '=UF_ACTIVE' => 1,
]);

print_r($items);

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

<?php

/**
 * Добавляет элемент HL-блока.
 */
function addHighloadBlockItem(int $highload_block_id, array $item_fields): array
{
    $data_class = fetchHighloadBlockDataClass($highload_block_id);

    if ($data_class === '') {
        return [
            'is_success' => false,
            'item_id' => 0,
            'error_messages' => ['DataClass не найден'],
        ];
    }

    $result = $data_class::add($item_fields);

    return [
        'is_success' => $result->isSuccess(),
        'item_id' => (int) $result->getId(),
        'error_messages' => $result->getErrorMessages(),
    ];
}

$result = addHighloadBlockItem($highload_block_id, [
    'UF_NAME' => $name,
    'UF_XML_ID' => $xml_id,
]);

print_r($result);

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

<?php

/**
 * Изменяет элемент HL-блока.
 */
function updateHighloadBlockItem(int $highload_block_id, int $item_id, array $item_fields): array
{
    $data_class = fetchHighloadBlockDataClass($highload_block_id);

    if ($data_class === '') {
        return [
            'is_success' => false,
            'error_messages' => ['DataClass не найден'],
        ];
    }

    if ($item_id <= 0) {
        return [
            'is_success' => false,
            'error_messages' => ['ID элемента не заполнен'],
        ];
    }

    $result = $data_class::update($item_id, $item_fields);

    return [
        'is_success' => $result->isSuccess(),
        'error_messages' => $result->getErrorMessages(),
    ];
}

$result = updateHighloadBlockItem($highload_block_id, $item_id, [
    'UF_NAME' => $name,
]);

print_r($result);

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

<?php

/**
 * Удаляет элемент HL-блока.
 */
function deleteHighloadBlockItem(int $highload_block_id, int $item_id): array
{
    $data_class = fetchHighloadBlockDataClass($highload_block_id);

    if ($data_class === '') {
        return [
            'is_success' => false,
            'error_messages' => ['DataClass не найден'],
        ];
    }

    if ($item_id <= 0) {
        return [
            'is_success' => false,
            'error_messages' => ['ID элемента не заполнен'],
        ];
    }

    $result = $data_class::delete($item_id);

    return [
        'is_success' => $result->isSuccess(),
        'error_messages' => $result->getErrorMessages(),
    ];
}

$result = deleteHighloadBlockItem($highload_block_id, $item_id);

print_r($result);