В интерфейсе завершение выглядит как галочка рядом с элементом курса и строка «Курс завершён» в отчёте. Под ним сразу три сущности: настройки завершения элемента, состояние пользователя по каждому элементу и критерии завершения курса, которые все это собирают. Разработчику плагина важно понимать границы: что читается и записывается через completion_info, что решает сам модуль, и что делает cron, а что происходит мгновенно.
Уровни: элемент и курс
| Уровень | Где настраивается | Где хранится состояние | Кто считает |
|---|---|---|---|
| Элемент курса (activity) | Настройки модуля, блок «Отслеживание выполнения» | Таблица course_modules_completion | Сам модуль и ядро при действиях пользователя |
| Курс | «Завершение курса» в настройках курса | Таблицы course_completions и course_completion_crit_compl | Критерии и агрегация; обновляется при событиях и по cron |
Функциональность включается сайтом («Администрирование → Дополнительные возможности → Отслеживание выполнения») и курсом. Описание на стороне разработчика — в разделе Activity completion API.
Состояния элемента
Для каждого пользователя и элемента ядро хранит состояние:
COMPLETION_INCOMPLETE— не выполнено;COMPLETION_COMPLETE— выполнено;COMPLETION_COMPLETE_PASS— выполнено, проходной балл достигнут;COMPLETION_COMPLETE_FAIL— выполнено, но балл не проходной.
Условия, по которым элемент считается выполненным, в штатной форме модуля бывают разными: ручная отметка студентом, просмотр, получение оценки, проходной балл и правила конкретного модуля (например, «отправить минимум столько сообщений» в форуме).
Чтение состояния
$course = get_course($courseid);
$modinfo = get_fast_modinfo($course, $userid);
$cm = $modinfo->get_cm($cmid);
$completion = new completion_info($course);
if ($completion->is_enabled($cm)) {
$data = $completion->get_data($cm, false, $userid);
if ($data->completionstate == COMPLETION_COMPLETE
|| $data->completionstate == COMPLETION_COMPLETE_PASS) {
// Элемент выполнен.
}
}
Проверка is_enabled() отсекает элементы, для которых отслеживание не включено. Для вывода на странице в виде привычной галочки пользуйтесь готовыми шаблонами, а не рисуйте свою: тема уже умеет показывать состояние. Для отчётов, где нужно знать завершение у многих пользователей сразу, есть методы, получающие данные пакетом: вызывать get_data() для каждой пары «пользователь × элемент» в цикле дорого.
Изменение состояния
Отметка выполнения выставляется методом update_state():
$completion->update_state($cm, COMPLETION_COMPLETE, $userid);
Но слово «выставляется» обманчиво. Для элемента с автоматическими правилами (оценка, просмотр, пользовательские условия) update_state() не принимает значение вслепую, а сам проверяет правила и приводит состояние в соответствие. Передавать COMPLETION_COMPLETE имеет смысл для ручной отметки или как «подсказку пересчитать». Типичная ошибка новичка — выставить завершение прямым INSERT в course_modules_completion: события не создаются, кэш не сбрасывается, критерии курса о нём не узнают, и в интерфейсе галочка появится не сразу или не появится вовсе.
Если пользователь выполнил действие (отправил ответ, посмотрел страницу), модуль сам вызывает пересчёт. Для просмотра есть отдельный метод set_module_viewed(), который вызывают в скрипте просмотра. Поэтому у собственных модулей важно не забывать про вызов в view.php: без него условие «Просмотреть» не сработает никогда.
Свои условия для модуля
В Moodle 4.0 появилась структура для пользовательских правил элемента: класс custom_completion. Её суть: модуль объявляет правила, а класс по запросу ядра сообщает, выполнено ли правило у пользователя. В supports модуля включается признак наличия правил завершения, в форме настроек появляются поля условий, а в каталоге classes/completion лежит класс.
namespace mod_example\completion;
use core_completion\activity_custom_completion;
class custom_completion extends activity_custom_completion {
public function get_state(string $rule): int {
$this->validate_rule($rule);
$done = $this->is_rule_done($rule); // ваша проверка по данным плагина
return $done ? COMPLETION_COMPLETE : COMPLETION_INCOMPLETE;
}
public static function get_defined_custom_rules(): array {
return ['completionreport'];
}
public function get_custom_rule_descriptions(): array {
return ['completionreport' => get_string('completionreportdesc', 'mod_example')];
}
public function get_sort_order(): array {
return ['completionview', 'completionreport'];
}
}
Метод is_rule_done() здесь условный: это ваша функция, которая сверяется с таблицами модуля. Названия остальных методов фиксированы базовым классом, и список обязательных методов зависит от версии: сверьтесь с классом activity_custom_completion в вашем Moodle. Когда данные, от которых зависит правило, меняются (скажем, преподаватель принял отчёт), модуль должен вызвать пересчёт состояния для пользователя, иначе галочка не обновится до следующего действия.
Для плагинов не-модулей (local, block) собственных правил завершения нет. Пути обхода: вынести логику в простой модуль-элемент курса; использовать события для реакции; применить условия доступности (плагины availability), которые ограничивают доступ к элементам по произвольной логике.
Завершение курса
Критерии курса определены ядром: завершение элементов, дата, длительность записи, оценка за курс, ручное завершение, подтверждение преподавателем. Набор нельзя расширить стороннему плагину, и это следует учитывать при проектировании: нестандартные условия моделируются через элементы курса с собственными правилами. Агрегация критериев настраивается: «все» или «любой».
Часть критериев вычисляется не мгновенно. Условия по дате и длительности проверяются плановой задачей, а при завершении элементов в тот же момент ставится отметка, по которой система пересчитает курс при ближайшей возможности. Поэтому «курс не завершился сразу» не всегда ошибка, и сначала нужно проверить cron.
| Симптом | Причина | Что проверить |
|---|---|---|
| Все элементы выполнены, курс не завершён | Не пересчитан статус, есть иной обязательный критерий | Страница «Завершение курса», задачи cron, отчёт о выполнении |
| Галочка не появляется после действия | В модуле нет вызова обновления состояния | view.php и обработчики действий модуля |
| Элемент не засчитан по оценке | Не достигнут проходной балл или оценка скрыта/ожидает пересчёта | Журнал оценок и настройки проходного балла |
| Завершение сбросилось у студента | Преподаватель сбросил попытку или изменил настройки элемента | Журнал событий, настройки «Заблокировать» |
| Нет события завершения курса | Курс завершён вручную или критерии не заданы | Настройки курса и события по пользователю |
Что хранится в настройках элемента
Условия завершения лежат прямо в записи элемента курса, в таблице course_modules. Поле completion показывает режим: отслеживание выключено, ручная отметка или автоматическое выполнение по условиям. Остальные поля уточняют условия: требование просмотра (completionview), номер оценки, по которой судят о выполнении (completiongradeitemnumber), проходной балл как отдельное условие (completionpassgrade) и ожидаемая дата завершения (completionexpected), которая нужна только для напоминаний и отображения в календаре. Пользовательские правила модуля хранятся в его собственных колонках. Для отчёта, который объясняет, почему элемент не засчитан, придётся прочитать все эти поля вместе с состоянием.
| Что хотим узнать | Откуда читать |
|---|---|
| Включено ли отслеживание для элемента | Поле completion в course_modules и метод is_enabled() |
| Состояние пользователя по элементу | Метод get_data() или таблица course_modules_completion |
| Описание условий для показа студенту | Шаблоны и функции информации о модуле, а не самодельный текст |
| Завершил ли пользователь курс | Объект завершения курса и таблица course_completions |
Сброс и повторное прохождение
Состояние завершения не вечно. Преподаватель может сбросить попытку теста, и состояние пересчитается. Функция «Сброс курса» в настройках удаляет данные пользователей и в том числе отметки завершения. При восстановлении курса из резервной копии с данными пользователей состояние тоже переносится. Это важно для зачётных книжек и отчётов: завершение, на которое вы опираетесь как на факт, может измениться. Поэтому события завершения, как и итоговые оценки, стоит фиксировать в своей таблице на момент наступления, если плагин создаёт документ (сертификат, ведомость), который нельзя менять задним числом.
Ещё одна тонкость: приостановленное или неактивное зачисление. Отчёты по завершению обычно строят по активным участникам, и студент, отчисленный, а затем восстановленный, может появиться в статистике не сразу. При проектировании отчёта заранее решите, кого считать участником курса на отчётную дату, и сделайте это явным условием запроса.
Классы и методы завершения: справка
| Метод или класс | Для чего |
|---|---|
new completion_info($course) | Точка входа для работы с завершением курса |
is_enabled($cm) | Включено ли отслеживание для элемента |
get_data($cm, $wholecourse, $userid) | Состояние завершения элемента у пользователя |
update_state($cm, $state, $userid) | Пересчитать и записать состояние |
set_module_viewed($cm, $userid) | Отметить просмотр элемента |
is_course_complete($userid) | Проверить завершение курса пользователем |
\core_completion\progress | Расчёт процента выполнения для отображения |
\core_completion\activity_custom_completion | Базовый класс пользовательских правил модуля |
Типичные ошибки разработчика
Первая ошибка уже описана: запись в таблицы напрямую. Вторая: в скрипте просмотра модуля нет вызова отметки просмотра, и условие «Просмотреть» не выполняется никогда. Третья: пользовательское правило проверяют по данным, которые ещё не сохранены на момент вызова пересчёта, и состояние отстаёт на одно действие. Четвёртая: отчёт считает «завершено» только по значению COMPLETION_COMPLETE и теряет вариант с проходным баллом. Для проверки полезно завести тестового пользователя и пройти элемент всеми способами, которые допускают настройки: вручную, по просмотру, по оценке, по проходному баллу.
Реакция на завершение
Для действий «после завершения» (сертификат, письмо, отметка в зачётной книжке) подписываются на события: на уровне элемента это \core\event\course_module_completion_updated, на уровне курса — \core\event\course_completed. Наблюдателю достаточно поставить фоновую задачу, а основную работу сделать вне запроса. На той же связке строятся выдача сертификатов и обработка слушателей по окончании обучения. Если нужно собрать такую цепочку под вашу СДО, пишите через страницу разработки плагинов Moodle.
Завершение влияет и на оценки: в курсе с обязательными условиями проходной балл часто определяет, будет ли элемент засчитан. Как журнал хранит такие значения, описано в статье про Grade API.
Опишите задачу — расскажу, как решить её конкретно в вашем случае. Свяжитесь — разберём вместе.