Moodle's Access API is a powerful tool for managing user permissions, but there's a wealth of practical knowledge that isn't captured in the official documentation (Which you SHOULD read). This blog post aims to fill that gap, providing software developers and Moodle administrators with a deeper technical understanding of Moodle's capabilities and permissions system.
Understanding Capability Risks
Capabilities in Moodle are associated with risks that affect site security and integrity. For instance, a capability tagged with RISK_XSS implies that granting this capability could allow a user to inject potentially harmful scripts. As a developer, it's crucial to understand these risks to prevent security breaches. When defining new capabilities for your plugin, always assign the appropriate risk level:
$capabilities = [
'mod/myplugin:dosomething' => [
'riskbitmask' => RISK_XSS | RISK_CONFIG,
// ...
],
];
Capability Caching and Performance
Moodle caches capabilities to optimize performance. However, developers must be aware of the implications. When you update capabilities, you must purge the cache to apply changes. This can be done via the Moodle interface, programmatically:
if ($capabilities_have_changed) {
purge_all_caches();
}
or via the CLI:
/usr/bin/php /yourmoodleinstallation/admin/cli/purge_caches.php
Fine-Tuning with Capability Overrides
Capability overrides allow for precise permission control. For example, a user might have the capability mod/forum:post at the course level but could be overridden at the forum level to restrict posting in a specific forum. This is done by adjusting the permissions in the context of the specific forum:
$context = context_module::instance($forum->cmid);
assign_capability('mod/forum:post', CAP_PROHIBIT, $roleid, $context->id);
Locking Capabilities
Locking a capability is a security measure to prevent its alteration in sub-contexts. This is particularly important for capabilities that could compromise the site's integrity, like moodle/site:config.
Let's say you have a capability called moodle/site:config, which allows users to change site-wide settings. This is a powerful capability that you might only want Site Administrators to have. To prevent this capability from being accidentally granted at lower levels of the context hierarchy (like in a course or module), you can lock this capability.
In practical terms, Moodle implements this through the CAP_PROHIBIT permission level. When you set a capability to CAP_PROHIBIT at a higher context level, it cannot be overridden by any CAP_ALLOW at a lower level.
It's important to note that CAP_PROHIBIT is a very strong setting and should be used sparingly, as it can have far-reaching effects and can be difficult to override if circumstances change. It's a tool for enforcing strict permissions policies and ensuring that certain capabilities are tightly controlled.
Archetype Mapping and Role Definitions
Archetypes are templates for roles that provide a starting point for capability assignments. When creating a new role or capability, it's important to map it correctly to an archetype:
$capabilities = [
'mod/myplugin:view' => [
'captype' => 'read',
'contextlevel' => CONTEXT_MODULE,
'archetypes' => [
'student' => CAP_ALLOW,
'teacher' => CAP_ALLOW,
// ...
],
],
];
User Contexts and Permissions
User contexts define the boundaries of a user's permissions. For example, a teacher's user context may allow them to edit courses they're assigned to but not others. When developing plugins, it's important to check the user's context before allowing certain actions:
$context = context_course::instance($courseid);
if (has_capability('moodle/course:edit', $context)) {
// The user can edit this course.
}
Regular Capability Audits
Conducting regular audits of capabilities ensures that permissions are current and secure. This involves reviewing the capabilities defined in your plugin and ensuring they are still necessary and properly scoped. It's also a good practice to document any changes and their implications for users.
Tips for Plugin Developers
When developing a Moodle plugin, define capabilities that are consistent with Moodle's conventions. For example, if your plugin is a new activity module, you might define capabilities like this:
$capabilities = [
'mod/myactivity:view' => [
// Definition
],
'mod/myactivity:submit' => [
// Definition
],
];
Remember to increment your plugin's version number after changing capabilities to trigger the upgrade scripts that apply these changes, this can be done via the administration interface, or via the CLI:
/usr/bin/php /yourmoodleinstallation/admin/cli/upgrade.php
By understanding these technical details and incorporating them into your development practices, you can leverage Moodle's capabilities system to its fullest extent, creating secure and efficient plugins that enhance the Moodle experience.
And That's it for today! I hope you found this helpful post. If you have any questions, please contact me on LinkedIn.
Happy coding!