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

Доработка Moodle без правки ядра: почему core трогать нельзя

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

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

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

Что происходит с правкой ядра при обновлении

Обновление Moodle — это замена файлов дистрибутива на новую версию с последующим запуском скриптов обновления базы. Любые изменения внутри этих файлов не сохраняются. Для администратора это выглядит так: вчера кнопка была на месте, сегодня после обновления её нет, и никто не может объяснить почему.

Есть и вторая проблема. Moodle регулярно выпускает исправления безопасности для поддерживаемых версий. Если файл правили вручную, вы либо не можете наложить исправление, либо накладываете его поверх чужой правки, не зная последствий. О том, как проходит обновление большой системы, я писала в рассказе про переход с Moodle 4.3 на 5.2 через 4.5 LTS на странице обновления Moodle: каждый сторонний плагин проверялся отдельно, а правки ядра при таком переходе становятся главным источником неожиданностей.

Как правки ядра попадают в систему

Сами по себе программисты не стремятся ломать архитектуру. Причины обычно такие:

  • Срочность: нужно «чтобы работало сегодня», а правильное решение займёт больше времени.
  • Незнание: исполнитель не знает, что для этого есть событие или хук.
  • Недокументированность: у Moodle нет точки расширения, которая нужна именно в этом месте, и программист идёт по короткому пути.
  • Привычка: человек пришёл из другой системы, где править исходники — норма.

Первые три причины решаются разговором и временем, четвёртая — требованием в договоре. Я включаю в работу пункт «без изменения файлов дистрибутива»: он прямо ограничивает исполнителя.

Чем заменить правку ядра

В большинстве случаев нужный результат достигается одним из пяти способов. В таблице я собрала их по принципу «что хотим изменить».

ЗадачаПравка ядра (плохо)Решение без правки
Выполнить действие после события: зачислили студента, сдали тестВставить код в функцию зачисленияНаблюдатель событий в собственном плагине (файл db/events.php)
Изменить оформление или шаблонПравить шаблон Mustache или CSS в основной темеДочерняя тема или собственная тема, переопределение шаблонов
Поменять формулировку на экранеПравить языковой файл дистрибутиваЛокальная настройка языка в администрировании
Добавить пункт в меню или страницу в профильДописывать код в навигациюФункции обратного вызова в lib.php плагина или механизм хуков
Изменить праваУбирать проверку в кодеРоли и переопределение прав в системе, собственные права плагина
Обмен данными с внешней системойПравить обработчик входа или базу напрямуюВеб-службы Moodle, задачи cron в плагине
Новая функция или отчётДопись в стандартный модульНовый плагин нужного типа, чаще всего local

Хуки (hooks) появились в системе в версии 4.3 и расширяются в следующих; если вам нужна их конкретная точка, проверяйте список на moodledev.io. Для версий до 4.3 применяют функции обратного вызова и события.

Пример: действие после зачисления

Допустим, при зачислении студента в курс нужно записать его в служебную таблицу. Вместо правки функции зачисления создаётся плагин типа local с наблюдателем.

defined('MOODLE_INTERNAL') || die();

$observers = [
    [
        'eventname' => '\core\event\user_enrolment_created',
        'callback'  => '\local_example\observer::enrolled',
    ],
];

Этот файл лежит в каталоге db вашего плагина. Класс наблюдателя получает событие и делает нужную запись. Так код живёт отдельно от ядра, переживает обновление и отключается удалением плагина. Структуру плагина целиком я разбираю в материалах раздела разработки плагинов.

Когда без изменения поведения ядра всё же не обойтись

Случается, что в Moodle нет точки расширения для вашей задачи. Тогда порядок действий такой:

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

Это крайняя мера, и в моей практике она нужна заметно реже, чем кажется исполнителям, которые к ней привыкли.

Как проверить, правили ли ядро в вашей системе

Для этого нужен чистый дистрибутив той же версии, что установлена у вас. Версию смотрите на странице уведомлений администратора или в файле version.php в корне Moodle. Дальше действуйте на копии:

diff -rq moodle-clean/ moodle-site/ --exclude=config.php --exclude=local --exclude=yourtheme

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

Разбор типичных ошибок

ОшибкаПричинаЧто делать
После обновления пропал функционалПравка лежала в файле ядра, файл заменёнПеренести правку в плагин, восстановить из резервной копии для изучения
Обновление останавливается на странице проверкиСторонний плагин не поддерживает новую версиюОбновить или заменить плагин, не отключая проверку вручную
Правки ядра остались, а автора нетНе было документации и репозиторияСравнить с чистым дистрибутивом, описать каждое различие
Новый программист боится обновлятьНет уверенности, что система повторяется на тестеСоздать тестовую копию и пройти обновление там
Часть кода дублирует стандартный функционалНе знали, что такая настройка естьСверить с документацией на docs.moodle.org и удалить лишнее

Какой тип плагина выбрать для доработки

Когда решено, что правка ядра не нужна, возникает вопрос, в плагин какого типа положить код. От выбора зависит, как он будет вести себя при обновлениях и удалении.

Тип плагинаПодходит дляЗамечание
localОбработчики событий, отдельные страницы, отчёты, интеграции, служебные задачиСамый универсальный вариант для доработок организации
themeОформление, шаблоны страниц, стилиДолжна быть дочерней темой, если вы не создаёте новую
blockБлоки на страницах курса или личной панелиЕсли нужна информационная панель, а не логика
modНовый элемент курса со своим содержимым и оценкамиСложнее по структуре, нужен, когда это именно учебная активность
reportОтчёты внутри курса или системыДля стандартного места в навигации отчётов
auth, enrolСпособ входа и способ зачисленияДля интеграций с внешней системой пользователей

Если вы сомневаетесь, начинайте с local: его проще перенести и переименовать, чем наоборот. Полный перечень типов и требования к структуре приведены на moodledev.io.

Как защитить доработку от следующего обновления

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

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

Что говорить исполнителю, который предлагает «быстро поправить файл»

Услышав такое предложение, спросите три вещи: почему нельзя сделать это в плагине, что случится с правкой при обновлении и где она будет записана. Если ответы расплывчаты, лучше сделать иначе. Часто «быстро поправить файл» занимает час, а правильное решение в плагине — день, и разница в стоимости в начале кажется заметной. Но правка, которую придётся переносить при каждом обновлении, окупает эту разницу уже на первом же переходе версии. Включите в договор обязательство не менять файлы дистрибутива без письменного согласования, это защищает вас от решений, принятых на бегу.

Что сделать до обновления

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

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

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