Перейти к содержимому
M
Все статьи
Технологии 9 мин чтения

Файлы в Moodle: File API, filearea и как плагину хранить и отдавать документы

Как работает File API в Moodle: контекст, component, filearea и itemid, сохранение файла из плагина и защищённая выдача через функцию pluginfile.

Как работает File API в Moodle: контекст, component, filearea и itemid, сохранение файла из плагина и защищённая выдача через функцию pluginfile.

Если плагин принимает от пользователей документы, сканы, справки или отдаёт сформированные 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.

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

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