Search moodle.org's
Developer Documentation

See Release Notes

  • Bug fixes for general core bugs in 4.2.x will end 22 April 2024 (12 months).
  • Bug fixes for security issues in 4.2.x will end 7 October 2024 (18 months).
  • PHP version: minimum PHP 8.0.0 Note: minimum PHP version has increased since Moodle 4.1. PHP 8.1.x is supported too.
<?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/>.

/**
 * Class that holds a tree of availability conditions.
 *
 * @package core_availability
 * @copyright 2014 The Open University
 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 */

namespace core_availability;

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

/**
 * Class that holds a tree of availability conditions.
 *
 * The structure of this tree in JSON input data is:
 *
 * { op:'&', c:[] }
 *
 * where 'op' is one of the OP_xx constants and 'c' is an array of children.
 *
 * At the root level one of the following additional values must be included:
 *
 * op '|' or '!&'
 *   show:true
 *   Boolean value controlling whether a failed match causes the item to
 *   display to students with information, or be completely hidden.
 * op '&' or '!|'
 *   showc:[]
 *   Array of same length as c with booleans corresponding to each child; you
 *   can make it be hidden or shown depending on which one they fail. (Anything
 *   with false takes precedence.)
 *
 * @package core_availability
 * @copyright 2014 The Open University
 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 */
class tree extends tree_node {
    /** @var int Operator: AND */
    const OP_AND = '&';
    /** @var int Operator: OR */
    const OP_OR = '|';
    /** @var int Operator: NOT(AND) */
    const OP_NOT_AND = '!&';
    /** @var int Operator: NOT(OR) */
    const OP_NOT_OR = '!|';

    /** @var bool True if this tree is at root level */
    protected $root;

    /** @var string Operator type (OP_xx constant) */
    protected $op;

    /** @var tree_node[] Children in this branch (may be empty array if needed) */
    protected $children;

    /**
     * Array of 'show information or hide completely' options for each child.
     * This array is only set for the root tree if it is in AND or NOT OR mode,
     * otherwise it is null.
     *
     * @var bool[]
     */
    protected $showchildren;

    /**
     * Single 'show information or hide completely' option for tree. This option
     * is only set for the root tree if it is in OR or NOT AND mode, otherwise
     * it is true.
     *
     * @var bool
     */
    protected $show;

    /**
     * Display a representation of this tree (used for debugging).
     *
     * @return string Text representation of tree
     */
    public function __toString() {
        $result = '';
        if ($this->root && is_null($this->showchildren)) {
            $result .= $this->show ? '+' : '-';
        }
        $result .= $this->op . '(';
        $first = true;
        foreach ($this->children as $index => $child) {
            if ($first) {
                $first = false;
            } else {
                $result .= ',';
            }
            if (!is_null($this->showchildren)) {
                $result .= $this->showchildren[$index] ? '+' : '-';
            }
            $result .= (string)$child;
        }
        $result .= ')';
        return $result;
    }

    /**
     * Decodes availability structure.
     *
     * This function also validates the retrieved data as follows:
     * 1. Data that does not meet the API-defined structure causes a
     *    coding_exception (this should be impossible unless there is
     *    a system bug or somebody manually hacks the database).
     * 2. Data that meets the structure but cannot be implemented (e.g.
     *    reference to missing plugin or to module that doesn't exist) is
     *    either silently discarded (if $lax is true) or causes a
     *    coding_exception (if $lax is false).
     *
     * @see decode_availability
     * @param \stdClass $structure Structure (decoded from JSON)
     * @param boolean $lax If true, throw exceptions only for invalid structure
     * @param boolean $root If true, this is the root tree
     * @return tree Availability tree
     * @throws \coding_exception If data is not valid structure
     */
    public function __construct($structure, $lax = false, $root = true) {
        $this->root = $root;

        // Check object.
        if (!is_object($structure)) {
            throw new \coding_exception('Invalid availability structure (not object)');
        }

        // Extract operator.
        if (!isset($structure->op)) {
            throw new \coding_exception('Invalid availability structure (missing ->op)');
        }
        $this->op = $structure->op;
        if (!in_array($this->op, array(self::OP_AND, self::OP_OR,
                self::OP_NOT_AND, self::OP_NOT_OR), true)) {
            throw new \coding_exception('Invalid availability structure (unknown ->op)');
        }

        // For root tree, get show options.
        $this->show = true;
        $this->showchildren = null;
        if ($root) {
            if ($this->op === self::OP_AND || $this->op === self::OP_NOT_OR) {
                // Per-child show options.
                if (!isset($structure->showc)) {
                    throw new \coding_exception(
                            'Invalid availability structure (missing ->showc)');
                }
                if (!is_array($structure->showc)) {
                    throw new \coding_exception(
                            'Invalid availability structure (->showc not array)');
                }
                foreach ($structure->showc as $value) {
                    if (!is_bool($value)) {
                        throw new \coding_exception(
                                'Invalid availability structure (->showc value not bool)');
                    }
                }
                // Set it empty now - add corresponding ones later.
                $this->showchildren = array();
            } else {
                // Entire tree show option. (Note: This is because when you use
                // OR mode, say you have A OR B, the user does not meet conditions
                // for either A or B. A is set to 'show' and B is set to 'hide'.
                // But they don't have either, so how do we know which one to do?
                // There might as well be only one value.)
                if (!isset($structure->show)) {
                    throw new \coding_exception(
                            'Invalid availability structure (missing ->show)');
                }
                if (!is_bool($structure->show)) {
                    throw new \coding_exception(
                            'Invalid availability structure (->show not bool)');
                }
                $this->show = $structure->show;
            }
        }

        // Get list of enabled plugins.
        $pluginmanager = \core_plugin_manager::instance();
        $enabled = $pluginmanager->get_enabled_plugins('availability');

        // For unit tests, also allow the mock plugin type (even though it
        // isn't configured in the code as a proper plugin).
        if (PHPUNIT_TEST) {
            $enabled['mock'] = true;
        }

        // Get children.
        if (!isset($structure->c)) {
            throw new \coding_exception('Invalid availability structure (missing ->c)');
        }
        if (!is_array($structure->c)) {
            throw new \coding_exception('Invalid availability structure (->c not array)');
        }
        if (is_array($this->showchildren) && count($structure->showc) != count($structure->c)) {
            throw new \coding_exception('Invalid availability structure (->c, ->showc mismatch)');
        }
        $this->children = array();
        foreach ($structure->c as $index => $child) {
            if (!is_object($child)) {
                throw new \coding_exception('Invalid availability structure (child not object)');
            }

            // First see if it's a condition. These have a defined type.
            if (isset($child->type)) {
                // Look for a plugin of this type.
                $classname = '\availability_' . $child->type . '\condition';
                if (!array_key_exists($child->type, $enabled)) {
                    if ($lax) {
                        // On load of existing settings, ignore if class
                        // doesn't exist.
                        continue;
                    } else {
                        throw new \coding_exception('Unknown condition type: ' . $child->type);
                    }
                }
                $this->children[] = new $classname($child);
            } else {
                // Not a condition. Must be a subtree.
                $this->children[] = new tree($child, $lax, false);
            }
            if (!is_null($this->showchildren)) {
                $this->showchildren[] = $structure->showc[$index];
            }
        }
    }

    public function check_available($not, info $info, $grabthelot, $userid) {
        // If there are no children in this group, we just treat it as available.
        $information = '';
        if (!$this->children) {
            return new result(true);
        }

        // Get logic flags from operator.
        list($innernot, $andoperator) = $this->get_logic_flags($not);

        if ($andoperator) {
            $allow = true;
        } else {
            $allow = false;
        }
        $failedchildren = array();
        $totallyhide = !$this->show;
        foreach ($this->children as $index => $child) {
            // Check available and get info.
            $childresult = $child->check_available(
                    $innernot, $info, $grabthelot, $userid);
            $childyes = $childresult->is_available();
            if (!$childyes) {
                $failedchildren[] = $childresult;
                if (!is_null($this->showchildren) && !$this->showchildren[$index]) {
                    $totallyhide = true;
                }
            }

            if ($andoperator && !$childyes) {
                $allow = false;
                // Do not exit loop at this point, as we will still include other info.
            } else if (!$andoperator && $childyes) {
                // Exit loop since we are going to allow access (from this tree at least).
                $allow = true;
                break;
            }
        }

        if ($allow) {
            return new result(true);
        } else if ($totallyhide) {
            return new result(false);
        } else {
            return new result(false, $this, $failedchildren);
        }
    }

    public function is_applied_to_user_lists() {
        return true;
    }

    /**
     * Tests against a user list. Users who cannot access the activity due to
     * availability restrictions will be removed from the list.
     *
     * This test ONLY includes conditions which are marked as being applied to
     * user lists. For example, group conditions are included but date
     * conditions are not included.
     *
     * The function operates reasonably efficiently i.e. should not do per-user
     * database queries. It is however likely to be fairly slow.
     *
     * @param array $users Array of userid => object
     * @param bool $not If tree's parent indicates it's being checked negatively
     * @param info $info Info about current context
     * @param capability_checker $checker Capability checker
     * @return array Filtered version of input array
     */
    public function filter_user_list(array $users, $not, info $info,
            capability_checker $checker) {
        // Get logic flags from operator.
        list($innernot, $andoperator) = $this->get_logic_flags($not);

        if ($andoperator) {
            // For AND, start with the whole result and whittle it down.
            $result = $users;
        } else {
            // For OR, start with nothing.
            $result = array();
            $anyconditions = false;
        }

        // Loop through all valid children.
        foreach ($this->children as $index => $child) {
            if (!$child->is_applied_to_user_lists()) {
                if ($andoperator) {
                    continue;
                } else {
                    // OR condition with one option that doesn't restrict user
                    // lists = everyone is allowed.
                    $anyconditions = false;
                    break;
                }
            }
            $childresult = $child->filter_user_list($users, $innernot, $info, $checker);
            if ($andoperator) {
                $result = array_intersect_key($result, $childresult);
            } else {
                // Combine results into array.
                foreach ($childresult as $id => $user) {
                    $result[$id] = $user;
                }
                $anyconditions = true;
            }
        }

        // For OR operator, if there were no conditions just return input.
        if (!$andoperator && !$anyconditions) {
            return $users;
        } else {
            return $result;
        }
    }

    public function get_user_list_sql($not, info $info, $onlyactive) {
        global $DB;
        // Get logic flags from operator.
        list($innernot, $andoperator) = $this->get_logic_flags($not);

        // Loop through all valid children, getting SQL for each.
        $childresults = array();
        foreach ($this->children as $index => $child) {
            if (!$child->is_applied_to_user_lists()) {
                if ($andoperator) {
                    continue;
                } else {
                    // OR condition with one option that doesn't restrict user
                    // lists = everyone is allowed.
                    $childresults = array();
                    break;
                }
            }
            $childresult = $child->get_user_list_sql($innernot, $info, $onlyactive);
            if ($childresult[0]) {
                $childresults[] = $childresult;
            } else if (!$andoperator) {
                // When using OR operator, if any part doesn't have restrictions,
                // then nor does the whole thing.
                return array('', array());
            }
        }

        // If there are no conditions, return null.
        if (!$childresults) {
            return array('', array());
        }
        // If there is a single condition, return it.
        if (count($childresults) === 1) {
            return $childresults[0];
        }

        // Combine results using INTERSECT or UNION.
        $outsql = null;
        $subsql = array();
        $outparams = array();
        foreach ($childresults as $childresult) {
            $subsql[] = $childresult[0];
            $outparams = array_merge($outparams, $childresult[1]);
        }
        if ($andoperator) {
            $outsql = $DB->sql_intersect($subsql, 'id');
        } else {
            $outsql = '(' . join(') UNION (', $subsql) . ')';
        }
        return array($outsql, $outparams);
    }

    public function is_available_for_all($not = false) {
        // Get logic flags.
        list($innernot, $andoperator) = $this->get_logic_flags($not);

        // No children = always available.
        if (!$this->children) {
            return true;
        }

        // Check children.
        foreach ($this->children as $child) {
            $innerall = $child->is_available_for_all($innernot);
            if ($andoperator) {
                // When there is an AND operator, then any child that results
                // in unavailable status would cause the whole thing to be
                // unavailable.
                if (!$innerall) {
                    return false;
                }
            } else {
                // When there is an OR operator, then any child which must only
                // be available means the whole thing must be available.
                if ($innerall) {
                    return true;
                }
            }
        }

        // If we get to here then for an AND operator that means everything must
        // be available. From OR it means that everything must be possibly
        // not available.
        return $andoperator;
    }

    /**
     * Gets full information about this tree (including all children) as HTML
     * for display to staff.
     *
     * @param info $info Information about location of condition tree
     * @throws \coding_exception If you call on a non-root tree
     * @return string HTML data (empty string if none)
     */
    public function get_full_information(info $info) {
        if (!$this->root) {
            throw new \coding_exception('Only supported on root item');
        }
        return $this->get_full_information_recursive(false, $info, null, true);
    }

    /**
     * Gets information about this tree corresponding to the given result
     * object. (In other words, only conditions which the student actually
     * fails will be shown - and nothing if display is turned off.)
     *
     * @param info $info Information about location of condition tree
     * @param result $result Result object
     * @throws \coding_exception If you call on a non-root tree
     * @return string HTML data (empty string if none)
     */
    public function get_result_information(info $info, result $result) {
        if (!$this->root) {
            throw new \coding_exception('Only supported on root item');
        }
        return $this->get_full_information_recursive(false, $info, $result, true);
    }

    /**
     * Gets information about this tree (including all or selected children) as
     * HTML for display to staff or student.
     *
     * @param bool $not True if there is a NOT in effect
     * @param info $info Information about location of condition tree
< * @param result $result Result object if this is a student display, else null
> * @param result|null $result Result object if this is a student display, else null
* @param bool $root True if this is the root item * @param bool $hidden Staff display; true if this tree has show=false (from parent) * @return string|renderable Information to render */ protected function get_full_information_recursive(
< $not, info $info, result $result = null, $root, $hidden = false) {
> $not, info $info, ?result $result, $root, $hidden = false) {
// Get list of children - either full list, or those which are shown. $children = $this->children; $staff = true; if ($result) { $children = $result->filter_nodes($children); $staff = false; } // If no children, return empty string. if (!$children) { return ''; } list($innernot, $andoperator) = $this->get_logic_flags($not); // If there is only one child, don't bother displaying this tree // (AND and OR makes no difference). Recurse to the child if a tree, // otherwise display directly. if (count ($children) === 1) { $child = reset($children); if ($this->root && is_null($result)) { if (is_null($this->showchildren)) { $childhidden = !$this->show; } else { $childhidden = !$this->showchildren[0]; } } else { $childhidden = $hidden; } if ($child instanceof tree) { return $child->get_full_information_recursive( $innernot, $info, $result, $root, $childhidden); } else { if ($root) { $result = $child->get_standalone_description($staff, $innernot, $info); } else { $result = $child->get_description($staff, $innernot, $info); } if ($childhidden) { $result .= ' ' . get_string('hidden_marker', 'availability'); } return $result; } } // Multiple children, so prepare child messages (recursive). $items = array(); $index = 0; foreach ($children as $child) { // Work out if this node is hidden (staff view only). $childhidden = $this->root && is_null($result) && !is_null($this->showchildren) && !$this->showchildren[$index]; if ($child instanceof tree) { $items[] = $child->get_full_information_recursive( $innernot, $info, $result, false, $childhidden); } else { $childdescription = $child->get_description($staff, $innernot, $info); if ($childhidden) { $childdescription .= ' ' . get_string('hidden_marker', 'availability'); } $items[] = $childdescription; } $index++; } // If showing output to staff, and root is set to hide completely, // then include this information in the message. if ($this->root) { $treehidden = !$this->show && is_null($result); } else { $treehidden = $hidden; } // Format output for display. return new \core_availability_multiple_messages($root, $andoperator, $treehidden, $items); } /** * Converts the operator for the tree into two flags used for computing * the result. * * The 2 flags are $innernot (whether to set $not when calling for children) * and $andoperator (whether to use AND or OR operator to combine children). * * @param bool $not Not flag passed to this tree * @return array Array of the 2 flags ($innernot, $andoperator) */ public function get_logic_flags($not) { // Work out which type of logic to use for the group. switch($this->op) { case self::OP_AND: case self::OP_OR: $negative = false; break; case self::OP_NOT_AND: case self::OP_NOT_OR: $negative = true; break; default: throw new \coding_exception('Unknown operator'); } switch($this->op) { case self::OP_AND: case self::OP_NOT_AND: $andoperator = true; break; case self::OP_OR: case self::OP_NOT_OR: $andoperator = false; break; default: throw new \coding_exception('Unknown operator'); } // Select NOT (or not) for children. It flips if this is a 'not' group. $innernot = $negative ? !$not : $not; // Select operator to use for this group. If flips for negative, because: // NOT (a AND b) = (NOT a) OR (NOT b) // NOT (a OR b) = (NOT a) AND (NOT b). if ($innernot) { $andoperator = !$andoperator; } return array($innernot, $andoperator); } public function save() { $result = new \stdClass(); $result->op = $this->op; // Only root tree has the 'show' options. if ($this->root) { if ($this->op === self::OP_AND || $this->op === self::OP_NOT_OR) { $result->showc = $this->showchildren; } else { $result->show = $this->show; } } $result->c = array(); foreach ($this->children as $child) { $result->c[] = $child->save(); } return $result; } /** * Checks whether this tree is empty (contains no children). * * @return boolean True if empty */ public function is_empty() { return count($this->children) === 0; } /** * Recursively gets all children of a particular class (you can use a base * class to get all conditions, or a specific class). * * @param string $classname Full class name e.g. core_availability\condition * @return array Array of nodes of that type (flattened, not a tree any more) */ public function get_all_children($classname) { $result = array(); $this->recursive_get_all_children($classname, $result); return $result; } /** * Internal function that implements get_all_children efficiently. * * @param string $classname Full class name e.g. core_availability\condition * @param array $result Output array of nodes */ protected function recursive_get_all_children($classname, array &$result) { foreach ($this->children as $child) { if (is_a($child, $classname)) { $result[] = $child; } if ($child instanceof tree) { $child->recursive_get_all_children($classname, $result); } } } public function update_after_restore($restoreid, $courseid, \base_logger $logger, $name) { $changed = false; foreach ($this->children as $index => $child) { if ($child->include_after_restore($restoreid, $courseid, $logger, $name, info::get_restore_task($restoreid))) { $thischanged = $child->update_after_restore($restoreid, $courseid, $logger, $name); $changed = $changed || $thischanged; } else { unset($this->children[$index]); unset($this->showchildren[$index]);
< $this->showchildren = array_values($this->showchildren);
> $this->showchildren = !is_null($this->showchildren) ? array_values($this->showchildren) : null;
$changed = true; } } return $changed; } public function update_dependency_id($table, $oldid, $newid) { $changed = false; foreach ($this->children as $child) { $thischanged = $child->update_dependency_id($table, $oldid, $newid); $changed = $changed || $thischanged; } return $changed; } /** * Returns a JSON object which corresponds to a tree. * * Intended for unit testing, as normally the JSON values are constructed * by JavaScript code. * * This function generates 'nested' (i.e. not root-level) trees. * * @param array $children Array of JSON objects from component children * @param string $op Operator (tree::OP_xx) * @return stdClass JSON object * @throws coding_exception If you get parameters wrong */ public static function get_nested_json(array $children, $op = self::OP_AND) { // Check $op and work out its type. switch($op) { case self::OP_AND: case self::OP_NOT_OR: case self::OP_OR: case self::OP_NOT_AND: break; default: throw new \coding_exception('Invalid $op'); } // Do simple tree. $result = new \stdClass(); $result->op = $op; $result->c = $children; return $result; } /** * Returns a JSON object which corresponds to a tree at root level. * * Intended for unit testing, as normally the JSON values are constructed * by JavaScript code. * * The $show parameter can be a boolean for all OP_xx options. For OP_AND * and OP_NOT_OR where you have individual show options, you can specify * a boolean (same for all) or an array. * * @param array $children Array of JSON objects from component children * @param string $op Operator (tree::OP_xx) * @param bool|array $show Whether 'show' option is turned on (see above) * @return stdClass JSON object ready for encoding * @throws coding_exception If you get parameters wrong */ public static function get_root_json(array $children, $op = self::OP_AND, $show = true) { // Get the basic object. $result = self::get_nested_json($children, $op); // Check $op type. switch($op) { case self::OP_AND: case self::OP_NOT_OR: $multishow = true; break; case self::OP_OR: case self::OP_NOT_AND: $multishow = false; break; } // Add show options depending on operator. if ($multishow) { if (is_bool($show)) { $result->showc = array_pad(array(), count($result->c), $show); } else if (is_array($show)) { // The JSON will break if anything isn't an actual bool, so check. foreach ($show as $item) { if (!is_bool($item)) { throw new \coding_exception('$show array members must be bool'); } } // Check the size matches. if (count($show) != count($result->c)) { throw new \coding_exception('$show array size does not match $children'); } $result->showc = $show; } else { throw new \coding_exception('$show must be bool or array'); } } else { if (!is_bool($show)) { throw new \coding_exception('For this operator, $show must be bool'); } $result->show = $show; } return $result; } }