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

Как устроен плагин Moodle: структура файлов и зачем нужен каждый

Структура плагина Moodle: version.php, lang, db, classes, templates и другие файлы. Что обязательно, что по необходимости и минимальный пример с нуля.

Структура плагина Moodle: version.php, lang, db, classes, templates и другие файлы. Что обязательно, что по необходимости и минимальный пример с нуля.

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

Имя компонента и место на диске

У каждого плагина есть имя компонента, его называют frankenstyle: тип плагина, подчёркивание и короткое имя латиницей. Например local_gradebook или mod_quiz. Это имя встречается везде: в названии таблиц (local_gradebook_entry), в именах прав (local/gradebook:view), в пространстве имён PHP, в ключе настроек и в вызовах get_string().

Тип определяет, где лежит папка. Для local всё просто: local/имя. Для остальных типов путь свой, и его нельзя придумывать: блоки лежат в blocks/ во множественном числе, способы записи в enrol/, способы входа в auth/, административные инструменты в admin/tool/, форматы курса в course/format/. Полный перечень типов и путей есть в документации на moodledev.io. О том, какой тип выбрать под задачу, я написала отдельно в статье про типы плагинов.

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

В Moodle 5.1 исходный код ядра переехал в подкаталог public, и плагины теперь лежат внутри него. Для разработчика это значит одно: путь в документации и в вашем деплое нужно сверять с версией. Структура внутри самого плагина не меняется.

Что лежит внутри: карта файлов

Файл или папкаНазначениеОбязательность
version.phpИмя компонента, номер версии, требуемая версия Moodle, зрелость, зависимостиОбязателен
lang/en/компонент.phpАнглийские строки интерфейса, включая pluginnameОбязателен
db/install.xmlОписание таблиц, которые создаются при первой установкеЕсли нужны таблицы
db/upgrade.phpШаги изменения схемы и данных при повышении версииЕсли схема менялась
db/access.phpПрава доступа (capabilities) и роли, которым они выдаются по умолчаниюЕсли есть права
db/events.phpПодписка на события ядраЕсли нужны наблюдатели
db/tasks.phpРасписание плановых задачЕсли нужен cron
db/services.phpОписание функций веб-сервисаЕсли есть внешний API
classes/Классы с автозагрузкой: логика, формы, провайдеры, задачиПочти всегда
classes/privacy/provider.phpОписание персональных данных плагинаДа, если плагин хранит данные пользователей
templates/Шаблоны MustacheЕсли есть вывод
amd/src/Исходники JavaScript-модулейЕсли есть JS
settings.phpСтраница настроек в администрированииЕсли есть настройки
lib.phpФункции-обратные вызовы с жёстким именемПо необходимости
index.php и другие страницыТочки входа по URLЕсли есть своя страница
tests/PHPUnit и BehatРекомендуется

Эта таблица не значит, что нужно создавать всё сразу. Хороший плагин содержит ровно те файлы, которые нужны задаче. Пустой events.php без подписок только мешает читать код.

version.php: паспорт плагина

Это единственный файл, по которому Moodle определяет, что папка является плагином, и решает, нужно ли что-то устанавливать или обновлять. Сравнивается номер version в файле с номером, сохранённым в базе. Если в файле больше, администратору покажут экран обновления.

<?php
defined('MOODLE_INTERNAL') || die();

$plugin->component = 'local_hello';
$plugin->version   = 2026110100;
$plugin->requires  = 2024100700;
$plugin->maturity  = MATURITY_STABLE;
$plugin->release   = '1.0.0';

Номер версии записывают как дату и два знака порядкового номера в течение дня: ГГГГММДДНН. Он должен только расти. Уменьшить его нельзя: Moodle откажется работать, пока вы не вернёте большее значение или не восстановите базу. requires задаёт минимальную сборку ядра. Правильное значение берут из version.php самого Moodle, а не из памяти. Строка component должна совпадать с именем папки и типом, иначе установка остановится с ошибкой.

Кроме этого, есть dependencies для зависимостей от других плагинов и supported для диапазона поддерживаемых веток. Их значения и точная семантика описаны на moodledev.io, я не буду пересказывать их по памяти.

Языковой файл

Без строки pluginname плагин в списке выглядит как сырой ключ. Файл лежит в lang/en/local_hello.php, а имя файла равно имени компонента (у mod-плагинов без префикса типа, это одно из немногих исключений).

<?php
defined('MOODLE_INTERNAL') || die();

$string['pluginname'] = 'Hello';
$string['privacy:metadata'] = 'The Hello plugin does not store personal data.';

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

Папка db: всё, что Moodle читает при установке и обновлении

Файлы из db/ Moodle разбирает не на каждый запрос. Их читают при установке, обновлении и очистке кэшей, а результат складывает в таблицы и кэш. Отсюда типичная жалоба: «я добавила право в access.php, а в системе его нет». Пока вы не увеличили version и не прошли обновление, ядро о правке не знает. Это же относится к подпискам на события, расписанию задач и описанию веб-сервисов.

Что поменялиЧто нужно сделать
db/access.php, db/events.php, db/tasks.php, db/services.phpУвеличить version и пройти обновление
db/install.xml у уже установленного плагинаДописать шаг в db/upgrade.php, одной правки install.xml мало
Строки в lang/enОчистить кэш строк, версию поднимать не нужно
Шаблоны в templates/Очистить кэш шаблонов или включить режим разработки темы
JavaScript в amd/srcПересобрать amd/build через Grunt и сбросить кэш JS

Как устроены таблицы и обновления схемы, я разобрала в статье про install.xml и upgrade.php, а права доступа в статье про access.php и capabilities.

classes: основная логика

Современный код Moodle живёт в классах. Автозагрузка работает по простому правилу: класс local_hello\greeting ищется в local/hello/classes/greeting.php, а local_hello\output\page в classes/output/page.php. Подключать такие файлы через require_once не нужно, и если вы это делаете, скорее всего, пространство имён или путь неверны.

<?php
namespace local_hello;

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

class greeting {
    public static function for_user(\stdClass $user): string {
        return get_string('hello', 'local_hello', fullname($user));
    }
}

Часть подпапок имеет особый смысл. В classes/task лежат плановые задачи, в classes/privacy провайдер персональных данных, в classes/external функции веб-сервиса, в classes/event свои события, в classes/output классы вывода. Ядро находит их по именам, поэтому переименовывать их по вкусу нельзя.

lib.php: нужен ли он ещё

Раньше всё расширение ядра шло через функции в lib.php с жёсткими именами вида local_hello_extend_navigation(). Сейчас ядро постепенно переводит такие точки расширения на классы и Hooks API, а lib.php остаётся там, где вызов по имени ещё поддерживается. У mod-плагинов, например, файл по-прежнему обязателен: через него задаются возможности модуля и его добавление в курс. Если новая точка расширения в документации описана классом, берите класс. Файл lib.php подгружается ядром не всегда, поэтому всё тяжёлое выносите в classes/, а в lib.php оставляйте тонкие обёртки.

Минимальный рабочий пример

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

  • local/hello/version.php с описанием выше;
  • local/hello/lang/en/local_hello.php со строкой pluginname;
  • local/hello/classes/greeting.php с классом из примера.

Откройте «Администрирование → Уведомления». Moodle покажет установку нового плагина. После неё плагин появится в списке «Обзор плагинов». Класс вы можете вызвать из любого скрипта: автозагрузка найдёт его. Страницу в админке, настройки и права добавляйте следующими шагами, они разобраны в руководстве про local-плагин с нуля.

Как Moodle находит и устанавливает плагин

При открытии страницы уведомлений ядро обходит каталоги всех типов плагинов, читает в каждой папке version.php и сравнивает версию с записью в таблице установленных компонентов. Новая папка считается новым плагином, и ядро выполняет db/install.xml, затем db/install.php, если он есть, и записывает версию. Папка с более высокой версией запускает db/upgrade.php. Папка с версией ниже сохранённой останавливает систему: Moodle не умеет откатывать код. Поэтому, если вы откатываете плагин, откатывать нужно и базу, иначе на сайте останется схема, которой код не ждёт.

Если плагин зависит от другого, это указывают в $plugin->dependencies, и ядро откажется ставить его, пока зависимость не будет удовлетворена. Именно поэтому при обновлении СДО на новую ветку я начинаю с проверки каждого стороннего плагина на совместимость: один устаревший version.php блокирует весь процесс. Как это выглядело на обновлении рабочей СДО с 4.3 до 5.2, я описывала на странице обновления Moodle.

Как выкладывать плагин на сервер

Практика, которая избавляет от половины странных проблем: плагин хранится в своём git-репозитории, корнем репозитория служит сама папка плагина (version.php лежит в корне репозитория, а не в подкаталоге), на сервер код попадает через git pull или архив из репозитория. Ручное копирование по FTP приводит к тому, что часть файлов остаётся от старой версии, а часть новая.

  • Владелец файлов должен позволять веб-серверу читать каталог, а писать в каталог плагина ему не нужно: разрешение записи в код открывает путь для атаки.
  • Архивы, собранные на macOS, часто содержат служебные файлы с именами вида ._имя. Они попадают в каталоги classes и templates и могут ломать загрузку. Перед выкладкой удаляйте их или собирайте архив командой, которая их не добавляет.
  • После выкладки очищайте кэши и открывайте страницу уведомлений, даже если версия не менялась: так вы увидите ошибку сразу, а не когда её найдёт пользователь.

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

Типичные ошибки в структуре

СимптомПричина
Плагин не виден на экране уведомленийПапка в неверном месте или нет version.php
Ошибка о несоответствии компонента при установке$plugin->component не совпадает с типом и именем папки
Класс не найденПространство имён не равно компоненту или путь не повторяет имя класса
Права, события, задачи не появилисьНе поднят номер версии
Название плагина показано ключомВ языковом файле нет pluginname или файл назван не по компоненту
Белый экран после копирования файловЛишний пробел или BOM перед <?php, либо права файлов не позволяют веб-серверу читать папку

В рабочих проектах я ставлю такие плагины через git и проверяю структуру кодом ещё до выкладки. Если вы хотите, чтобы плагин делала я, начните со страницы программиста Moodle: там описано, как я уточняю задачу до начала работы.

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

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