Перейти к содержимому
M
Все статьи
Разработка 8 мин чтения

Report Builder в Moodle 4.x: свои источники данных и отчёты без SQL-костылей

Как устроен Report Builder Moodle 4.x: сущности, источники данных, системные отчёты. Как добавить свой источник и дать преподавателям собирать отчёты без SQL.

Как устроен Report Builder Moodle 4.x: сущности, источники данных, системные отчёты. Как добавить свой источник и дать преподавателям собирать отчёты без SQL.

Раньше каждый нестандартный отчёт в Moodle означал отдельный PHP-файл с SQL-запросом, таблицей и своей проверкой прав. Начиная с версии 4.x есть штатный конструктор Report Builder, и теперь разумнее писать не отчёты, а источники данных: набор сущностей, из которых методисты сами собирают нужные таблицы. Ниже разбираю, как конструктор устроен и как к нему добавить своё. Для готовых отчётов под регламент учебного центра есть страница отчёты ДПО в Moodle, а здесь устройство.

Какие бывают отчёты в Report Builder

Это путает больше всего, поэтому начну с различий. В конструкторе есть три вещи с похожими названиями.

ВидКто собираетГде живётКогда выбирать
Пользовательский отчётАдминистратор или методист в интерфейсеВ базе Moodle, как данныеНужны разные выборки, состав меняется
Источник данныхРазработчикВ коде плагинаНужны новые поля для пользовательских отчётов
Системный отчётРазработчикВ коде плагинаФиксированная таблица на странице плагина

Когда заказчик говорит «нужен отчёт», сначала выясните, нужен ли ему один отчёт или возможность собирать их. В первом случае достаточно системного отчёта или готового пользовательского. Во втором нужен источник данных, и после его написания разработчик больше не нужен.

Сущности: из чего собирается источник

В основе конструктора лежит понятие сущности. Сущность описывает одну таблицу или группу связанных данных и отвечает на три вопроса: какие у неё есть колонки, по каким полям можно фильтровать и какие условия можно задать. В ядре уже есть готовые сущности для пользователей, курсов и категорий курсов, вы подключаете их, а не пишете заново. Полный список находится в каталоге сущностей репозитория github.com/moodle/moodle.

Своя сущность нужна для собственной таблицы плагина. Например, у зачётной книжки есть таблица с записями ведомости, у кабинета слушателя есть таблица документов. Сущность описывает их колонки один раз, и дальше эти колонки доступны в любом отчёте.

Часть сущностиЧто задаёт
Псевдонимы таблицКакие таблицы использует сущность и как они называются в запросе
Название сущностиКак её показывать в списке колонок
КолонкиЧто можно вывести: поля, вычисляемые значения, ссылки
ФильтрыПо чему пользователь отбирает строки отчёта
УсловияОграничения, заданные автором отчёта заранее

Пишем источник данных

Источник данных — класс в каталоге classes/reportbuilder/datasource вашего плагина. Он наследует core_reportbuilder\datasource и в методе initialise задаёт основную таблицу и подключает сущности. Конструктор находит такие классы сам, регистрировать их отдельно не нужно.

namespace local_gradebook\reportbuilder\datasource;

use core_reportbuilder\datasource;
use core_reportbuilder\local\entities\user;
use local_gradebook\reportbuilder\local\entities\record;

class records extends datasource {

    public static function get_name(): string {
        return get_string('datasource_records', 'local_gradebook');
    }

    protected function initialise(): void {
        $recordentity = new record();
        $recordalias = $recordentity->get_table_alias('local_gradebook_rec');
        $this->set_main_table('local_gradebook_rec', $recordalias);
        $this->add_entity($recordentity);

        $userentity = new user();
        $useralias = $userentity->get_table_alias('user');
        $this->add_entity($userentity->add_join(
            "JOIN {user} {$useralias} ON {$useralias}.id = {$recordalias}.userid"
        ));

        $this->add_all_from_entities();
    }

    public function get_default_columns(): array {
        return ['user:fullname', 'record:subject', 'record:grade'];
    }

    public function get_default_filters(): array { return ['record:subject']; }
    public function get_default_conditions(): array { return []; }
}

Таблица плагина называется здесь для примера, подставьте свою. Главное в коде: основная таблица, связанные сущности с описанием соединения и вызов, который выкладывает все колонки, фильтры и условия сущностей в интерфейс. Идентификаторы вида user:fullname строятся из имени сущности и колонки; по ним вы указываете, что показывать в новом отчёте по умолчанию.

Названия методов и пространств имён проверяйте по документации конструктора на moodledev.io: в 4.x между выпусками что-то переименовывали, а в 5.x возможны новые обязанности у сущности. Сверка занимает десять минут, ошибка стоит часа.

Колонка сущности

Колонки описываются объектами. Для каждой указывают название, тип данных, поле и, при необходимости, функцию форматирования значения.

$columns[] = (new column(
    'grade',
    new lang_string('grade', 'local_gradebook'),
    $this->get_entity_name()
))
    ->add_joins($this->get_joins())
    ->set_type(column::TYPE_FLOAT)
    ->add_field("{$alias}.grade")
    ->set_is_sortable(true);

Тип колонки определяет форматирование и сортировку: число сортируется как число, а не как строка. Если значение нужно показывать иначе, чем оно хранится, например код статуса как слово, добавляют функцию форматирования. Не складывайте текст статуса в SQL через длинные CASE: он тогда не переводится на другие языки.

Системный отчёт для страницы плагина

Если нужна фиксированная таблица на странице плагина, например список документов слушателей для методиста, пишется системный отчёт. Он наследует core_reportbuilder\system_report, в initialise задаёт основную таблицу, подключает колонки и фильтры, а метод проверки доступа решает, кому его вообще можно показать. На странице отчёт встраивается вызовом, который создаёт его по классу и параметрам и выводит. Фильтры, постраничность и выгрузку в CSV и таблицы вы получаете даром.

Права

У конструктора собственные права: просматривать отчёты, редактировать их, управлять расписанием. Для источника этого недостаточно, потому что отчёт показывает данные, а данные могут быть ограничены. Если руководитель филиала не должен видеть чужой филиал, закладывайте ограничение в источник, а не надеясь на то, что автор отчёта добавит нужное условие. Проверьте это под ролью, у которой права на отчёты есть, а прав на данные нет.

Что проверить перед релизом

  1. Источник виден в списке при создании отчёта, а колонки сгруппированы по сущностям с понятными названиями.
  2. Фильтры работают вместе с постраничностью и сортировкой.
  3. Выгрузка в CSV и ODS отдаёт то, что видно на экране, включая кириллицу.
  4. Расписание отчёта по почте уходит и содержит данные, доступные адресату, а не автору.
  5. Параметры в SQL идут через плейсхолдеры, а не склеиваются в строку.
  6. Запрос укладывается в разумное время на данных реального размера, а не на тестовой выборке.

Расписание и рассылка отчётов

У пользовательских отчётов Report Builder есть расписания: отчёт формируется по графику и уходит по почте выбранным получателям в нужном формате. Для учебного центра это снимает типичную рутину, когда методист каждый понедельник выгружает сводку и пересылает руководству. Два замечания из практики. Письмо уходит с данными, которые видит получатель, а не автор отчёта, поэтому право на просмотр данных нужно проверять у каждого адресата. И расписания выполняются плановой задачей Moodle: если cron на сервере настроен небрежно, письма придут не вовремя или не придут вовсе. Работу плановых задач я проверяю в числе первых мер на странице технической поддержки.

Типичные ошибки

СимптомПричинаРешение
Источник не появляется в спискеКласс лежит не в classes/reportbuilder/datasource или у него неверное пространство имёнПроверить путь и namespace, очистить кэши
Колонки сущности не видны в отчётеСущность не добавлена в источник или не вызван метод подключения всех колонокДобавить сущность и подключить её колонки
Строки в отчёте дублируютсяСоединение даёт несколько записей на одну основную строкуУточнить условие соединения, использовать LEFT JOIN к уникальной выборке
Ошибка SQL при добавлении фильтраПсевдонимы таблиц повторяются в разных сущностяхПолучать псевдонимы из сущности, а не писать вручную
Отчёт медленный на большой базеСоединения по полям без индексаДобавить индексы в install.xml и проверить план запроса
Видны данные чужого подразделенияОграничение не заложено в источникДобавить условие в источник, привязанное к текущему пользователю

Дублирование строк самая неприятная из этих ошибок: итоговые числа в отчёте оказываются завышены, и это замечают после того, как отчёт ушёл руководству. Проверяйте суммы на небольшом срезе, в котором число строк известно заранее.

Случай из практики: сводки для руководителей

Для отчёта руководителям по обучению слушателей исходная задача звучала как «Excel с такими-то столбцами». Столбцы совпадали с тем, что уже умеет выводить Report Builder по пользователям, курсам и записям, не хватало только данных из своей таблицы плагина. Если бы заказчик просил именно этот файл, достаточно было бы сущности и источника. Но данные для сводки заказчик хотел брать из других мест, и поэтому такой отчёт я оформила отдельным плагином с выгрузкой в Excel и PDF: он нужен был по строго заданному образцу. Конструктор хорош там, где состав столбцов меняется, а жёсткие формы документов проще собрать отдельным кодом.

Если у вас накопилось несколько однотипных выгрузок, которые методисты просят изменить каждый месяц, их можно заменить одним источником. Опишите, какие столбцы вам нужны и откуда они берутся: по описанию видно, хватит ли штатных сущностей. Для постановки задачи пригодится страница про разработку отчёта под регламент.

Нужна помощь с Moodle?

Опишите задачу — расскажу, как решить её конкретно в вашем случае. Свяжитесь — разберём вместе.