Руководство по использованию метода Result::fetchAll в 1С-Битрикс

При работе с базой данных в 1С-Битрикс часто возникает необходимость получить сразу все результаты запроса и обработать их. Для этого в D7-ядре (пространство имён \Bitrix\Main\DB) предусмотрен метод fetchAll, который позволяет быстро и удобно вернуть все строки выборки в виде ассоциативного массива.

В данной статье мы разберём:

1. Что такое метод fetchAll
2. Каков формат возвращаемых данных
3. Где и как его правильно применять
4. Примеры использования

1. Общее описание метода

Метод объявлен следующим образом:

public function fetchAll(
    \Bitrix\Main\Text\Converter $converter = null
);

• Нестатический метод: чтобы им воспользоваться, необходимо работать с объектом результата запроса.
• Возвращает: ассоциативный массив со всеми строками выборки. Если результат пустой, будет возвращён пустой массив.
• Параметр $converter (опциональный): объект класса \Bitrix\Main\Text\Converter или его наследников, который нужен для конвертации (расшифровки) данных при получении из базы. Обычно используется при необходимости специальной обработки текста (например, декодирование HTML, преобразование кодировок и т. п.). В большинстве случаев можно не указывать этот параметр, если нет особых требований к конвертации.

2. В каком случае стоит применять fetchAll

Метод fetchAll удобен в ситуациях, когда:

1. Нужно получить все записи из результата запроса целиком. Например, при выборке небольшого количества строк (небольшого массива данных).
2. Не требуется построчная итерация с дальнейшей немедленной обработкой. Если нужно прокручивать результаты в цикле, иногда удобнее использовать методы наподобие fetch() или while ($row = $result->fetch()) { ... }.
3. Нужно сформировать общий массив данных, который будет передан на дальнейшую обработку, сериализацию, вывод или работу с ним в шаблоне компонента.

Примечание: Если предполагается очень большая выборка, вызов fetchAll может вызвать повышенную нагрузку на память. В таком случае целесообразно рассмотреть возможность использования построчного извлечения данных или разбить выборку на страницы (пагинацию).

3. Пример использования

Рассмотрим базовый пример запроса, получающего список пользователей из таблицы b_user. Для этого используем класс \Bitrix\Main\UserTable, который работает с таблицей b_user:

<?php

use Bitrix\Main\UserTable;
use Bitrix\Main\Application;

// ...
// Предположим, код располагается в init.php или внутри метода компонента

// Получаем список пользователей
$result = UserTable::getList([
    'select' => ['ID', 'LOGIN', 'NAME', 'LAST_NAME'],
    'filter' => ['ACTIVE' => 'Y'],
    'order'  => ['ID' => 'DESC'],
]);

// Теперь у нас есть объект \Bitrix\Main\DB\Result
// Для получения всех строк воспользуемся fetchAll
$users = $result->fetchAll();

// $users теперь содержит массив:
// [
//   [
//       'ID'        => '...',
//       'LOGIN'     => '...',
//       'NAME'      => '...',
//       'LAST_NAME' => '...'
//   ],
//   [...],
//   ...
// ]

// В случае пустого результата будет возвращён пустой массив []

// Выведем полученный массив для отладки
echo '<pre>';
print_r($users);
echo '</pre>';

В этом примере:

• Мы задали массив параметров выборки (select, filter, order).
• Метод getList вернул объект результата, который мы сохранили в переменную $result.
• Затем вызвали $result->fetchAll(), получив ассоциативный массив.

При необходимости построчно обрабатывать данные (например, если их слишком много) можно было бы использовать while ($row = $result->fetch()), но когда удобно сразу получить весь массив, fetchAll даёт более компактный код.

Пример с параметром $converter

Если нам необходимо применить особую конвертацию данных, то можно передать объект класса, реализующего интерфейс \Bitrix\Main\Text\Converter. Для примера представим, что у нас есть некий HtmlConverter (это лишь условное название) для преобразования HTML-сущностей:

<?php

use Bitrix\Main\DB\Result;
use Bitrix\Main\Text\Converter;

// Допустим, есть класс HtmlConverter, наследник \Bitrix\Main\Text\Converter
$converter = new HtmlConverter();

// Результат запроса
$result = SomeTable::getList([
    'select' => ['ID', 'TITLE', 'DESCRIPTION'],
]);

// Применяем конвертер при получении всех строк
$data = $result->fetchAll($converter);

// Теперь массив $data будет содержать уже сконвертированные строки,
// где HTML-сущности преобразованы, или произведены иные нужные действия,
// зависящие от реализации конвертера.

Чаще всего разработчикам хватает стандартного поведения, поэтому параметр передаётся не так часто.

4. Практические советы по использованию

1. Учитывайте объём данных. Если ожидается, что выборка будет насчитывать несколько тысяч (или десятков тысяч) записей, подумайте о разделении загрузки по частям или построчной обработке.
2. Используйте селективные фильтры. Чем меньше данных вы загружаете, тем эффективнее будет ваш код — и не перегрузит память.
3. Не забывайте об индексах в базе данных и корректных фильтрах, чтобы метод fetchAll обрабатывал результат быстрее.
4. Проверяйте результат перед дальнейшей логикой:

$rows = $result->fetchAll();
if (empty($rows)) {
    // Обработка ситуации, когда записи не найдены
} else {
    // Дальнейшая логика
}

Вывод

Метод fetchAll в 1С-Битрикс (D7) — это удобный способ быстро получить все строки результата SQL-запроса в виде массива для последующей групповой обработки. Основные плюсы — простота и «короткий» код. При необходимости можно задействовать конвертер, чтобы расшифровать данные в особом формате. Однако следует аккуратно применять данный метод с учётом возможного большого объёма данных, чтобы не перегрузить память.

Используйте fetchAll, когда вам нужно собрать список сразу и работать с ним как с целым объектом, например, для вывода списков на одной странице, формирования отчётов, экспорта данных и т. д. При более «тяжёлых» выборках разумнее переходить на построчное чтение данных.

Надеемся, что данное руководство поможет вам быстрее освоить и эффективно применять \Bitrix\Main\DB\Result::fetchAll в ваших проектах на 1С-Битрикс!