В Moodle запись пользователя на курс всегда принадлежит какому-то способу записи. Это не просто строка в таблице: за ней стоит экземпляр способа в курсе, правило о том, кто и когда может её изменить, и код, который решает, что делать при отчислении. Когда штатных способов не хватает, пишется enrol-плагин. Ниже разбираю, как он устроен, и три случая из практики, когда он действительно нужен. Если вы решаете, нужна ли вам вообще доработка, начните со страницы про разработку плагинов Moodle.
Что хранит Moodle о записи
Запись описывают две таблицы, и обе пригодятся при отладке. Таблица enrol хранит экземпляры способов: один способ записи, добавленный в один курс, это одна строка. Таблица user_enrolments хранит саму запись человека: ссылку на экземпляр, пользователя, статус, даты начала и окончания. Роль в курсе при этом лежит отдельно, в назначениях ролей контекста курса, и у каждой такой роли указан компонент, который её выдал, например enrol_manual.
Последнее важно. Роль, выданная способом записи, помечена компонентом. Поэтому при отчислении Moodle снимает только свои назначения и не трогает роли, которые преподаватель выдал руками. Если вы назначаете роль в обход API, эта защита перестаёт работать, и потом чистка превращается в ручную работу.
Анатомия плагина
Плагин лежит в каталоге enrol/имя, а его класс называется enrol_имя_plugin и наследует enrol_plugin. Всё остальное по смыслу похоже на любой плагин Moodle, подробнее про общую структуру я писала в статье про разработку плагинов. Для записи на курс нужны такие файлы.
| Файл | Назначение |
|---|---|
version.php | Компонент enrol_имя, версия, требуемая версия Moodle |
lib.php | Класс enrol_имя_plugin: поведение способа записи |
db/access.php | Права: настроить экземпляр, управлять записями, отчислять |
lang/ru/enrol_имя.php и lang/en/... | Строки интерфейса, название плагина, названия прав |
settings.php | Общие настройки способа на уровне сайта (необязательно) |
edit.php, edit_form.php | Форма экземпляра в курсе, если не используется стандартный интерфейс редактирования |
classes/task/ | Плановые задачи: синхронизация, проверка сроков |
classes/privacy/provider.php | Что плагин хранит о людях, для экспорта и удаления данных |
Если вы храните собственные данные о записи, например номер договора или идентификатор платежа, добавляйте свою таблицу в db/install.xml и привязывайте её к экземпляру или к записи. Не кладите чужие данные в поля enrol: там всего несколько универсальных колонок, и они нужны самому ядру.
Методы класса, которые определяют поведение
Базовый класс уже умеет записывать и отчислять. От вас требуется ответить на вопросы, которые Moodle задаёт при показе интерфейса и при операциях. Я перечисляю только то, что реально приходится переопределять.
| Метод | О чём спрашивает Moodle |
|---|---|
can_add_instance($courseid) | Можно ли добавить этот способ в курс. Здесь проверяют право и условия, например что способ ещё не добавлен |
add_instance($course, array $fields) | Создание экземпляра, обычно достаточно вызвать родительский метод |
get_instance_name($instance) | Как показать экземпляр в списке способов курса |
allow_unenrol($instance) | Разрешено ли отчислять вручную. Если запись принадлежит внешней системе, отвечают «нет» |
allow_manage($instance) | Разрешено ли менять сроки и статус записей вручную |
can_delete_instance($instance) | Можно ли убрать способ из курса |
can_hide_show_instance($instance) | Можно ли отключить способ без удаления записей |
use_standard_editing_ui() | Использовать стандартный интерфейс редактирования экземпляра; тогда форма описывается методами edit_instance_form и edit_instance_validation |
Названия методов и их сигнатуры сверяйте с описанием класса в документации разработчика на moodledev.io для вашей версии, они немного менялись от выпуска к выпуску. Самый частый источник ошибок здесь не в логике, а в том, что метод есть в старой версии и по-другому называется в новой.
Запись и отчисление через API
Сама запись делается методом enrol_user вашего же объекта плагина. Он создаёт строку в user_enrolments, назначает роль с пометкой компонента и посылает событие. Отчисление делает unenrol_user, он снимает роли, чистит данные пользователя в курсе, если это настроено, и тоже посылает событие, на которое могут подписаться другие плагины.
$plugin = enrol_get_plugin('contract');
$instance = $DB->get_record('enrol', [
'courseid' => $courseid,
'enrol' => 'contract',
'status' => ENROL_INSTANCE_ENABLED,
], '*', MUST_EXIST);
$plugin->enrol_user(
$instance,
$userid,
$instance->roleid,
$timestart,
$timeend
);
В примере способ называется contract, роль берётся из настроек экземпляра, а даты приходят из договора. Если даты не нужны, передают нули. Повторный вызов для уже записанного пользователя обновляет запись, а не создаёт дубль, поэтому плановую задачу можно делать идемпотентной: она каждый раз приводит записи в соответствие с внешними данными.
Три сценария, где нужен свой способ
Оплата
Запись после оплаты — самый частый запрос. Платёжный шлюз присылает уведомление, обработчик проверяет подпись и сумму, затем вызывает запись. Тут важно разделить две вещи: платёжный плагин (в моём случае EduKassa) отвечает за приём денег, а способ записи отвечает за доступ. Если смешать их в одном плагине, любое изменение в платежах будет задевать зачисление. Связывать их лучше через события или через небольшой интерфейс, а не прямыми вызовами.
Выгрузка из 1С
Когда студенты приходят из учётной системы колледжа, ручная запись превращается в бесконечную рутину. Для пяти колледжей я загружала студентов из выгрузок 1С:Колледж скриптом, который создаёт пользователей и раскладывает их по когортам. Запись на курсы при этом шла не прямыми зачислениями, а через синхронизацию с когортой: штатный способ записи по когорте сам добавляет и убирает людей, когда состав когорты меняется. Свой enrol-плагин в такой схеме не понадобился. Он нужен, если правило сложнее состава группы, например зачислять только при подтверждённом статусе из внешней системы. Подробнее про обмен данными — на странице интеграции Moodle с 1С.
Договор
В учебном центре дополнительного образования запись на программу идёт по договору: договор заключён, значит человек зачислен на срок обучения, договор расторгнут, значит доступ закрывается. Здесь enrol-плагин выглядит естественно: у экземпляра есть привязка к программе, у записи есть номер договора, а плановая задача сверяет срок и статус. Чем это отличается от штатного способа, который просто выставляет даты? Тем, что закрытие доступа происходит по событию во внешней системе, а не по календарю.
Плановая синхронизация
Если источник истины находится вне Moodle, плагин обычно получает задачу в classes/task/, описанную в db/tasks.php. Задача проходит по экземплярам, получает внешние данные и вызывает запись или отчисление. Три правила, которые я для себя вывела.
- Считать разницу, а не пересоздавать. Задача сравнивает ожидаемое состояние с текущим и меняет только расхождения.
- Не отчислять при ошибке источника. Если внешняя система не ответила, это не повод закрывать доступ всем. Задача должна завершиться с ошибкой и ничего не менять.
- Выбирать между приостановкой и отчислением осознанно. Приостановленная запись сохраняет оценки и историю, отчисление с очисткой данных их удаляет.
Проверка перед релизом
- Установить плагин на чистый Moodle и пройти путь: добавить способ в курс, записать, отчислить, удалить способ.
- Проверить права: отдельно под преподавателем без права настройки.
- Убедиться, что при удалении курса и пользователя плагин не оставляет мусора, а провайдер конфиденциальности отдаёт ваши данные.
- Запустить плановую задачу дважды подряд: второй запуск не должен ничего менять.
- Прогнать код через проверку стандартов и написать хотя бы один тест на запись и отчисление.
Типичные ошибки в enrol-плагинах
| Ошибка | Последствие | Как избежать |
|---|---|---|
| Роль назначена прямым вызовом, а не при записи | При отчислении роль остаётся, человек видит курс без записи | Всегда передавать роль в enrol_user |
| Отчисление по ошибке внешнего источника | Массовая потеря доступа из-за сбоя чужого сервиса | Не менять ничего, если ответ не получен или пуст |
Нет проверки can_add_instance | Способ добавляют в курсы, где он не нужен | Проверять право и условия курса |
| Своя таблица без привязки к экземпляру | После удаления способа остаются осиротевшие строки | Чистить данные при удалении экземпляра |
Последнюю ошибку находят не сразу: удаление способа из курса вызывает метод удаления экземпляра, и если вы не переопределили его, ваши таблицы про это ничего не узнают.
Если у вас уже есть правило зачисления, которое сейчас выполняют руками, опишите его: кто, когда и по какому признаку попадает на курс. Часто выясняется, что хватит штатной синхронизации с когортой, а когда не хватает, из этого описания получается готовое задание. Напишите мне через страницу доработки Moodle.
Опишите задачу — расскажу, как решить её конкретно в вашем случае. Свяжитесь — разберём вместе.