Настройки плагина это то, что отличает продукт от одноразового скрипта: адрес внешнего сервиса, количество дней до напоминания, список включённых функций. Если зашить их в код, любая смена значения превращается в правку и выкладку. Moodle предлагает для этого готовый механизм. Вы описываете настройки в одном файле settings.php, ядро рисует страницу, проверяет значения и хранит их, а код плагина читает одной функцией. Ниже руководство с кодом. Оно продолжает пошаговое создание local-плагина, где в админку уже добавлена внешняя страница.
Как устроено дерево администрирования
Меню «Администрирование» это дерево объектов. Корень содержит разделы (localplugins, modules, users, appearance и другие), внутри разделов находятся категории и страницы. Страницы бывают двух видов: admin_settingpage с набором настроек, которую Moodle рисует сам, и admin_externalpage, ведущая на ваш скрипт. Файл settings.php в корне плагина выполняется при построении дерева и получает готовую переменную $ADMIN. Для плагинов многих типов (блоки, активности, фильтры) система уже создала страницу и положила её в переменную $settings, вам остаётся только добавлять поля. Для local-плагинов страницу создают сами и вешают на раздел localplugins.
Минимальный пример
<?php
defined('MOODLE_INTERNAL') || die();
if ($hassiteconfig) {
$settings = new admin_settingpage('local_hello',
get_string('pluginname', 'local_hello'));
$ADMIN->add('localplugins', $settings);
if ($ADMIN->fulltree) {
$settings->add(new admin_setting_configtext(
'local_hello/apiurl',
get_string('apiurl', 'local_hello'),
get_string('apiurl_desc', 'local_hello'),
'https://example.org/api',
PARAM_URL
));
$settings->add(new admin_setting_configcheckbox(
'local_hello/enabled',
get_string('enabled', 'local_hello'),
get_string('enabled_desc', 'local_hello'),
1
));
}
}
Здесь две важные детали. Условие $hassiteconfig отсекает пользователей без права настройки сайта, так что дерево строится быстрее. Блок $ADMIN->fulltree выполняется только тогда, когда нужна полная страница; вне его строится облегчённое дерево меню. Если поля добавить не внутри этого условия, меню станет тяжёлым, а некоторые установки начнут тормозить.
Первый аргумент каждой настройки это имя в форме компонент/имя. Так Moodle понимает, к какому плагину относится значение. Четвёртый аргумент значение по умолчанию, пятый (у текстового поля) тип очистки данных.
Какие бывают настройки
| Класс | Для чего |
|---|---|
admin_setting_configtext | Строка или число, тип очистки задаётся константой PARAM_* |
admin_setting_configpasswordunmask | Пароль или ключ с возможностью показать значение |
admin_setting_configtextarea | Многострочный текст, например список адресов |
admin_setting_configcheckbox | Включено или выключено |
admin_setting_configselect | Выбор одного значения из списка |
admin_setting_configmulticheckbox | Набор флажков |
admin_setting_configduration | Промежуток времени с единицами измерения |
admin_setting_heading | Заголовок раздела внутри страницы |
admin_setting_description | Пояснительный текст без поля ввода |
Для каждой настройки в языковом файле нужны две строки: название и описание. Принято называть их имя и имя_desc. Обратите внимание, что это те же строки языка, о которых говорилось в предыдущей статье.
Пример настройки-выбора, где варианты задаются массивом:
$settings->add(new admin_setting_configselect(
'local_hello/mode',
get_string('mode', 'local_hello'),
get_string('mode_desc', 'local_hello'),
'daily',
[
'daily' => get_string('mode_daily', 'local_hello'),
'weekly' => get_string('mode_weekly', 'local_hello'),
]
));
Чтение и запись значений
Читают настройки функцией get_config():
$url = get_config('local_hello', 'apiurl');
$all = get_config('local_hello'); // объект со всеми настройками плагина
set_config('lastsync', time(), 'local_hello');
unset_config('lastsync', 'local_hello');
Если настройки нет в базе, get_config() вернёт false, а не значение по умолчанию из settings.php. Значения по умолчанию записываются в базу при установке или обновлении плагина, а также при первом сохранении страницы. Поэтому в коде всегда обрабатывайте случай, когда настройка не задана, и не полагайтесь на то, что она есть. Для служебных значений, которые меняет не администратор, а код (дата последней синхронизации, номер последней обработанной записи), используют те же set_config и get_config, но на странице настроек такие значения не показывают.
Чтобы обращаться к настройкам не прямыми вызовами по всему коду, создайте небольшой класс, который возвращает их с проверкой и значением по умолчанию. Это упрощает тесты и смену хранения.
Секреты и ключи API
Поле admin_setting_configpasswordunmask скрывает значение в браузере, но в таблице config_plugins оно хранится открытым текстом, и любой, кто получит дамп базы, прочитает ключ. Поэтому для ключей платёжных систем и токенов я использую другую схему: значение задаётся в config.php через массив $CFG->forced_plugin_settings.
$CFG->forced_plugin_settings = [
'local_hello' => [
'apikey' => getenv('HELLO_API_KEY'),
],
];
Принудительные значения подставляются в get_config() и в интерфейсе показываются как заблокированные. Ключ хранится вне базы, в окружении сервера, и не попадает в бэкап базы данных. Эту схему стоит продумать до первой выкладки: после утечки дампа ключ придётся менять у провайдера. Принципы хранения секретов подробнее в материале про безопасность Moodle.
Реакция на изменение
Если после сохранения нужно выполнить действие (сбросить кэш, пересчитать данные), у объекта настройки вызывают set_updatedcallback() и передают имя функции или вызываемую структуру. Она запустится при изменении значения через интерфейс.
$setting = new admin_setting_configtext('local_hello/ttl',
get_string('ttl', 'local_hello'),
get_string('ttl_desc', 'local_hello'), '3600', PARAM_INT);
$setting->set_updatedcallback(function () {
\cache_helper::purge_by_event('local_hello_settingschanged');
});
$settings->add($setting);
Название события кэша здесь пример: оно должно быть объявлено в db/caches.php вашего плагина. Подробнее о кэше в одной из следующих статей серии.
Несколько страниц и категория
Когда настроек много, разделите их по страницам и соберите в категорию. Категорию создают как admin_category, а страницы вешают на неё. Внешнюю страницу (отчёт, список) добавляют в ту же категорию.
$ADMIN->add('localplugins', new admin_category('local_hello_cat',
get_string('pluginname', 'local_hello')));
$ADMIN->add('local_hello_cat', new admin_externalpage('local_hello_report',
get_string('report', 'local_hello'),
new moodle_url('/local/hello/index.php'), 'local/hello:view'));
Типичные ошибки
| Симптом | Причина | Что делать |
|---|---|---|
| Страницы настроек нет в списке плагинов | Нет $ADMIN->add или кэш не очищен | Добавить страницу в localplugins, очистить кэши |
| Страница есть, полей нет | Поля добавлены вне $ADMIN->fulltree или с ошибкой в имени класса | Перенести внутрь условия, проверить имена |
get_config возвращает false | Настройка ещё не сохранена, значения по умолчанию в базу не попали | Обрабатывать отсутствие значения в коде |
| Название настройки отображается ключом | Нет строки в языковом файле | Добавить пару имя и имя_desc |
| Значение сохраняется «обрезанным» | Тип PARAM_* слишком строгий | Подобрать подходящий тип, например PARAM_URL для адреса |
| Ключ API виден в дампе базы | Хранится в обычной настройке | Вынести в config.php |
Класс-обёртка над настройками
Если вызывать get_config('local_hello', ...) в десяти местах, то через полгода никто не вспомнит, какие значения допустимы и что делать при пустом. Я выношу чтение в маленький класс. Он возвращает значение с типом, подставляет разумный запасной вариант и скрывает, где оно хранится.
namespace local_hello;
class config {
public static function api_url(): string {
$url = get_config('local_hello', 'apiurl');
return $url ? rtrim($url, '/') : '';
}
public static function is_enabled(): bool {
return (bool) get_config('local_hello', 'enabled');
}
public static function ttl(): int {
$ttl = (int) get_config('local_hello', 'ttl');
return $ttl > 0 ? $ttl : 3600;
}
}
Теперь остальной код пишет config::ttl() и не думает о том, как значение хранится. Если завтра ключ перейдёт в config.php или в окружение, поменяется один класс. Для тестов это тоже удобно: в тесте задаётся значение через set_config(), а перед тестом вызывается resetAfterTest(), чтобы изменения не просочились в другие тесты.
Настройки пользователя и курса
Глобальные настройки плагина для всего сайта. У части задач значения нужны на уровне пользователя или курса, и хранить их в config_plugins неправильно.
| Уровень | Где хранить | Как читать и писать |
|---|---|---|
| Сайт | Таблица настроек плагинов | get_config(), set_config() |
| Пользователь | Предпочтения пользователя | get_user_preferences(), set_user_preference() |
| Курс или элемент курса | Своя таблица плагина или поля модуля | $DB с ключом по курсу |
| Секрет | Принудительная настройка в config.php | get_config() |
Предпочтения пользователя нужно описать в Privacy API через add_user_preference(), иначе они выпадут из выгрузки данных. Об этом подробнее в статье про Privacy API. Настройки курса в своей таблице требуют ещё и резервного копирования, если вы хотите, чтобы они переезжали вместе с курсом; это отдельная работа, и для local-плагина её обычно не делают.
Чем проверять значения
Тип очистки PARAM_* отбрасывает недопустимые символы, но не проверяет смысл. Если число должно лежать в диапазоне или адрес должен отвечать, этого типа мало. У классов настроек есть метод проверки, который можно переопределить: создайте наследника нужного класса и реализуйте в нём validate(), который возвращает true или текст ошибки. Для простых диапазонов часто достаточно подходящего типа, а для связанных настроек (например, дата окончания позже даты начала) помогает проверка в обработчике обновления.
Если вам нужна страница настроек для плагина под вашу организацию, с проверкой значений и доступом по ролям, это обычная часть разработки плагина. А если настройки уже есть, но их значения расходятся между сайтами, посмотрите, как организовать поддержку Moodle.
Типовые настройки, которые я закладываю почти всегда
В большинстве плагинов для заказчиков повторяется один и тот же набор. Переключатель «включить функцию», который позволяет быстро отключить плагин при проблемах, не удаляя его. Адрес и ключ внешней системы, если есть интеграция. Срок хранения данных в днях. Адрес электронной почты, на который уходят служебные уведомления. Режим отладки с подробной записью в журнал: включается только на время разбора проблемы. Именно переключатель включения не раз выручал на рабочих СДО: если плагин начинает мешать, его отключают одним флажком и разбираются спокойно, без срочной правки кода.
Что проверить перед релизом
- Каждая настройка имеет название, описание, разумное значение по умолчанию и корректный тип очистки.
- Код не падает, если настройка не задана.
- Доступ к странице настроек ограничен правом, а сами значения не выводятся в публичных местах.
- Секреты не лежат в базе открытым текстом, если это возможно.
- После удаления плагина его настройки удаляются вместе с ним: ядро делает это само при деинсталляции.
Настройки часто становятся первой частью задачи, а за ними идут интеграции и личные кабинеты. Если вам нужен плагин с продуманной страницей настроек, посмотрите, как строится работа на странице разработки плагинов, а для сложных связок с внешними системами заходите на интеграцию Moodle с 1С. Следующая статья серии посвящена обязательной для хранящих данные плагинов теме: Privacy API.
Опишите задачу — расскажу, как решить её конкретно в вашем случае. Свяжитесь — разберём вместе.