Query API: чтение HL-блоков

Фасад Kokhanenko\Hlblocks\Facade\HlBlock создаёт запрос по числовому ID или техническому имени HL-блока. Перед использованием подключите ядро Битрикса и модуль.

PHP

use Bitrix\Main\Loader;
use Kokhanenko\Hlblocks\Facade\HlBlock;

if (!Loader::includeModule('kokhanenko.hlblocks')) {
    throw new RuntimeException('Модуль HL-блоков не установлен.');
}

$items = HlBlock::query('KokhanenkoDemoNews')
    ->select(['ID', 'UF_NAME', 'UF_PREVIEW_PICTURE'])
    ->active()
    ->order(['UF_SORT' => 'ASC', 'ID' => 'DESC'])
    ->limit(10)
    ->expand(['UF_PREVIEW_PICTURE'])
    ->get();

Пример предполагает существующий блок и поля, включая UF_ACTIVE и UF_SORT. Этот API читает данные, но не выполняет автоматическую проверку пользовательского доступа. Проверяйте права в вызывающем коде, особенно для закрытых HL и связей.

Методы запроса

Все методы настройки возвращают новый запрос. Базовый объект не изменяется.

Метод	Контракт
`select(array $fields)`	Поля выборки; пустой набор API означает все поля
`filter(array $filter)`	Заменить фильтр
`addFilter(array $filter)`	Добавить условие; сложные группы объединяются верхним AND
`order(array $order)`	Порядок полей и направления `ASC/DESC`
`limit(int $limit)`	Положительное число строк
`offset(int $offset)`	Неотрицательное смещение
`active()`	Добавить условие `UF_ACTIVE=1`; поле обязательно
`expand(array $fields, array $relationSelect = [])`	Раскрыть файловые поля и HL-связи по метаданным
`expandFiles(array $fields)`	Явно раскрыть файловые поля
`expandRelations(array $fields)`	Явно раскрыть HL-связи

Не путайте limit(0) API с LIMIT=0 компонента. API требует положительный лимит; компонент трактует ноль как отсутствие ограничения.

PHP

$base = HlBlock::query('KokhanenkoDemoNews')->active();
$latest = $base->order(['ID' => 'DESC'])->limit(3)->get();
$total = $base->count();

Методы выполнения

Метод	Результат
`get(): array`	Последовательный список строк; пустой результат — `[]`
`first(): ?array`	Первая строка или `null`
`find(int $id): ?array`	Запись по ID с сохранением фильтра и активности; смещение сбрасывается
`count(): int`	Количество по фильтру без загрузки всех строк; не размер окна LIMIT/OFFSET
`result(): HlQueryResult`	`items` и `dependencyHlBlockIds` для управления кешем

find() ищет по ID, а не по символьному коду. Для кода используйте явный фильтр или детальный компонент, который дополнительно обнаруживает дубли UF_UNIC_CODE.

Фильтры

PHP

$query = HlBlock::query('KokhanenkoDemoNews')->filter([
    'LOGIC' => 'AND',
    '=UF_ACTIVE' => 1,
    ['LOGIC' => 'OR', '=ID' => [1, 2], '=UF_UNIC_CODE' => 'company-news'],
]);

Используются массивы условий D7, а не SQL-строки. Неподдерживаемые выражения и некорректные поля отклоняются. Не передавайте произвольный фильтр посетителя напрямую в API; разрешайте только необходимые поля и значения.

У простых плоских фильтров addFilter() объединяет ключи, и более позднее значение одинакового ключа выигрывает. Для независимых условий со сложной логикой используйте явные группы.

Связи и файлы

PHP

$items = HlBlock::query('Partners')
    ->select(['ID', 'UF_NAME', 'UF_CITY', 'UF_LOGO'])
    ->expand(['UF_CITY', 'UF_LOGO'], ['UF_CITY' => ['UF_NAME']])
    ->get();

Здесь Partners, UF_CITY и UF_LOGO — пример собственной схемы. UF_CITY должен быть полем типа hlblock, а UF_LOGO — file.

Исходные ID сохраняются. В UF_CITY_DATA добавляется строка цели, в UF_LOGO_DATA — файловый массив с SRC. Одиночное отсутствующее значение даёт null; множественное — список найденных значений. Чтение связанных записей и файлов пакетное, без отдельного запроса на каждую карточку.

В relationSelect отсутствующий ключ означает все поля цели, [] — только ID; ID добавляется автоматически. Раскрывается один уровень: вложенные связи и файлы связанной строки не загружаются. Инфоблоки через этот механизм не раскрываются.

Ошибки и запись

API может выбрасывать HlBlockNotFoundException, InvalidHlQueryException и UnsupportedExpansionException из пространства Kokhanenko\Hlblocks\Query\Exception. На публичной странице показывайте понятное сообщение, а подробности оставляйте в серверной диагностике.

В Query API нет add/update/delete. Для пользовательской записи применяйте публичный редактор; для серверных сценариев используйте проверенные ORM-контракты Битрикса с собственной проверкой прав и валидацией. Прямые SQL-изменения обходят события обслуживания и сброса кеша.