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

Свой способ записи на курс: как устроен enrol-плагин и когда он нужен

Как устроен enrol-плагин Moodle: класс, таблицы, права, задачи. Три сценария, где нужен свой способ записи на курс: оплата, выгрузка из 1С, договор.

Как устроен enrol-плагин Moodle: класс, таблицы, права, задачи. Три сценария, где нужен свой способ записи на курс: оплата, выгрузка из 1С, договор.

В 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. Задача проходит по экземплярам, получает внешние данные и вызывает запись или отчисление. Три правила, которые я для себя вывела.

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

Проверка перед релизом

  1. Установить плагин на чистый Moodle и пройти путь: добавить способ в курс, записать, отчислить, удалить способ.
  2. Проверить права: отдельно под преподавателем без права настройки.
  3. Убедиться, что при удалении курса и пользователя плагин не оставляет мусора, а провайдер конфиденциальности отдаёт ваши данные.
  4. Запустить плановую задачу дважды подряд: второй запуск не должен ничего менять.
  5. Прогнать код через проверку стандартов и написать хотя бы один тест на запись и отчисление.

Типичные ошибки в enrol-плагинах

ОшибкаПоследствиеКак избежать
Роль назначена прямым вызовом, а не при записиПри отчислении роль остаётся, человек видит курс без записиВсегда передавать роль в enrol_user
Отчисление по ошибке внешнего источникаМассовая потеря доступа из-за сбоя чужого сервисаНе менять ничего, если ответ не получен или пуст
Нет проверки can_add_instanceСпособ добавляют в курсы, где он не нуженПроверять право и условия курса
Своя таблица без привязки к экземпляруПосле удаления способа остаются осиротевшие строкиЧистить данные при удалении экземпляра

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

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

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

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