Если плагин принимает от пользователей документы, сканы, справки или отдаёт сформированные PDF, нужно решить три вопроса: куда файл положить, как показать его в форме и кому разрешить скачать. В Moodle на всё это есть File API. Использовать его нужно строго по правилам: самодельная папка в moodledata ломается при переносе, бэкапе и проверке прав.
Как устроено хранение
На диске файлы лежат в moodledata/filedir. Имя файла на диске — SHA1 от его содержимого, например filedir/ab/cd/abcd…. Поэтому два одинаковых файла хранятся в одном экземпляре. «Настоящая» информация — в таблице files: там имя, путь, пользователь, дата, хэш содержимого, размер и самое важное — адрес в системе Moodle из пяти полей плюс имя.
| Поле | Смысл | Пример |
|---|---|---|
contextid | Контекст, к которому относится файл | Контекст системы или курса |
component | Кому принадлежит файл | local_example |
filearea | Именованная область внутри компонента | documents |
itemid | Разделитель внутри области | Идентификатор записи |
filepath | Виртуальный путь с начальным и конечным слэшем | / |
filename | Имя файла | spravka.pdf |
Эти шесть значений однозначно определяют файл. Справочник находится на странице File API. Из-за такого устройства в Moodle не бывает «пути к файлу» в смысле диска: доступ всегда идёт через файловое хранилище.
Сохранение файла из кода
Когда плагин сам формирует файл (выписка, ведомость), его кладут в хранилище так:
$fs = get_file_storage();
$record = [
'contextid' => \context_system::instance()->id,
'component' => 'local_example',
'filearea' => 'documents',
'itemid' => $docid,
'filepath' => '/',
'filename' => 'vypiska.pdf',
];
$file = $fs->create_file_from_string($record, $pdfcontent);
Если исходный файл уже лежит на диске, используйте create_file_from_pathname(). Попытка создать файл с тем же адресом вызовет исключение, поэтому перед созданием проверьте существование через $fs->get_file(...) или удалите старый. Чтобы получить все файлы области, вызывают get_area_files() с контекстом, компонентом, областью и itemid.
Загрузка файлов пользователем через форму
Пользователь загружает файл в элемент формы filemanager (или filepicker для одного файла). Сначала файл попадает в черновую область (draft area), привязанную к пользователю. Только после сохранения формы его нужно перенести в постоянную область вызовом file_save_draft_area_files():
// В определении формы.
$mform->addElement('filemanager', 'attachments', 'Документы', null, [
'subdirs' => 0,
'maxfiles' => 5,
'accepted_types' => ['.pdf', '.jpg', '.png'],
]);
// При открытии формы: подготовить черновик из сохранённых файлов.
$draftid = file_get_submitted_draft_itemid('attachments');
file_prepare_draft_area($draftid, $context->id, 'local_example', 'documents', $docid,
['subdirs' => 0, 'maxfiles' => 5]);
$data->attachments = $draftid;
// После отправки: перенести из черновика в постоянное хранилище.
file_save_draft_area_files($data->attachments, $context->id,
'local_example', 'documents', $docid, ['subdirs' => 0, 'maxfiles' => 5]);
Это самая частая точка ошибок. Если после отправки формы файлы «исчезли», проверьте, что для редактирования вызывалась подготовка черновика, а для сохранения — перенос, и что параметры (контекст, компонент, область, itemid) совпадают в обоих местах. Ограничения по типам файлов в форме — удобство, а не защита: проверку содержимого при необходимости выполняйте на сервере. Подробнее про элементы форм в статье про Forms API и moodleform.
Выдача файла: функция pluginfile
Файлы из хранилища выдаёт скрипт pluginfile.php. Адрес имеет форму /pluginfile.php/{contextid}/{component}/{filearea}/{itemid}/{путь}/{имя}. Скрипт определяет компонент и вызывает в его lib.php функцию имякомпонента_pluginfile. Именно здесь решается, кому можно скачать файл. Если функции нет или она не отдала файл, пользователь получит ошибку.
function local_example_pluginfile($course, $cm, $context, $filearea, $args, $forcedownload, array $options = []) {
if ($context->contextlevel != CONTEXT_SYSTEM) {
return false;
}
if ($filearea !== 'documents') {
return false;
}
require_login();
require_capability('local/example:viewdocuments', $context);
$itemid = (int)array_shift($args);
$filename = array_pop($args);
$filepath = $args ? '/' . implode('/', $args) . '/' : '/';
$fs = get_file_storage();
$file = $fs->get_file($context->id, 'local_example', $filearea, $itemid, $filepath, $filename);
if (!$file || $file->is_directory()) {
return false;
}
send_stored_file($file, 0, 0, true, $options);
}
Обратите внимание на проверку не только входа, но и принадлежности: если вход выполнен, а права проверены только по роли, один слушатель сможет угадать itemid другого и скачать чужой документ. Для личных документов сверяйте владельца записи (itemid → запись → userid) с текущим пользователем. Четвёртый параметр send_stored_file() — принудительное скачивание вместо открытия в браузере; для документов обычно включают.
Ссылку на файл строят методом moodle_url::make_pluginfile_url() с теми же значениями адреса, не собирая строку вручную: тогда будут учтены особенности установки и подпапки.
Что проверять и частые ошибки
| Симптом | Причина | Решение |
|---|---|---|
| «Файл не найден» по правильной ссылке | Функция pluginfile возвращает false: не совпала область, контекст или itemid | Отладить значения $args; проверить путь и имя файла |
| Чужие документы доступны по подбору номера | Проверяются только права роли, но не владелец | Сверять принадлежность записи пользователю |
| Файлы пропали после сохранения формы | Не вызвана file_save_draft_area_files или не совпали параметры | Использовать один набор значений в подготовке и сохранении |
| Диск растёт, хотя записи удалены | Файлы плагина не удаляются вместе с записью | Вызвать delete_area_files в коде удаления |
| Не создаётся файл с тем же именем | Адрес уже занят | Проверить get_file и удалить прежний или менять filename |
| Файл не попал в резервную копию курса | Плагин не описал файловые области для backup | Реализовать резервное копирование области в backup-API плагина (если это модуль) или задокументировать, что копия не охватывает файлы |
Для личных данных учитывайте и Privacy API: файлы пользователя нужно уметь экспортировать и удалять по запросу, о чём в блоге есть заметка про персональные данные и 152-ФЗ. Такая схема подходит для личного кабинета слушателя, где методист проверяет загруженные документы: загрузка в черновик, перенос в область плагина, просмотр через защищённую выдачу и удаление вместе с записью.
Размеры, типы и проверка содержимого
Предел загрузки складывается из нескольких слоёв. На уровне PHP это upload_max_filesize и post_max_size, на уровне веб-сервера лимит тела запроса, на уровне Moodle максимальный размер на сайте и в курсе, а в форме плагина ещё и параметр maxbytes. Действует самый строгий. Пользователь, жалующийся, что файл на 20 МБ «не грузится», упёрся обычно в лимит веб-сервера, о котором Moodle не знает: он увидит страницу ошибки без объяснений.
Ограничение расширений в форме проверяет только имя. Содержимое определяется по-другому: у сохранённого файла можно спросить MIME-тип, а при выдаче учесть его. Если по смыслу плагина нужен только PDF, проверяйте тип на сервере после сохранения и удаляйте лишнее. На сайтах, куда загружают файлы посторонние люди, подключают антивирус: в Moodle есть подсистема проверки, а в плагине антивируса ClamAV файлы проверяются при загрузке.
Временные файлы и кэширование выдачи
Для промежуточных файлов (например, при сборке PDF) не создавайте каталоги вручную. В Moodle есть функции получения временного каталога запроса, который удаляется сам по окончании, и общего временного каталога в moodledata. Файл, созданный в системном /tmp, может оказаться недоступным другому серверу кластера или остаться навсегда.
Параметр срока жизни при выдаче (второй в send_stored_file) управляет заголовками кэширования. Для общедоступных картинок можно поставить большое значение, для личных документов нужен ноль, иначе браузер или прокси сохранят копию. Фрагмент с нулём в примере выше сделан намеренно. Если после удаления документа пользователь всё ещё «видит» его в браузере, проверьте этот параметр.
Наконец, подумайте о резервных копиях. Файлы в хранилище входят в бэкап moodledata, но не в резервную копию курса, если вы не описали область в API резервного копирования. Для личных документов слушателей это обычно и нужно, так что решение должно быть осознанным. Как организовать полное копирование данных сайта, я разбирала в статье про резервное копирование Moodle.
Функции File API: справка
| Функция или метод | Для чего |
|---|---|
get_file_storage() | Получить объект файлового хранилища |
create_file_from_string() | Сохранить файл из строки, например сформированный PDF |
create_file_from_pathname() | Сохранить файл, лежащий на диске |
get_file() / get_area_files() | Найти один файл или все файлы области |
delete_area_files() | Удалить файлы области вместе с записью плагина |
file_prepare_draft_area() | Подготовить черновик перед показом формы |
file_save_draft_area_files() | Перенести файлы из черновика в постоянную область |
moodle_url::make_pluginfile_url() | Построить ссылку на файл |
send_stored_file() | Отдать файл браузеру с заголовками |
Почему нельзя хранить пути самому
Соблазн «сохранить в свою папку внутри moodledata» возникает у каждого, кто впервые делает загрузку документов. Платить за него приходится при переносе сайта, при многосерверной схеме и при проверке прав: файл вне хранилища не знает про контекст, пользователь и сроки хранения, а в резервной копии Moodle его никто не ожидает. Через File API те же задачи решаются стандартно: дедупликация, учёт размера в отчётах, очистка, единая схема прав. Единственная цена — привыкнуть к шести значениям адреса, которые описывают любой файл.
Удаление и сопровождение
Удаляя запись, удаляйте и файлы: $fs->delete_area_files($context->id, 'local_example', 'documents', $docid). Если нужно полностью очистить область, не указывайте itemid. Физически содержимое будет убрано из каталога filedir в ходе плановой очистки, когда на хэш не останется ссылок. При переносе сайта копируйте moodledata целиком вместе с filedir и базой: по отдельности они бесполезны, а детали этого есть в материале про перенос Moodle на другой сервер.
Если плагин для работы с документами нужен под вашу задачу, начните с описания: кто загружает, кто проверяет, как долго хранить. На этом основании делается и структура областей, и права. Для заказа напишите через страницу разработки плагинов Moodle.
Опишите задачу — расскажу, как решить её конкретно в вашем случае. Свяжитесь — разберём вместе.