Плагин, написанный под 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.0 | Bootstrap 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.
Порядок действий перед обновлением рабочей СДО
- Составить список сторонних плагинов и посмотреть в каталоге, какие из них заявляют поддержку нужной версии.
- Поднять копию рабочей СДО на тестовом стенде с целевой версией.
- Для каждого проблемного плагина решить: обновить, заменить или доработать.
- Прогнать тесты и основные сценарии пользователей.
- Только после этого обновлять рабочую систему.
Что делать со сторонними плагинами, которые не обновляются
Самый неприятный случай — сторонний плагин, автор которого перестал его выпускать. Варианты по возрастанию трудозатрат:
- Посмотреть форк. Часто кто-то уже выпустил совместимую версию, и ссылка есть в обсуждении плагина.
- Заменить плагин штатной возможностью или другим плагином. Нередко функция уже встроена в ядро новых версий. Но замена означает перенос данных, и сначала нужен тест на копии.
- Доработать плагин самим. Если несовместимостей немного, это дешевле замены, но вы становитесь его сопровождающим. Правки лучше хранить в отдельной ветке 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. Если ваш плагин сломался после смены версии и нужна быстрая диагностика, пишите на срочную помощь программиста.
Опишите задачу — расскажу, как решить её конкретно в вашем случае. Свяжитесь — разберём вместе.