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

Local-плагин Moodle с нуля: от пустой папки до страницы в админке

Пошагово создаём local-плагин Moodle: version.php, строки, право доступа, пункт в администрировании и страница с проверкой прав. Рабочий код для Moodle 4.x и 5.x.

Пошагово создаём local-плагин Moodle: version.php, строки, право доступа, пункт в администрировании и страница с проверкой прав. Рабочий код для Moodle 4.x и 5.x.

Это пошаговое руководство, как собрать работающий local-плагин: от пустой папки до страницы в разделе «Плагины» админки, доступной только тем, у кого есть специальное право. Код проверен по логике Moodle 4.x и 5.x и использует только стабильные функции. По дороге я поясняю, зачем нужна каждая строка, потому что копировать код без понимания в Moodle дорого: ошибка сразу превращается в белый экран. Что вообще лежит в плагине, разобрано в статье про структуру файлов, а когда вам нужна готовая разработка, подойдёт страница разработки плагинов.

Что получится

Плагин local_hello с пятью файлами и ещё одним, необязательным:

  • version.php описывает компонент;
  • lang/en/local_hello.php хранит строки;
  • db/access.php объявляет право local/hello:view;
  • settings.php добавляет пункт в администрирование;
  • index.php содержит саму страницу;
  • classes/greeting.php хранит логику (для порядка выносим её из страницы).

Работать удобнее всего на отдельной тестовой копии Moodle, а не на рабочей СДО. Как поднять такую среду, я описывала в материале про локальную среду в Docker.

Шаг 1. Папка и version.php

Создайте каталог local/hello в корне кода Moodle (в версии 5.1 и новее корнем для плагинов служит подкаталог public). Внутри положите version.php:

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

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

Значение requires подставьте из version.php вашего Moodle, а не копируйте из примера: оно должно быть не больше версии, на которой вы собираетесь запускать плагин. Если поставить больше, установка остановится с сообщением о несовместимости.

Шаг 2. Языковой файл

Создайте lang/en/local_hello.php. Строки в файле принято располагать по алфавиту ключей, этого требует Code Checker.

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

$string['greeting'] = 'Hello, {$a}!';
$string['hello:view'] = 'View the Hello page';
$string['pluginname'] = 'Hello';
$string['privacy:metadata'] = 'The Hello plugin does not store personal data.';

Ключ hello:view это описание права из следующего шага. Если его не добавить, в списке прав вместо названия будет виден технический код. Строка privacy:metadata нужна провайдеру персональных данных. Плагин, который ничего не хранит, объявляет это словами; как реализовать это полноценно, я разбираю в статье про Privacy API.

Шаг 3. Право доступа

Файл db/access.php описывает права плагина. Добавим одно, разрешим его менеджерам:

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

$capabilities = [
    'local/hello:view' => [
        'captype'      => 'read',
        'contextlevel' => CONTEXT_SYSTEM,
        'archetypes'   => [
            'manager' => CAP_ALLOW,
        ],
    ],
];

Имя права строится как тип/имя:действие. Уровень контекста системный, потому что страница относится ко всему сайту. Архетип определяет, каким ролям право выдаётся по умолчанию при установке. Позже администратор может изменить это в настройках ролей. Подробности и ловушки прав в статье про access.php.

Шаг 4. Класс с логикой

Вынесем формирование приветствия в класс. Это пример автозагрузки: файл лежит в classes/greeting.php, класс в пространстве имён local_hello.

<?php
namespace local_hello;

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

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

Так страница остаётся тонкой, а класс можно покрыть тестом без запуска веб-интерфейса.

Шаг 5. Пункт в администрировании

Файл settings.php в корне плагина выполняется при построении дерева администрирования. Добавим внешнюю страницу в раздел «Плагины → Локальные плагины»:

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

if ($hassiteconfig) {
    $ADMIN->add('localplugins', new admin_externalpage(
        'local_hello_page',
        get_string('pluginname', 'local_hello'),
        new moodle_url('/local/hello/index.php'),
        'local/hello:view'
    ));
}

Первый аргумент admin_externalpage это уникальный идентификатор страницы в дереве, последний право, при наличии которого пункт виден. Проверка $hassiteconfig оборачивает всё, чтобы обычные пользователи не тратили время на построение дерева. Страницу с формой настроек (а не внешнюю страницу) добавляют иначе, и об этом отдельная статья про settings.php.

Шаг 6. Сама страница

Файл index.php подключает конфигурацию, проверяет доступ и выводит оформление:

<?php
require_once(__DIR__ . '/../../config.php');
require_once($CFG->libdir . '/adminlib.php');

admin_externalpage_setup('local_hello_page');

$PAGE->set_title(get_string('pluginname', 'local_hello'));

echo $OUTPUT->header();
echo $OUTPUT->heading(get_string('pluginname', 'local_hello'));
echo html_writer::tag('p', \local_hello\greeting::for_user($USER));
echo $OUTPUT->footer();

Функция admin_externalpage_setup() делает сразу несколько вещей: требует вход, проверяет право, указанное для страницы в дереве, задаёт контекст и URL, подставляет заголовок и навигацию администрирования. Поэтому отдельные require_login() и require_capability() в таком скрипте не нужны. Если вы пишете публичную страницу вне админки, вызывайте require_login() сами, а затем require_capability() и задавайте URL, контекст и заголовок через $PAGE.

Шаг 7. Установка и проверка

Войдите администратором и откройте «Администрирование → Уведомления». Moodle обнаружит плагин и предложит обновление базы. После подтверждения в разделе «Плагины → Локальные плагины» появится пункт «Hello». Перейдите по нему и увидите приветствие с вашим именем.

Затем проверьте обратный случай. Создайте пользователя без роли менеджера, зайдите им и откройте адрес /local/hello/index.php напрямую. Должна появиться ошибка об отсутствии права. Если страница открылась, значит проверка прав у вас потеряна, и это важнее любого оформления.

Что пойдёт не так

СимптомПричинаЧто сделать
Пункта нет в менюНе очищены кэши или нет праваОчистить кэши, проверить роль
Право показано как «local/hello:view»Нет строки hello:view в языковом файлеДобавить строку, очистить кэш строк
Белый экран на страницеОпечатка в PHP или неверный путь в config.phpВключить вывод ошибок, смотреть журнал
Менеджер не видит страницуПраво добавили, но версию не повышалиУвеличить version, пройти обновление
Ошибка Class not foundПространство имён не равно компонентуСверить namespace и путь файла

Настройка среды: что включить на тестовом сайте

Для разработки на тестовом сервере добавьте в config.php строки, которые показывают ошибки на экране и дают подробные сообщения. На рабочем сайте их быть не должно.

$CFG->debug = (E_ALL | E_STRICT);
$CFG->debugdisplay = 1;
$CFG->cachejs = false;
$CFG->langstringcache = false;
$CFG->cachetemplates = false;

Последние три строки отключают кэш JavaScript, строк языка и шаблонов, чтобы правки были видны без очистки кэшей. Первые две раскрывают причину белого экрана. Эти параметры можно задать и через интерфейс в разделе отладки, но запись в config.php надёжнее: она работает, даже когда интерфейс не открывается. Отдельная статья о том, что делать с белым экраном, будет в следующей партии серии.

Команды, которые пригодятся в работе

Каждый раз открывать браузер ради очистки кэша или обновления неудобно. В каталоге admin/cli лежат скрипты для этого:

КомандаЧто делает
php admin/cli/purge_caches.phpОчищает все кэши Moodle
php admin/cli/upgrade.php --non-interactiveВыполняет обновление базы и плагинов без вопросов
php admin/cli/maintenance.php --enableВключает режим обслуживания, ключ --disable выключает его
php admin/cli/cron.phpЗапускает cron вручную, полезно при отладке задач

Запускайте их от пользователя, под которым работает веб-сервер, иначе файлы кэша получат неверного владельца и сайт перестанет их читать. Ещё одна тонкость: после обновления из командной строки кэш настроек в памяти веб-процесса (например, APCu) может остаться старым, и очищать его приходится из веб-интерфейса.

Следующая правка: как расти от каркаса

Каркас не должен разрастаться без плана. Я иду в таком порядке. Сначала данные: таблица в db/install.xml. Затем доступ: права в db/access.php и проверки на странице. Затем ввод: форма для создания записи. Затем вывод: шаблон со списком. Затем настройки, плановые задачи и уведомления, и только в конце оформление и мелочи. Такой порядок защищает от самой частой ошибки новичков, когда красивый интерфейс строится над данными, структура которых позже меняется.

Каждый шаг фиксируйте в git отдельным коммитом и поднимайте версию в version.php только тогда, когда меняете что-то из каталога db/. Лишние подъёмы версии безвредны, но засоряют историю обновлений на рабочих сайтах.

Проверка перед первой выкладкой

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

Откуда брать правильные значения и образцы

Когда пишете первый плагин, не придумывайте структуру по памяти. В самом коде Moodle лежат образцы всех типов: для local-плагина хорошим ориентиром служат небольшие плагины ядра, а в документации на moodledev.io есть описания каждого API. Для проверки шаблона плагина полезен официальный генератор каркаса плагинов (плагин tool_pluginskel из каталога): он создаёт заготовку файлов по описанию. Я использую его редко, потому что руками для local-плагина получается быстрее, но для mod или block заготовка экономит время и защищает от пропущенных файлов.

Ещё одно правило: каждое слово в именах должно быть осмысленным. Название вроде local_test2 приживается на рабочем сайте на годы, а переименовать его нельзя. Подумайте над именем заранее: короткое, отражающее назначение, без привязки к конкретному заказчику, если плагин может пригодиться другим.

Для самопроверки после установки задайте себе три вопроса. Видит ли страницу пользователь без права? Остаётся ли плагин рабочим, если выключить отладку? Корректно ли он удаляется? Если на все три ответ верный, каркас готов к росту, и дальше можно подключать базу данных, формы и шаблоны, не переделывая основу.

Что добавить дальше

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

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

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