Proyectos de Subversion Moodle

<?php

// This file is part of Moodle - http://moodle.org/

//

// Moodle is free software: you can redistribute it and/or modify

// it under the terms of the GNU General Public License as published by

// the Free Software Foundation, either version 3 of the License, or

// (at your option) any later version.

//

// Moodle is distributed in the hope that it will be useful,

// but WITHOUT ANY WARRANTY; without even the implied warranty of

// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the

// GNU General Public License for more details.

//

// You should have received a copy of the GNU General Public License

// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.

/**

 * Helper functions to implement the complex get_user_capability_course function.

 *

 * @package core

 * @copyright 2017 The Open University

 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later

 */

namespace core\access;

defined('MOODLE_INTERNAL') || die();

/**

 * Helper functions to implement the complex get_user_capability_course function.

 *

 * @package core

 * @copyright 2017 The Open University

 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later

 */

class get_user_capability_course_helper {

    /**

     * 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

     */

    protected static function get_capability_info_at_each_context($userid, $capability) {

        // Get access data for user.

        $accessdata = get_user_accessdata($userid);

        // Get list of roles for user (any location) and information about these roles.

        $roleids = [];

        foreach ($accessdata['ra'] as $path => $roles) {

            foreach ($roles as $roleid) {

                $roleids[$roleid] = true;

            }

        }

        $rdefs = get_role_definitions(array_keys($roleids));

        // A prohibit in any relevant role prevents the capability

        // in that context and all subcontexts. We need to track that.

        // Here, the array keys are the paths where there is a prohibit the values are the role id.

        $prohibitpaths = [];

        // Get data for required capability at each context path where the user has a role that can

        // affect it.

        $pathroleperms = [];

        foreach ($accessdata['ra'] as $rapath => $roles) {

            foreach ($roles as $roleid) {

                // Get role definition for that role.

                foreach ($rdefs[$roleid] as $rdefpath => $caps) {

                    // Ignore if this override/definition doesn't refer to the relevant cap.

                    if (!array_key_exists($capability, $caps)) {

                        continue;

                    }

                    // Check a role definition or override above ra.

                    if (self::path_is_above($rdefpath, $rapath)) {

                        // Note that $rdefs is sorted by path, so if a more specific override

                        // exists, it will be processed later and override this one.

                        $effectivepath = $rapath;

                    } else if (self::path_is_above($rapath, $rdefpath)) {

                        $effectivepath = $rdefpath;

                    } else {

                        // Not inside an area where the user has the role, so ignore.

                        continue;

                    }

                    // Check for already seen prohibits in higher context. Overrides can't change that.

                    if (self::any_path_is_above($prohibitpaths, $effectivepath)) {

                        continue;

                    }

                    // This is a releavant role assignment / permission combination. Save it.

                    if (!array_key_exists($effectivepath, $pathroleperms)) {

                        $pathroleperms[$effectivepath] = [];

                    }

                    $pathroleperms[$effectivepath][$roleid] = $caps[$capability];

                    // Update $prohibitpaths if necessary.

                    if ($caps[$capability] == CAP_PROHIBIT) {

                        // First remove any lower-context prohibits that might have come from other roles.

                        foreach ($prohibitpaths as $otherprohibitpath => $notused) {

                            if (self::path_is_above($effectivepath, $otherprohibitpath)) {

                                unset($prohibitpaths[$otherprohibitpath]);

                            }

                        }

                        $prohibitpaths[$effectivepath] = $roleid;

                    }

                }

            }

        }

        // Finally, if a later role had a higher-level prohibit that an earlier role,

        // there may be more bits we can prune - but don't prune the prohibits!

        foreach ($pathroleperms as $effectivepath => $roleperms) {

            if ($roleid = self::any_path_is_above($prohibitpaths, $effectivepath)) {

                unset($pathroleperms[$effectivepath]);

                $pathroleperms[$effectivepath][$roleid] = CAP_PROHIBIT;

            }

        }

        return $pathroleperms;

    }

    /**

     * 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.

     */

    protected static function path_is_above($parentpath, $otherpath) {

        return preg_match('~^' . $parentpath . '($|/)~', $otherpath);

    }

    /**

     * 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)

     *      any of the $prohibitpaths, 0 otherwise (so, can be used as a bool).

     */

    protected static function any_path_is_above($prohibitpaths, $otherpath) {

        foreach ($prohibitpaths as $prohibitpath => $roleid) {

            if (self::path_is_above($prohibitpath, $otherpath)) {

                return $roleid;

            }

        }

        return 0;

    }

    /**

     * 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

     */

    protected static function calculate_permission_tree(array $pathroleperms) {

        // Considering each discovered context path as an inflection point, evaluate the user's

        // permission (based on all roles) at each point.

        $pathallows = [];

        $mindepth = 1000;

        $maxdepth = 0;

        foreach ($pathroleperms as $path => $roles) {

            $evaluatedroleperms = [];

            // Walk up the tree starting from this path.

            $innerpath = $path;

            while ($innerpath !== '') {

                $roles = $pathroleperms[$innerpath];

                // Evaluate roles at this path level.

                foreach ($roles as $roleid => $perm) {

                    if (!array_key_exists($roleid, $evaluatedroleperms)) {

                        $evaluatedroleperms[$roleid] = $perm;

                    } else {

                        // The existing one is at a more specific level so it takes precedence

                        // UNLESS this is a prohibit.

                        if ($perm == CAP_PROHIBIT) {

                            $evaluatedroleperms[$roleid] = $perm;

                        }

                    }

                }

                // Go up to next path level (if any).

                do {

                    $innerpath = substr($innerpath, 0, strrpos($innerpath, '/'));

                    if ($innerpath === '') {

                        // No higher level data.

                        break;

                    }

                } while (!array_key_exists($innerpath, $pathroleperms));

            }

            // If we have an allow from any role, and no prohibits, then user can access this path,

            // else not.

            $allow = false;

            foreach ($evaluatedroleperms as $perm) {

                if ($perm == CAP_ALLOW) {

                    $allow = true;

                } else if ($perm == CAP_PROHIBIT) {

                    $allow = false;

                    break;

                }

            }

            // Store the result based on path and depth so that we can process in depth order in

            // the next step.

            $depth = strlen(preg_replace('~[^/]~', '', $path));

            $mindepth = min($depth, $mindepth);

            $maxdepth = max($depth, $maxdepth);

            $pathallows[$depth][$path] = $allow;

        }

        // Organise into a tree structure, processing in depth order so that we have ancestors

        // set up before we encounter their children.

        $root = (object)['allow' => false, 'path' => null, 'children' => []];

        $nodesbypath = [];

        for ($depth = $mindepth; $depth <= $maxdepth; $depth++) {

            // Skip any missing depth levels.

            if (!array_key_exists($depth, $pathallows)) {

                continue;

            }

            foreach ($pathallows[$depth] as $path => $allow) {

                // Value for new tree node.

                $leaf = (object)['allow' => $allow, 'path' => $path, 'children' => []];

                // Try to find a place to join it on if there is one.

                $ancestorpath = $path;

                $found = false;

                while ($ancestorpath) {

                    $ancestorpath = substr($ancestorpath, 0, strrpos($ancestorpath, '/'));

                    if (array_key_exists($ancestorpath, $nodesbypath)) {

                        $found = true;

                        break;

                    }

                }

                if ($found) {

                    $nodesbypath[$ancestorpath]->children[] = $leaf;

                } else {

                    $root->children[] = $leaf;

                }

                $nodesbypath[$path] = $leaf;

            }

        }

        return $root;

    }

    /**

     * 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

     */

    protected static function remove_negative_subtrees($root) {

        // If a node 'starts' negative, we don't need it (as negative is the default) - extract only

        // subtrees that start with a positive value.

        $positiveroot = (object)['allow' => false, 'path' => null, 'children' => []];

        $consider = [$root];

        while ($consider) {

            $first = array_shift($consider);

            foreach ($first->children as $node) {

                if ($node->allow) {

                    // Add directly to new root.

                    $positiveroot->children[] = $node;

                } else {

                    // Consider its children for adding to root (if there are any positive ones).

                    $consider[] = $node;

                }

            }

        }

        return $positiveroot;

    }

    /**

     * Removes duplicate nodes of a tree - where a child node has the same permission as its

     * parent.

     *

     * @param \stdClass $parent Tree root node

     */

    protected static function remove_duplicate_nodes($parent) {

        $length = count($parent->children);

        $index = 0;

        while ($index < $length) {

            $child = $parent->children[$index];

            if ($child->allow === $parent->allow) {

                // Remove child node, but add its children to this node instead.

                array_splice($parent->children, $index, 1);

                $length--;

                $index--;

                foreach ($child->children as $grandchild) {

                    $parent->children[] = $grandchild;

                    $length++;

                }

            } else {

                // Keep child node, but recurse to remove its unnecessary children.

                self::remove_duplicate_nodes($child);

            }

            $index++;

        }

    }

    /**

     * 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

     */

    protected static function get_tree($userid, $capability) {

        // Extract raw capability data for this user and capability.

        $pathroleperms = self::get_capability_info_at_each_context($userid, $capability);

        // Convert the raw data into a permission tree based on context.

        $root = self::calculate_permission_tree($pathroleperms);

        unset($pathroleperms);

        // Simplify the permission tree by removing unnecessary nodes.

        $root = self::remove_negative_subtrees($root);

        self::remove_duplicate_nodes($root);

        // Return the tree.

        return $root;

    }

    /**

     * 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

     */

    protected static function create_sql($parent) {

        global $DB;

        $sql = '';

        $params = [];

        if ($parent->path !== null) {

            // Except for the root element, create the condition that it applies to the context of

            // this element (or anything within it).

            $sql = ' (x.path = ? OR ' . $DB->sql_like('x.path', '?') .')';

            $params[] = $parent->path;

            $params[] = $parent->path . '/%';

            if ($parent->children) {

                // When there are children, these are assumed to have the opposite sign i.e. if we

                // are allowing the parent, we are not allowing the children, and vice versa. So

                // the 'OR' clause for children will be inside this 'AND NOT'.

                $sql .= ' AND NOT (';

            }

        } else if (count($parent->children) > 1) {

            // Place brackets in the query when it is going to be an OR of multiple conditions.

            $sql .= ' (';

        }

        if ($parent->children) {

            $first = true;

            foreach ($parent->children as $child) {

                if ($first) {

                    $first = false;

                } else {

                    $sql  .= ' OR';

                }

                // Recuse to get the child requirements - this will be the check that the context

                // is within the child, plus possibly and 'AND NOT' for any different contexts

                // within the child.

                list ($childsql, $childparams) = self::create_sql($child);

                $sql .= $childsql;

                $params = array_merge($params, $childparams);

            }

            // Close brackets if opened above.

            if ($parent->path !== null || count($parent->children) > 1) {

                $sql .= ')';

            }

        }

        return [$sql, $params];

    }

    /**

     * 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

     */

    public static function get_sql($userid, $capability) {

        // Get a tree of capability permission at various contexts for current user.

        $root = self::get_tree($userid, $capability);

        // The root node always has permission false. If there are no child nodes then the user

        // cannot access anything.

        if (!$root->children) {

            return [false, false];

        }

        // Get SQL to limit contexts based on the permission tree.

        return self::create_sql($root);

    }

    /**

     * Map fieldnames to get ready for the SQL query.

     *

     * @param string $fieldsexceptid A comma-separated list of the fields you require, not including id.

     *   Add ctxid, ctxpath, ctxdepth etc to return course context information for preloading.

     * @return string Mapped field list for the SQL query.

     */

    public static function map_fieldnames(string $fieldsexceptid = ''): string {

        // Convert fields list and ordering.

        $fieldlist = '';

        if ($fieldsexceptid) {

            $fields = array_map('trim', explode(',', $fieldsexceptid));

            foreach ($fields as $field) {

                // Context fields have a different alias.

                if (strpos($field, 'ctx') === 0) {

                    switch($field) {

                        case 'ctxlevel' :

                            $realfield = 'contextlevel';

                            break;

                        case 'ctxinstance' :

                            $realfield = 'instanceid';

                            break;

                        default:

                            $realfield = substr($field, 3);

                            break;

                    }

                    $fieldlist .= ',x.' . $realfield . ' AS ' . $field;

                } else {

                    $fieldlist .= ',c.'.$field;

                }

            }

        }

        return $fieldlist;

    }

}