Your IP : 18.117.254.202
<?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|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, $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 = !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;
}
}