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