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

Формы в Moodle: Forms API, moodleform и валидация без боли

Как сделать форму в плагине Moodle через moodleform: элементы, setType, правила, серверная валидация, обработка отправки и типичные ошибки Forms API.

Как сделать форму в плагине Moodle через moodleform: элементы, setType, правила, серверная валидация, обработка отправки и типичные ошибки Forms API.

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

Каркас формы

Класс принято класть в classes/form/ плагина. Подключать formslib.php нужно вручную: библиотека форм не загружается автоматически.

<?php
namespace local_hello\form;

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

require_once($CFG->libdir . '/formslib.php');

class note_form extends \moodleform {

    protected function definition() {
        $mform = $this->_form;

        $mform->addElement('text', 'title', get_string('title', 'local_hello'));
        $mform->setType('title', PARAM_TEXT);
        $mform->addRule('title', null, 'required', null, 'client');

        $mform->addElement('textarea', 'body', get_string('body', 'local_hello'),
            ['rows' => 6, 'cols' => 60]);
        $mform->setType('body', PARAM_TEXT);

        $mform->addElement('hidden', 'id');
        $mform->setType('id', PARAM_INT);

        $this->add_action_buttons();
    }

    public function validation($data, $files) {
        $errors = parent::validation($data, $files);
        if (\core_text::strlen($data['title']) > 100) {
            $errors['title'] = get_string('titletoolong', 'local_hello');
        }
        return $errors;
    }
}

Метод definition() описывает поля, validation() проверку данных после отправки. Объект $this->_form это тот самый $mform, с которым вы будете работать в каждой строке описания. Метод add_action_buttons() добавляет кнопки «Сохранить» и «Отмена». Первый аргумент отвечает за показ кнопки отмены, второй за подпись.

Обработка на странице

Форма создаётся на странице, затем страница проверяет три состояния: нажата ли отмена, прошла ли отправка с валидными данными, или форму надо просто показать.

$returnurl = new moodle_url('/local/hello/index.php');
$form = new \local_hello\form\note_form();

if ($form->is_cancelled()) {
    redirect($returnurl);
} else if ($data = $form->get_data()) {
    $record = (object) [
        'userid'      => $USER->id,
        'title'       => $data->title,
        'body'        => $data->body,
        'timecreated' => time(),
    ];
    $DB->insert_record('local_hello_note', $record);
    redirect($returnurl, get_string('saved', 'local_hello'),
        null, \core\output\notification::NOTIFY_SUCCESS);
}

echo $OUTPUT->header();
$form->display();
echo $OUTPUT->footer();

Метод get_data() возвращает объект с очищенными значениями только когда форма отправлена и валидна. Иначе он вернёт null, и страница ещё раз покажет форму, уже с введёнными значениями и текстами ошибок. После сохранения всегда делайте редирект, а не вывод результата в том же запросе: обновление страницы тогда не отправит форму повторно.

Для заполнения формы значениями (редактирование записи) вызывайте $form->set_data($record) до display(). Ключи объекта должны совпадать с именами полей.

Основные элементы

ЭлементЧто даётТип для setType
textОднострочное полеPARAM_TEXT, для адресов PARAM_URL
textareaМногострочное полеPARAM_TEXT
passwordunmaskПароль с кнопкой показаPARAM_RAW (осторожно)
selectВыпадающий список, передаётся массив вариантовPARAM_INT или PARAM_ALPHANUMEXT
advcheckboxФлажок, всегда присылает 0 или 1PARAM_BOOL
date_selector, date_time_selectorВыбор даты и времени, значение приходит меткой временизадаёт сам элемент
editorТекстовый редактор с форматированиемзначение приходит массивом с текстом и форматом
filemanager, filepickerЗагрузка файлов в хранилище Moodleидентификатор черновой области
autocompleteПоиск и выбор нескольких значенийPARAM_INT или PARAM_RAW по данным
hiddenСкрытое поле, для идентификаторовPARAM_INT
static, headerПояснения и заголовки секций, данных не несутне нужен

Для файлов и текстового редактора сохранение устроено сложнее: данные проходят через черновую область File API и требуют отдельных вызовов подготовки и сохранения. Подробно об этом в статье про File API.

setType и очистка данных

Каждое поле, значение которого вы читаете из get_data(), должно иметь setType(). Тип задаёт, как Moodle очистит строку: PARAM_INT оставит целое число, PARAM_TEXT уберёт опасные теги, но сохранит многоязычные конструкции, PARAM_RAW не будет чистить ничего. Последним нужно пользоваться редко и только если дальнейшая обработка сама экранирует вывод. Если тип пропущен, Moodle выдаст предупреждение и применит значение по умолчанию. Это не ошибка отображения, а прямой сигнал о небезопасном коде, и такие предупреждения следует устранять до релиза. Полный список констант PARAM_* есть на moodledev.io в разделе про Data manipulation API.

Валидация: клиентская и серверная

Правила addRule() принимают тип проверки, сообщение и место выполнения. Встроенных проверок хватает на обязательность, длину, число, адрес электронной почты:

$mform->addRule('email', get_string('required'), 'required', null, 'client');
$mform->addRule('email', get_string('invalidemail'), 'email', null, 'client');
$mform->addRule('code', null, 'maxlength', 20, 'client');

Клиентская проверка работает в браузере и существует для удобства. Её легко обойти, поэтому защищает только validation() на сервере. Туда выносите всё, что зависит от базы или других полей: уникальность, диапазоны дат, взаимосвязь значений. Метод получает массив $data и возвращает массив ошибок вида «имя поля → текст»; пустой массив означает успех.

if (!empty($data['enddate']) && $data['enddate'] < $data['startdate']) {
    $errors['enddate'] = get_string('endbeforestart', 'local_hello');
}
if ($DB->record_exists('local_hello_note', ['code' => $data['code']])) {
    $errors['code'] = get_string('codeexists', 'local_hello');
}

При редактировании записи проверка уникальности должна исключать саму редактируемую запись, иначе пользователь не сможет сохранить её без изменений. Передайте идентификатор скрытым полем и добавьте условие в запрос.

Зависимости между полями

Для скрытия и блокировки полей в зависимости от других есть методы hideIf() и disabledIf(). Они работают на клиенте, но данные скрытых полей сервер всё равно получит, поэтому разбирать их в validation() и при сохранении нужно с учётом условия. Подсказки к полям подключаются вызовом addHelpButton(); для него в языковом файле требуется пара строк: само название и строка с суффиксом _help.

Типичные ошибки и что с ними делать

СимптомПричинаРешение
Предупреждение про setTypeТип поля не заданДобавить setType() каждому полю
get_data() всегда nullНе проходит валидация или не совпадает ключ сессииПосмотреть ошибки на форме, проверить, что форма создаётся один раз и с одним именем
Значения не подставляются при редактированииset_data() вызван после display() или ключи не совпадают с именами полейВызывать до отображения, сверить ключи
Форма сохраняется повторно при обновлении страницыНет редиректа после сохраненияДелать redirect() после успешной обработки
Скрытое поле теряет значениеДля hidden нет setType()Задать PARAM_INT или нужный тип
Дата сохраняется со сдвигомМетка времени пересчитывается без учёта часового пояса пользователяИспользовать функции Moodle для дат и не складывать часы вручную
Ошибка пропадает после перезагрузкиОшибка проверяется на клиенте, а на сервере нетПродублировать правило в validation()

Редактирование и удаление записи: полный цикл

Рассмотрим страницу, которая и создаёт, и редактирует заметку. Идентификатор приходит параметром, при его наличии запись загружается и форма заполняется. Права проверяются до создания формы.

$id = optional_param('id', 0, PARAM_INT);
$context = context_system::instance();
require_login();
require_capability('local/hello:manage', $context);

$PAGE->set_url(new moodle_url('/local/hello/edit.php', ['id' => $id]));
$PAGE->set_context($context);

$record = $id ? $DB->get_record('local_hello_note', ['id' => $id], '*', MUST_EXIST) : null;
$form = new \local_hello\form\note_form(null, ['id' => $id]);
if ($record) {
    $form->set_data($record);
}

Функция optional_param() читает параметр запроса и сразу очищает его по типу. Именно так нужно получать все данные из адреса: прямое обращение к $_GET и $_POST в коде Moodle не принято и не проходит проверку. Если запись загружена с MUST_EXIST, то несуществующий идентификатор приведёт к понятной ошибке, а не к пустой форме.

Удаление не стоит делать обычной ссылкой: переход по ссылке не должен менять данные. Используйте запрос с ключом сессии и подтверждение:

$delete = optional_param('delete', 0, PARAM_INT);
if ($delete) {
    require_sesskey();
    $DB->delete_records('local_hello_note', ['id' => $delete]);
    redirect($returnurl, get_string('deleted', 'local_hello'));
}

Функция require_sesskey() проверяет, что запрос пришёл со страницы вашего сайта, а не со стороннего ресурса. В ссылку на удаление ключ вставляют вызовом sesskey(). Формы Moodle добавляют такой ключ сами, поэтому дополнительной защиты для них не нужно, а вот для ссылок и AJAX-запросов она обязательна.

Форма не заменяет проверку прав

Типичная ошибка новичков: форма показывается только менеджеру, значит, обработчик защищён. Это не так. Адрес страницы можно открыть без кнопки, а запрос отправить из любого инструмента. Проверка права должна быть в самом начале скрипта, до создания формы, так как get_data() запускает обработку. Если у формы есть скрытое поле id редактируемой записи, дополнительно убедитесь, что запись принадлежит тому, кто её правит, либо что у пользователя есть право менять чужие. Тема прав разобрана в статье про access.php.

Повторяющиеся группы полей

Если нужно собрать список однотипных элементов (несколько вариантов ответа, несколько контактов), в формах есть метод repeat_elements(). Он размножает набор полей нужное число раз, добавляет кнопку «Добавить ещё» и сам нумерует имена. Использовать его стоит в простых случаях. Когда у каждого повторяющегося блока своя логика, надёжнее сделать отдельную страницу или динамическую форму для одной записи и вывести список через шаблон.

Ещё одна полезная привычка: тексты ошибок валидации пишите для человека, а не для разработчика. «Дата окончания не может быть раньше даты начала» читается быстрее, чем «Неверный диапазон». Все тексты вынесены в языковой файл, а значит их при необходимости изменят без правки кода.

Данные из формы и дальнейшая обработка

Очистка в get_data() гарантирует тип, но не безопасность вывода. Текст из поля PARAM_TEXT безопасно сохранять в базу, а при выводе его всё равно нужно пропускать через format_string() или экранировать в шаблоне. Для больших текстов из редактора сохраняйте не только значение, но и формат (поле noteformat), иначе при выводе функция format_text() не поймёт, как его трактовать. Эта пара полей, текст и формат, встречается во всех таблицах ядра, где есть описания.

Если форма создаёт запись, связанную с другими (пользователь, курс), проверяйте существование связанных объектов на сервере в validation(). Значение из выпадающего списка тоже приходит из запроса, а значит, его можно подменить. Передав в запросе несуществующий идентификатор, злоумышленник не должен получить ни ошибку базы, ни запись в чужой курс.

Что ещё стоит знать

В форму можно передавать данные при создании через массив customdata: он доступен внутри как $this->_customdata. Это удобно для списка вариантов в выпадающем списке или идентификатора курса. Для окон без перезагрузки страницы в ядре есть динамические формы, они строятся на отдельном базовом классе и работают через AJAX. Переходить к ним стоит, когда обычная форма уже написана и нужна только доработка интерфейса.

Если интерфейс в вашем плагине разрастается и проверки с формами занимают половину кода, это повод вынести логику в классы и написать тесты. Как разработать плагин под вашу задачу, описано на странице разработки плагинов Moodle. Дальше в серии: вывод страниц через Output API и Mustache.

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

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