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

Страница настроек плагина Moodle: settings.php, admin tree и хранение значений

Как добавить настройки плагину Moodle: settings.php, admin_settingpage, классы admin_setting_*, get_config и set_config, секреты и значения по умолчанию.

Как добавить настройки плагину Moodle: settings.php, admin_settingpage, классы admin_setting_*, get_config и set_config, секреты и значения по умолчанию.

Настройки плагина это то, что отличает продукт от одноразового скрипта: адрес внешнего сервиса, количество дней до напоминания, список включённых функций. Если зашить их в код, любая смена значения превращается в правку и выкладку. 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.phpget_config()

Предпочтения пользователя нужно описать в Privacy API через add_user_preference(), иначе они выпадут из выгрузки данных. Об этом подробнее в статье про Privacy API. Настройки курса в своей таблице требуют ещё и резервного копирования, если вы хотите, чтобы они переезжали вместе с курсом; это отдельная работа, и для local-плагина её обычно не делают.

Чем проверять значения

Тип очистки PARAM_* отбрасывает недопустимые символы, но не проверяет смысл. Если число должно лежать в диапазоне или адрес должен отвечать, этого типа мало. У классов настроек есть метод проверки, который можно переопределить: создайте наследника нужного класса и реализуйте в нём validate(), который возвращает true или текст ошибки. Для простых диапазонов часто достаточно подходящего типа, а для связанных настроек (например, дата окончания позже даты начала) помогает проверка в обработчике обновления.

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

Типовые настройки, которые я закладываю почти всегда

В большинстве плагинов для заказчиков повторяется один и тот же набор. Переключатель «включить функцию», который позволяет быстро отключить плагин при проблемах, не удаляя его. Адрес и ключ внешней системы, если есть интеграция. Срок хранения данных в днях. Адрес электронной почты, на который уходят служебные уведомления. Режим отладки с подробной записью в журнал: включается только на время разбора проблемы. Именно переключатель включения не раз выручал на рабочих СДО: если плагин начинает мешать, его отключают одним флажком и разбираются спокойно, без срочной правки кода.

Что проверить перед релизом

  • Каждая настройка имеет название, описание, разумное значение по умолчанию и корректный тип очистки.
  • Код не падает, если настройка не задана.
  • Доступ к странице настроек ограничен правом, а сами значения не выводятся в публичных местах.
  • Секреты не лежат в базе открытым текстом, если это возможно.
  • После удаления плагина его настройки удаляются вместе с ним: ядро делает это само при деинсталляции.

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

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

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