Search moodle.org's
Developer Documentation

See Release Notes
Long Term Support Release

  • Bug fixes for general core bugs in 4.1.x will end 13 November 2023 (12 months).
  • Bug fixes for security issues in 4.1.x will end 10 November 2025 (36 months).
  • PHP version: minimum PHP 7.4.0 Note: minimum PHP version has increased since Moodle 4.0. PHP 8.0.x is supported too.

Differences Between: [Versions 310 and 401] [Versions 311 and 401] [Versions 39 and 401]

Helper functions to implement the complex get_user_capability_course function.

Copyright: 2017 The Open University
License: http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
File Size: 467 lines (20 kb)
Included or required:0 times
Referenced: 0 times
Includes or requires: 0 files

Defines 1 class

get_user_capability_course_helper:: (10 methods):
  get_capability_info_at_each_context()
  path_is_above()
  any_path_is_above()
  calculate_permission_tree()
  remove_negative_subtrees()
  remove_duplicate_nodes()
  get_tree()
  create_sql()
  get_sql()
  map_fieldnames()


Class: get_user_capability_course_helper  - X-Ref

Helper functions to implement the complex get_user_capability_course function.

get_capability_info_at_each_context($userid, $capability)   X-Ref
Based on the given user's access data (roles) and system role definitions, works out
an array of capability values at each relevant context for the given user and capability.

This is organised by the effective context path (the one at which the capability takes
effect) and then by role id. Note, however, that the resulting array only has
the information that will be needed later. If there are Prohibits present in some
roles, then they cannot be overridden by other roles or role overrides in lower contexts,
therefore, such information, if any, is absent from the results.

param: int $userid User id
param: string $capability Capability e.g. 'moodle/course:view'
return: array Array of capability constants, indexed by context path and role id

path_is_above($parentpath, $otherpath)   X-Ref
Test if a context path $otherpath is the same as, or underneath, $parentpath.

param: string $parentpath the path of the parent context.
param: string $otherpath the path of another context.
return: bool true if $otherpath is underneath (or equal to) $parentpath.

any_path_is_above($prohibitpaths, $otherpath)   X-Ref
Test if a context path $otherpath is the same as, or underneath, any of $prohibitpaths.

param: array $prohibitpaths array keys are context paths.
param: string $otherpath the path of another context.
return: int releavant $roleid if $otherpath is underneath (or equal to)

calculate_permission_tree(array $pathroleperms)   X-Ref
Calculates a permission tree based on an array of information about role permissions.

The input parameter must be in the format returned by get_capability_info_at_each_context.

The output is the root of a tree of stdClass objects with the fields 'path' (a context path),
'allow' (true or false), and 'children' (an array of similar objects).

param: array $pathroleperms Array of permissions
return: \stdClass Root object of permission tree

remove_negative_subtrees($root)   X-Ref
Given a permission tree (in calculate_permission_tree format), removes any subtrees that
are negative from the root. For example, if a top-level node of the permission tree has
'false' permission then it is meaningless because the default permission is already false;
this function will remove it. However, if there is a child within that node that is positive,
then that will need to be kept.

param: \stdClass $root Root object
return: \stdClass Filtered tree root

remove_duplicate_nodes($parent)   X-Ref
Removes duplicate nodes of a tree - where a child node has the same permission as its
parent.

param: \stdClass $parent Tree root node

get_tree($userid, $capability)   X-Ref
Gets a permission tree for the given user and capability, representing the value of that
capability at different contexts across the system. The tree will be simplified as far as
possible.

The output is the root of a tree of stdClass objects with the fields 'path' (a context path),
'allow' (true or false), and 'children' (an array of similar objects).

param: int $userid User id
param: string $capability Capability e.g. 'moodle/course:view'
return: \stdClass Root node of tree

create_sql($parent)   X-Ref
Creates SQL suitable for restricting by contexts listed in the given permission tree.

This function relies on the permission tree being in the format created by get_tree.
Specifically, all the children of the root element must be set to 'allow' permission,
children of those children must be 'not allow', children of those grandchildren 'allow', etc.

param: \stdClass $parent Root node of permission tree
return: array Two-element array of SQL (containing ? placeholders) and then a params array

get_sql($userid, $capability)   X-Ref
Gets SQL to restrict a query to contexts in which the user has a capability.

This returns an array with two elements (SQL containing ? placeholders, and a params array).
The SQL is intended to be used as part of a WHERE clause. It relies on the prefix 'x' being
used for the Moodle context table.

If the user does not have the permission anywhere at all (so that there is no point doing
the query) then the two returned values will both be false.

param: int $userid User id
param: string $capability Capability e.g. 'moodle/course:view'
return: array Two-element array of SQL (containing ? placeholders) and then a params array

map_fieldnames(string $fieldsexceptid = '')   X-Ref
Map fieldnames to get ready for the SQL query.

param: string $fieldsexceptid A comma-separated list of the fields you require, not including id.
return: string Mapped field list for the SQL query.