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

Совместимость плагина с Moodle 4.1–5.x: что ломается и как держать одну ветку

Что ломается в плагинах Moodle при обновлении с 4.1 до 5.x: таблица версий, диагностика, одна ветка кода и автоматическая проверка на нескольких версиях.

Что ломается в плагинах Moodle при обновлении с 4.1 до 5.x: таблица версий, диагностика, одна ветка кода и автоматическая проверка на нескольких версиях.

Плагин, написанный под Moodle 4.1, часто работает на 4.5 без правок, а на 5.x вдруг показывает белый экран. Единого списка «что ломается» нет, но причины повторяются, и у каждой есть привычный способ проверки. Я сопровождаю плагины на версиях от 3.10 до 5.x, и ниже — то, с чем сталкивалась на практике, и как держать одну ветку кода вместо трёх.

Откуда берутся поломки

Почти все проблемы совместимости относятся к четырём группам: изменилась версия PHP, ядро убрало устаревший API, переработан интерфейс или шаблоны, изменились зависимости (редактор, формат курса, банк вопросов). Moodle заранее предупреждает об устаревании: функция сначала помечается как deprecated и в режиме разработчика выводит предупреждение, а через несколько релизов удаляется. Поэтому первый и самый дешёвый способ — просто запустить плагин на новой версии с включённым режимом разработчика и прочитать предупреждения (как это делать, описано в статье про отладку Moodle).

Что менялось между версиями

Таблица составлена по моему опыту и по заметкам к релизам; для своей задачи сверяйтесь с документацией разработчика и списком изменений нужного релиза.

ВерсияЧто изменилосьЧем это грозит плагину
4.0новая навигация (вторичное меню), перестроен банк вопросов в виде отдельных подплагиновпункты меню, добавленные старым способом, оказываются не там; плагины, работающие с вопросами, требуют правок
4.3минимальная версия PHP повышена; TinyMCE становится редактором по умолчаниюкод на старом PHP не стартует; плагины, зависящие от Atto, перестают расширять редактор
4.4появился Hooks API, старые функции-обратные вызовы начинают помечаться устаревшими; минимальная версия PHP снова вышепредупреждения deprecated; в будущих релизах обратные вызовы исчезнут
4.5 (LTS)долгосрочная ветка с поддержкой безопасностибазовая цель для большинства рабочих СДО
5.0Bootstrap 5 в теме Boost, очередное повышение PHP, чистка устаревшего APIразметка с data-toggle и другими атрибутами Bootstrap 4 перестаёт работать; правки шаблонов и JavaScript
5.1изменена структура каталогов ядра: веб-доступная часть вынесена в подкаталогскрипты установки и обновления, которые рассчитывают на старые пути; прямые подключения файлов ядра

Требования к PHP по версиям Moodle проверяйте на странице релизов — они менялись на нескольких рубежах и важнее любой таблицы в статье.

Диагностика после обновления

СимптомВероятная причинаПроверка
Белый экран или ошибка 500 на странице плагинафатальная ошибка PHP, обычно из-за удалённой функции или классажурнал ошибок веб-сервера и PHP
Плагин пропал из менюизменился способ добавления пунктов в навигациюсм. статью про Navigation API
Не работает кнопка, окно или вкладкаразметка Bootstrap 4 в теме на Bootstrap 5консоль браузера, поиск data-toggle в шаблонах
Плагин отключён и требует обновленияв version.php не указана новая версия в requires или supportedстраница уведомлений админки
Строки типа [[...]]изменился идентификатор строки или файл языкапроверить файлы языка
Предупреждения deprecated на каждой страницевызов функции, признанной устаревшейпрочитать подсказку в самом сообщении: в нём обычно указана замена

Одна ветка вместо нескольких

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

  • Проверять наличие, а не номер версии. Если новая функция есть в классе, используйте её, иначе вызывайте старую. Для таких ветвлений достаточно проверки существования класса или метода.
  • Выносить различия в один класс. Все места, где поведение зависит от версии, собраны в единственном «адаптере». Остальной код вызывает адаптер и версий не знает.
  • Явно указывать диапазон. В version.php заданы минимальная версия (requires) и список поддерживаемых релизов; всё остальное считается неподдерживаемым и не обещается.
// classes/compat.php — единственное место, где код знает о версиях
namespace local_myplugin;

class compat {
    public static function has_hooks(): bool {
        return class_exists(\core\hook\manager::class);
    }
}

Если различия разрастаются (например, нужно поддерживать 3.10 и 5.x одновременно), одна ветка перестаёт быть честной, и тогда я завожу отдельные ветки. Такое бывает на старых СДО, которые нельзя обновить сразу.

Автоматическая проверка на нескольких версиях

Чтобы не узнавать о поломках от пользователей, плагин должен прогоняться на каждой поддерживаемой версии Moodle. Это делает moodle-plugin-ci в GitHub Actions: матрица из версий Moodle, PHP и баз данных, запуск проверок кода и тестов (о проверках, о тестах). Локально то же самое воспроизводится в moodle-docker: достаточно переключить версию кода и PHP.

Порядок действий перед обновлением рабочей СДО

  1. Составить список сторонних плагинов и посмотреть в каталоге, какие из них заявляют поддержку нужной версии.
  2. Поднять копию рабочей СДО на тестовом стенде с целевой версией.
  3. Для каждого проблемного плагина решить: обновить, заменить или доработать.
  4. Прогнать тесты и основные сценарии пользователей.
  5. Только после этого обновлять рабочую систему.

Что делать со сторонними плагинами, которые не обновляются

Самый неприятный случай — сторонний плагин, автор которого перестал его выпускать. Варианты по возрастанию трудозатрат:

  • Посмотреть форк. Часто кто-то уже выпустил совместимую версию, и ссылка есть в обсуждении плагина.
  • Заменить плагин штатной возможностью или другим плагином. Нередко функция уже встроена в ядро новых версий. Но замена означает перенос данных, и сначала нужен тест на копии.
  • Доработать плагин самим. Если несовместимостей немного, это дешевле замены, но вы становитесь его сопровождающим. Правки лучше хранить в отдельной ветке git, чтобы они не терялись при следующем обновлении.
  • Отказаться от плагина. Иногда это лучший вариант: функцией пользовались двое, а поддерживать её дорого.

Я заношу такие решения в таблицу по каждому плагину: что делает, кто его использует, что выбрано. Этот список потом становится основой плана обновления, и заказчик видит, на что уходит время.

Шаблоны и стили при переходе на Bootstrap 5

Если плагин выводит собственную разметку или использует элементы Bootstrap, при переходе на Moodle 5.x прежде всего надо пройтись по шаблонам Mustache и по JavaScript. Атрибуты, которые управляли выпадающими списками, модальными окнами и подсказками, получили новый префикс, а часть утилитарных классов переименована. Симптомы неочевидны: страница открывается, но кнопка «ничего не делает». Поэтому после обновления я всегда открываю консоль браузера и прохожу все экраны плагина под ролями преподавателя и студента, а не только под администратором. Подробнее про шаблоны — в статье про Output API и Mustache.

Как заявлять поддерживаемые версии честно

В version.php нужно указывать не те версии, на которых плагин «скорее всего заведётся», а те, на которых он проверен. Поле requires отвечает за минимальную версию ядра, поле supported — за диапазон веток, которые вы готовы поддерживать. Если плагин не прошёл проверку на новой ветке, не расширяйте диапазон заранее: Moodle предупредит администратора о несовместимости, и это лучше, чем неожиданное падение на рабочем сайте. После проверки диапазон расширяют отдельной версией плагина с понятной записью в истории изменений.

Пример: пункт меню плагина после перехода на Moodle 4

Один из самых частых случаев в моей практике — ссылка плагина в навигации курса, которая после обновления оказалась не там или пропала. В Moodle 4.0 интерфейс получил вторичную навигацию: вкладки курса («Курс», «Участники», «Оценки», «Отчёты», «Ещё») строятся из тех же узлов, но порядок и вложенность определяются новой логикой. Плагин, который добавлял пункт старой функцией расширения навигации курса, продолжает вызываться, но узел может попасть в раздел «Ещё» или другое место. Диагностика проста: откройте страницу курса под ролью, для которой ссылка предназначена, проверьте разделы «Ещё» и «Отчёты», затем сверьтесь с описанием Navigation API. Если место неудачное, узел явно помещают в нужный родительский узел при добавлении. Подробности вынесены в отдельную статью про навигацию (Navigation API), здесь важно другое: такие различия не видны без проверки глазами, и поэтому прохождение интерфейса под разными ролями входит у меня в обязательный список перед выпуском.

Именно так проходило обновление рабочей СДО центра ДПО с 4.3 до 5.2 через 4.5: каждый сторонний плагин проверялся отдельно, несовместимые заменялись, а редактор Atto заменялся на TinyMCE. Подробности процесса — на странице обновления Moodle. Если ваш плагин сломался после смены версии и нужна быстрая диагностика, пишите на срочную помощь программиста.

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

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