Плагин 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: там описано, как я уточняю задачу до начала работы.
Опишите задачу — расскажу, как решить её конкретно в вашем случае. Свяжитесь — разберём вместе.