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

Права доступа в плагине Moodle: access.php, capabilities и проверки в коде

Как устроены capabilities в Moodle: описание прав в db/access.php, уровни контекста, require_capability и has_capability, типичные ошибки с правами в плагинах.

Как устроены capabilities в Moodle: описание прав в db/access.php, уровни контекста, require_capability и has_capability, типичные ошибки с правами в плагинах.

Права в Moodle это не роли в вашем коде. Плагин объявляет право (capability), ядро хранит в базе, каким ролям оно разрешено в каком контексте, а код плагина лишь спрашивает: «может ли этот пользователь сделать это здесь». Благодаря этому администратор настраивает доступ в интерфейсе, не трогая код. Но схема работает, только если плагин объявил права грамотно и проверяет их там, где нужно. Основную часть ошибок безопасности в сторонних плагинах составляют именно отсутствующие проверки. Общую картину ролей я описывала в материале про роли и права в Moodle, а здесь разбор с точки зрения разработчика.

Как описывается право в access.php

Файл db/access.php возвращает массив $capabilities. Ключ это имя права, значение массив с параметрами:

<?php
defined('MOODLE_INTERNAL') || die();

$capabilities = [
    'local/hello:view' => [
        'captype'      => 'read',
        'contextlevel' => CONTEXT_SYSTEM,
        'archetypes'   => [
            'manager' => CAP_ALLOW,
        ],
    ],
    'local/hello:manage' => [
        'riskbitmask'  => RISK_PERSONAL,
        'captype'      => 'write',
        'contextlevel' => CONTEXT_SYSTEM,
        'archetypes'   => [
            'manager' => CAP_ALLOW,
        ],
        'clonepermissionsfrom' => 'moodle/site:config',
    ],
];
ПараметрЧто означает
Ключ массиваИмя вида тип/имя:действие, для local-плагина local/имя:действие
captyperead для просмотра, write для изменений. Права типа write не действуют в заблокированных контекстах (блокировка контекстов), права типа read продолжают работать
contextlevelСамый узкий уровень, на котором право имеет смысл: система, категория, курс, модуль, пользователь, блок
archetypesКакие архетипы ролей получают право при создании: manager, editingteacher, teacher, student, user и другие
riskbitmaskОтметка о рисках (персональные данные, конфигурация, XSS и так далее). Показывается администратору в настройках ролей
clonepermissionsfromКопирует начальные настройки другого права, удобно для «административных» прав

Если право работает с чужими персональными данными, ставьте RISK_PERSONAL. Это не ограничивает доступ, но предупреждает администратора, когда он выдаёт право широкой роли.

Имя права обязательно должно иметь описание в языковом файле: ключ строки равен имени права без префикса типа, то есть для local/hello:view строка $string['hello:view']. Без неё в интерфейсе ролей виден технический код, а Code Checker сообщит об ошибке.

Когда право попадает в систему

Файл access.php читается при установке и обновлении плагина. Правки в нём без повышения version не вступают в силу, и это самая частая причина вопроса «я добавила право, а его нет». Ещё одна тонкость относится к уже работающим сайтам: архетипы применяются в момент создания права. Если вы позже добавите в access.php новую роль с CAP_ALLOW, существующим сайтам это не передастся. Чтобы выдать право программно, в upgrade.php вызывают update_capabilities('local_hello') и затем assign_capability(). Без первого вызова право ещё не записано в таблицу прав, и апгрейд завершится ошибкой.

Контекст: куда привязывать проверку

Любая проверка прав выполняется в контексте, то есть в конкретном месте иерархии Moodle: система → категория → курс → модуль, ответвления идут к пользователю и блоку. Роль, назначенная в верхнем контексте, действует на нижние, если она не переопределена. Поэтому выбор контекста это не формальность.

$system = context_system::instance();
$course = context_course::instance($courseid);
$module = context_module::instance($cmid);
$user   = context_user::instance($userid);

В версиях 4.2 и новее те же классы доступны и в пространстве имён core\context; старые имена остаются рабочими. Я использую короткие вызовы, потому что они понятны на всех поддерживаемых ветках.

Проверки в коде

Для защиты страницы или действия применяйте require_capability(). Для показа кнопки, пункта меню или ветки логики has_capability().

require_login();
$context = context_system::instance();
require_capability('local/hello:view', $context);

if (has_capability('local/hello:manage', $context)) {
    // показать кнопки редактирования
}

Порядок важен: сначала require_login() (для страниц курса с аргументом курса), потом проверка права в нужном контексте. Если пропустить вход, неавторизованный пользователь получит гостевые права, а значит и ту часть данных, которая разрешена гостю.

Отдельный случай: пользователь работает со своими данными. Тогда правило обычно двойное: сам студент видит свои записи без особых прав, а чужие видит тот, у кого есть специальное право. В коде это выглядит как проверка владельца и права:

$ownrecord = ((int) $record->userid === (int) $USER->id);
if (!$ownrecord) {
    require_capability('local/hello:viewall', context_system::instance());
}

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

Не проверяйте короткое имя роли (teacher, manager) в коде. Администратор вправе создать свою роль или переименовать существующую, и проверка по названию перестанет работать. Проверяйте только право.

Поиск пользователей по праву

Для задач вида «разослать уведомление всем, кто может проверять документы» применяйте get_users_by_capability(). Функция учитывает назначения ролей и переопределения в нужном контексте, чего не сделает ручной SQL-запрос по таблице назначений. Для проверки записи пользователя на курс используется is_enrolled(), который умеет проверять и наличие права: параметр $withcapability.

Права в веб-сервисах и AJAX

Все места, где плагин отдаёт данные, считаются входами в систему: страницы, внешние функции, скрипты AJAX, обработчики форм. В функции external API проверка контекста и права обязательна, как и на странице; токен только подтверждает личность. Это тема отдельной статьи про свой веб-сервис.

Типичные ошибки

ОшибкаПоследствиеКак правильно
Тестирование только под администраторомАдминистратор проходит любую проверку, ошибка прав незаметнаТестировать от имени студента, преподавателя, менеджера
Проверки нет вообще, страница «спрятана» отсутствием ссылкиЛюбой, кто знает адрес, видит данныеДобавить require_capability() на каждый вход
Проверка в неправильном контекстеПраво назначено на курс, а проверяется в системе, преподаватель получает отказПроверять в том контексте, где право назначается
Нет строки языка для праваВ списке ролей виден код, ругается Code CheckerДобавить ключ действие в языковой файл
Право объявлено, версия не поднятаПрава в базе нет, проверка всегда отказываетПоднять версию и пройти обновление
Проверка по названию ролиЛомается, когда роль переименовалиПроверять право, а не роль
Доверие параметру userid из запросаПодмена идентификатора даёт чужие данныеСверять владельца записи с $USER->id

Четыре значения права и как они складываются

Для права у роли в контексте есть четыре состояния: не задано (наследуется), разрешено (CAP_ALLOW), запрещено (CAP_PREVENT) и строго запрещено (CAP_PROHIBIT). Итог считается просто: если на пути от контекста вверх встречается CAP_PROHIBIT, право отсутствует, и никто не может его вернуть ниже. Если запретов нет, право есть, когда хотя бы одна роль пользователя разрешает его в этом контексте или в родительском. Запрет CAP_PREVENT перекрывает разрешение, заданное выше, но может быть отменён разрешением на уровне ниже.

Практический вывод: не проектируйте плагин так, будто права привязаны к ролям жёстко. Администратор вправе переопределить доступ в конкретном курсе, и ваш код должен вести себя корректно при любом сочетании. Поэтому единственный источник решения это has_capability() и никакие самодельные списки ролей.

Как я раскладываю права на примере кабинета

Возьмём плагин кабинета слушателя с загрузкой документов и проверкой методистом. Права проектируются от действий, а не от должностей:

ДействиеПравоКонтекстКому по умолчанию
Открыть свой кабинетlocal/cabinet:viewсистемаРоль «Пользователь» (архетип user)
Загрузить свой документlocal/cabinet:uploadсистемаРоль «Пользователь»
Просматривать документы всех слушателейlocal/cabinet:reviewallсистемаМенеджер
Принять или отклонить документlocal/cabinet:approveсистемаМенеджер
Настроить плагинmoodle/site:configсистемаТолько администратор

Обратите внимание, что настройки не получают собственного права: для них достаточно существующего moodle/site:config, которое уже есть в ядре. Создавайте новые права только тогда, когда стандартные не подходят по смыслу. И разделяйте просмотр и изменение: роль «методист-наблюдатель» часто нужна, и она должна видеть всё, но не менять ничего.

Как проверить права руками

В интерфейсе Moodle есть инструмент, которым удобно пользоваться при разработке: на странице «Права» нужного контекста вкладка «Проверить права» показывает, какие права есть у выбранного пользователя и почему. Вторая возможность: команда «Войти как» под нужным пользователем (с правом имитации). Она работает на тестовом сайте и позволяет пройти сценарий глазами студента. В автоматических тестах права назначают через генератор данных: создают пользователя, роль, назначают право в контексте и проверяют результат вызова. Такой тест занимает несколько строк и закрывает целый класс ошибок. Подробнее про тесты в статье следующей партии про PHPUnit.

Отдельная привычка: после каждого изменения access.php прогоните плагин под тремя ролями (студент, преподаватель, менеджер) и запишите, что каждый видит. Ожидаемая и реальная картина обычно расходятся в двух-трёх местах, и это дешевле найти до релиза.

Мини-чек-лист перед релизом

  • Каждая точка входа (страница, AJAX, external-функция, обработчик формы) начинается с входа и проверки права.
  • Для каждого права есть строка в языковом файле и осмысленный архетип.
  • Права, затрагивающие персональные данные, имеют RISK_PERSONAL.
  • Для каждой роли (студент, преподаватель, менеджер) проверено, что ей показывают ровно нужное.

Если вы унаследовали плагин, где проверок нет, это предмет аудита; как я его провожу, описано на странице доработки Moodle. Следующий шаг в разработке: формы, которые принимают данные от пользователя, — Forms API.

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

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