Раньше каждый нестандартный отчёт в 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 и таблицы вы получаете даром.
Права
У конструктора собственные права: просматривать отчёты, редактировать их, управлять расписанием. Для источника этого недостаточно, потому что отчёт показывает данные, а данные могут быть ограничены. Если руководитель филиала не должен видеть чужой филиал, закладывайте ограничение в источник, а не надеясь на то, что автор отчёта добавит нужное условие. Проверьте это под ролью, у которой права на отчёты есть, а прав на данные нет.
Что проверить перед релизом
- Источник виден в списке при создании отчёта, а колонки сгруппированы по сущностям с понятными названиями.
- Фильтры работают вместе с постраничностью и сортировкой.
- Выгрузка в CSV и ODS отдаёт то, что видно на экране, включая кириллицу.
- Расписание отчёта по почте уходит и содержит данные, доступные адресату, а не автору.
- Параметры в SQL идут через плейсхолдеры, а не склеиваются в строку.
- Запрос укладывается в разумное время на данных реального размера, а не на тестовой выборке.
Расписание и рассылка отчётов
У пользовательских отчётов Report Builder есть расписания: отчёт формируется по графику и уходит по почте выбранным получателям в нужном формате. Для учебного центра это снимает типичную рутину, когда методист каждый понедельник выгружает сводку и пересылает руководству. Два замечания из практики. Письмо уходит с данными, которые видит получатель, а не автор отчёта, поэтому право на просмотр данных нужно проверять у каждого адресата. И расписания выполняются плановой задачей Moodle: если cron на сервере настроен небрежно, письма придут не вовремя или не придут вовсе. Работу плановых задач я проверяю в числе первых мер на странице технической поддержки.
Типичные ошибки
| Симптом | Причина | Решение |
|---|---|---|
| Источник не появляется в списке | Класс лежит не в classes/reportbuilder/datasource или у него неверное пространство имён | Проверить путь и namespace, очистить кэши |
| Колонки сущности не видны в отчёте | Сущность не добавлена в источник или не вызван метод подключения всех колонок | Добавить сущность и подключить её колонки |
| Строки в отчёте дублируются | Соединение даёт несколько записей на одну основную строку | Уточнить условие соединения, использовать LEFT JOIN к уникальной выборке |
| Ошибка SQL при добавлении фильтра | Псевдонимы таблиц повторяются в разных сущностях | Получать псевдонимы из сущности, а не писать вручную |
| Отчёт медленный на большой базе | Соединения по полям без индекса | Добавить индексы в install.xml и проверить план запроса |
| Видны данные чужого подразделения | Ограничение не заложено в источник | Добавить условие в источник, привязанное к текущему пользователю |
Дублирование строк самая неприятная из этих ошибок: итоговые числа в отчёте оказываются завышены, и это замечают после того, как отчёт ушёл руководству. Проверяйте суммы на небольшом срезе, в котором число строк известно заранее.
Случай из практики: сводки для руководителей
Для отчёта руководителям по обучению слушателей исходная задача звучала как «Excel с такими-то столбцами». Столбцы совпадали с тем, что уже умеет выводить Report Builder по пользователям, курсам и записям, не хватало только данных из своей таблицы плагина. Если бы заказчик просил именно этот файл, достаточно было бы сущности и источника. Но данные для сводки заказчик хотел брать из других мест, и поэтому такой отчёт я оформила отдельным плагином с выгрузкой в Excel и PDF: он нужен был по строго заданному образцу. Конструктор хорош там, где состав столбцов меняется, а жёсткие формы документов проще собрать отдельным кодом.
Если у вас накопилось несколько однотипных выгрузок, которые методисты просят изменить каждый месяц, их можно заменить одним источником. Опишите, какие столбцы вам нужны и откуда они берутся: по описанию видно, хватит ли штатных сущностей. Для постановки задачи пригодится страница про разработку отчёта под регламент.
Опишите задачу — расскажу, как решить её конкретно в вашем случае. Свяжитесь — разберём вместе.