Moodle APIs 3.9
Moodle 3.9.13+ (Build: 20220325)
Public Member Functions | Static Public Member Functions | Public Attributes | Protected Member Functions | Static Protected Member Functions | Protected Attributes | Static Protected Attributes | List of all members
core_availability\tree Class Reference

Class that holds a tree of availability conditions. More...

Inheritance diagram for core_availability\tree:
core_availability\tree_node

Public Member Functions

 __construct ($structure, $lax=false, $root=true)
 Decodes availability structure. More...
 
 __toString ()
 Display a representation of this tree (used for debugging). More...
 
 check_available ($not, core_availability\info $info, $grabthelot, $userid)
 Determines whether this particular item is currently available according to the availability criteria. More...
 
 check_available ($not, info $info, $grabthelot, $userid)
 
 filter_user_list (array $users, $not, core_availability\info $info, capability_checker $checker)
 Tests this condition against a user list. More...
 
 filter_user_list (array $users, $not, info $info, capability_checker $checker)
 Tests against a user list. More...
 
 get_all_children ($classname)
 Recursively gets all children of a particular class (you can use a base class to get all conditions, or a specific class). More...
 
 get_full_information (info $info)
 Gets full information about this tree (including all children) as HTML for display to staff. More...
 
 get_logic_flags ($not)
 Converts the operator for the tree into two flags used for computing the result. More...
 
 get_result_information (info $info, result $result)
 Gets information about this tree corresponding to the given result object. More...
 
 get_user_list_sql ($not, core_availability\info $info, $onlyactive)
 Obtains SQL that returns a list of enrolled users that has been filtered by the conditions applied in the availability API, similar to calling get_enrolled_users and then filter_user_list. More...
 
 get_user_list_sql ($not, info $info, $onlyactive)
 
 include_after_restore ($restoreid, $courseid, base_logger $logger, $name, base_task $task)
 Checks whether this node should be included after restore or not. More...
 
 is_applied_to_user_lists ()
 Checks whether this condition applies to user lists. More...
 
 is_available_for_all ($not=false)
 Checks whether this condition is actually going to be available for all users under normal circumstances. More...
 
 is_empty ()
 Checks whether this tree is empty (contains no children). More...
 
 save ()
 Saves tree data back to a structure object. More...
 
 update_after_restore ($restoreid, $courseid, base_logger $logger, $name)
 Updates this node after restore, returning true if anything changed. More...
 
 update_dependency_id ($table, $oldid, $newid)
 Updates this node if it contains any references (dependencies) to the given table and id. More...
 

Static Public Member Functions

static get_nested_json (array $children, $op=self::OP_AND)
 Returns a JSON object which corresponds to a tree. More...
 
static get_root_json (array $children, $op=self::OP_AND, $show=true)
 Returns a JSON object which corresponds to a tree at root level. More...
 

Public Attributes

int const OP_AND = '&'
 Operator: AND.
 
int const OP_NOT_AND = '!&'
 Operator: NOT(AND)
 
int const OP_NOT_OR = '!|'
 Operator: NOT(OR)
 
int const OP_OR = '|'
 Operator: OR.
 

Protected Member Functions

 get_full_information_recursive ( $not, info $info, result $result=null, $root, $hidden=false)
 Gets information about this tree (including all or selected children) as HTML for display to staff or student. More...
 
 recursive_get_all_children ($classname, array &$result)
 Internal function that implements get_all_children efficiently. More...
 

Static Protected Member Functions

static unique_sql_parameter (array &$params, $value)
 Utility function for generating SQL parameters (because we can't use ? parameters because get_enrolled_sql has infected us with horrible named parameters). More...
 

Protected Attributes

tree_node[] $children
 Children in this branch (may be empty array if needed)
 
string $op
 Operator type (OP_xx constant)
 
bool $root
 True if this tree is at root level.
 
bool $show
 Single 'show information or hide completely' option for tree. More...
 
bool[] $showchildren
 Array of 'show information or hide completely' options for each child. More...
 

Static Protected Attributes

static int $uniquesqlparametercounter = 1
 Counter to be used in tree_node::unique_sql_parameter().
 

Detailed Description

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

License
http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later

Constructor & Destructor Documentation

◆ __construct()

core_availability\tree::__construct (   $structure,
  $lax = false,
  $root = true 
)

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 also
decode_availability
Parameters
stdClass$structureStructure (decoded from JSON)
boolean$laxIf true, throw exceptions only for invalid structure
boolean$rootIf true, this is the root tree
Return values
treeAvailability tree
Exceptions
coding_exceptionIf data is not valid structure

Member Function Documentation

◆ __toString()

core_availability\tree::__toString ( )

Display a representation of this tree (used for debugging).

Return values
stringText representation of tree

◆ check_available()

core_availability\tree_node::check_available (   $not,
core_availability\info  $info,
  $grabthelot,
  $userid 
)
abstractinherited

Determines whether this particular item is currently available according to the availability criteria.

  • This does not include the 'visible' setting (i.e. this might return true even if visible is false); visible is handled independently.
  • This does not take account of the viewhiddenactivities capability. That should apply later.

The $not option is potentially confusing. This option always indicates the 'real' value of NOT. For example, a condition inside a 'NOT AND' group will get this called with $not = true, but if you put another 'NOT OR' group inside the first group, then a condition inside that will be called with $not = false. We need to use the real values, rather than the more natural use of the current value at this point inside the tree, so that the information displayed to users makes sense.

Parameters
bool$notSet true if we are inverting the condition
core_availability::info$infoItem we're checking
bool$grabthelotPerformance hint: if true, caches information required for all course-modules, to make the front page and similar pages work more quickly (works only for current user)
int$useridUser ID to check availability for
Return values
resultAvailability check result

◆ filter_user_list() [1/2]

core_availability\tree_node::filter_user_list ( array  $users,
  $not,
core_availability\info  $info,
capability_checker  $checker 
)
inherited

Tests this condition against a user list.

Users who do not meet the condition will be removed from the list, unless they have the ability to view hidden activities/sections.

This function must be implemented if is_applied_to_user_lists returns true. Otherwise it will not be called.

The function must operate efficiently, e.g. by using a fixed number of database queries regardless of how many users are in the list.

Within this function, if you need to check capabilities, please use the provided checker which caches results where possible.

Conditions do not need to check the viewhiddenactivities or viewhiddensections capabilities. These are handled by core_availability::info::filter_user_list.

Parameters
array$usersArray of userid => object
bool$notTrue if this condition is applying in negative mode
core_availability::info$infoItem we're checking
capability_checker$checker
Return values
arrayFiltered version of input array
Exceptions
coding_exceptionIf called on a condition that doesn't apply to user lists

◆ filter_user_list() [2/2]

core_availability\tree::filter_user_list ( array  $users,
  $not,
info  $info,
capability_checker  $checker 
)

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.

Parameters
array$usersArray of userid => object
bool$notIf tree's parent indicates it's being checked negatively
info$infoInfo about current context
capability_checker$checkerCapability checker
Return values
arrayFiltered version of input array

◆ get_all_children()

core_availability\tree::get_all_children (   $classname)

Recursively gets all children of a particular class (you can use a base class to get all conditions, or a specific class).

Parameters
string$classnameFull class name e.g. core_availability::condition
Return values
arrayArray of nodes of that type (flattened, not a tree any more)

◆ get_full_information()

core_availability\tree::get_full_information ( info  $info)

Gets full information about this tree (including all children) as HTML for display to staff.

Parameters
info$infoInformation about location of condition tree
Exceptions
coding_exceptionIf you call on a non-root tree
Return values
stringHTML data (empty string if none)

◆ get_full_information_recursive()

core_availability\tree::get_full_information_recursive (   $not,
info  $info,
result  $result = null,
  $root,
  $hidden = false 
)
protected

Gets information about this tree (including all or selected children) as HTML for display to staff or student.

Parameters
bool$notTrue if there is a NOT in effect
info$infoInformation about location of condition tree
result$resultResult object if this is a student display, else null
bool$rootTrue if this is the root item
bool$hiddenStaff display; true if this tree has show=false (from parent)
Return values
string|renderableInformation to render

◆ get_logic_flags()

core_availability\tree::get_logic_flags (   $not)

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

Parameters
bool$notNot flag passed to this tree
Return values
arrayArray of the 2 flags ($innernot, $andoperator)

◆ get_nested_json()

static core_availability\tree::get_nested_json ( array  $children,
  $op = self::OP_AND 
)
static

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.

Parameters
array$childrenArray of JSON objects from component children
string$opOperator (tree::OP_xx)
Return values
stdClassJSON object
Exceptions
coding_exceptionIf you get parameters wrong

◆ get_result_information()

core_availability\tree::get_result_information ( info  $info,
result  $result 
)

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

Parameters
info$infoInformation about location of condition tree
result$resultResult object
Exceptions
coding_exceptionIf you call on a non-root tree
Return values
stringHTML data (empty string if none)

◆ get_root_json()

static core_availability\tree::get_root_json ( array  $children,
  $op = self::OP_AND,
  $show = true 
)
static

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.

Parameters
array$childrenArray of JSON objects from component children
string$opOperator (tree::OP_xx)
bool | array$showWhether 'show' option is turned on (see above)
Return values
stdClassJSON object ready for encoding
Exceptions
coding_exceptionIf you get parameters wrong

◆ get_user_list_sql()

core_availability\tree_node::get_user_list_sql (   $not,
core_availability\info  $info,
  $onlyactive 
)
inherited

Obtains SQL that returns a list of enrolled users that has been filtered by the conditions applied in the availability API, similar to calling get_enrolled_users and then filter_user_list.

As for filter_user_list, this ONLY filters out users with conditions that are marked as applying to user lists. For example, group conditions are included but date conditions are not included.

The returned SQL is a query that returns a list of user IDs. It does not include brackets, so you neeed to add these to make it into a subquery. You would normally use it in an SQL phrase like "WHERE u.id IN ($sql)".

The SQL will be complex and may be slow. It uses named parameters (sorry, I know they are annoying, but it was unavoidable here).

If there are no conditions, the returned result is array('', array()).

Conditions do not need to check the viewhiddenactivities or viewhiddensections capabilities. These are handled by core_availability::info::get_user_list_sql.

Parameters
bool$notTrue if this condition is applying in negative mode
core_availability::info$infoItem we're checking
bool$onlyactiveIf true, only returns active enrolments
Return values
arrayArray with two elements: SQL subquery and parameters array
Exceptions
coding_exceptionIf called on a condition that doesn't apply to user lists

◆ include_after_restore()

core_availability\tree_node::include_after_restore (   $restoreid,
  $courseid,
base_logger  $logger,
  $name,
base_task  $task 
)
inherited

Checks whether this node should be included after restore or not.

The node may be removed depending on restore settings, which you can get from the $task object.

By default nodes are still included after restore.

Parameters
string$restoreidRestore ID
int$courseidID of target course
base_logger$loggerLogger for any warnings
string$nameName of this item (for use in warning messages)
base_task$taskCurrent restore task
Return values
boolTrue if there was any change

Reimplemented in availability_group\condition, and availability_grouping\condition.

◆ is_applied_to_user_lists()

core_availability\tree::is_applied_to_user_lists ( )

Checks whether this condition applies to user lists.

The default is false (the condition is used to control access, but does not prevent the student from appearing in lists).

For example, group conditions apply to user lists: we do not want to include a student in a list of users if they are prohibited from accessing the activity because they don't belong to a relevant group. However, date conditions do not apply - we still want to show users in a list of people who might have submitted an assignment, even if they are no longer able to access the assignment in question because there is a date restriction.

The general idea is that conditions which are likely to be permanent (group membership, user profile) apply to user lists. Conditions which are likely to be temporary (date, grade requirement) do not.

Conditions which do apply to user lists must implement the filter_user_list function.

Return values
boolTrue if this condition applies to user lists

Reimplemented from core_availability\tree_node.

◆ is_available_for_all()

core_availability\tree::is_available_for_all (   $not = false)

Checks whether this condition is actually going to be available for all users under normal circumstances.

Normally, if there are any conditions, then it may be hidden. However in the case of date conditions there are some conditions which will definitely not result in it being hidden for anyone.

Parameters
bool$notSet true if we are inverting the condition
Return values
boolTrue if condition will return available for everyone

Reimplemented from core_availability\tree_node.

◆ is_empty()

core_availability\tree::is_empty ( )

Checks whether this tree is empty (contains no children).

Return values
booleanTrue if empty

◆ recursive_get_all_children()

core_availability\tree::recursive_get_all_children (   $classname,
array &  $result 
)
protected

Internal function that implements get_all_children efficiently.

Parameters
string$classnameFull class name e.g. core_availability::condition
array$resultOutput array of nodes

◆ save()

core_availability\tree::save ( )

Saves tree data back to a structure object.

Return values
stdClassStructure object (ready to be made into JSON format)

Reimplemented from core_availability\tree_node.

◆ unique_sql_parameter()

static core_availability\tree_node::unique_sql_parameter ( array &  $params,
  $value 
)
staticprotectedinherited

Utility function for generating SQL parameters (because we can't use ? parameters because get_enrolled_sql has infected us with horrible named parameters).

Parameters
array$paramsParams array (value will be added to this array)
string | int$valueValue
Return values
SQLcode for the parameter, e.g. ':pr1234'

◆ update_after_restore()

core_availability\tree::update_after_restore (   $restoreid,
  $courseid,
base_logger  $logger,
  $name 
)

Updates this node after restore, returning true if anything changed.

The default behaviour is simply to return false. If there is a problem with the update, $logger can be used to output a warning.

Note: If you need information about the date offset, call core_availability::info::get_restore_date_offset($restoreid). For information on the restoring task and its settings, call core_availability::info::get_restore_task($restoreid).

Parameters
string$restoreidRestore ID
int$courseidID of target course
base_logger$loggerLogger for any warnings
string$nameName of this item (for use in warning messages)
Return values
boolTrue if there was any change

Reimplemented from core_availability\tree_node.

◆ update_dependency_id()

core_availability\tree::update_dependency_id (   $table,
  $oldid,
  $newid 
)

Updates this node if it contains any references (dependencies) to the given table and id.

Parameters
string$tableTable name e.g. 'course_modules'
int$oldidPrevious ID
int$newidNew ID
Return values
boolTrue if it changed, otherwise false

Reimplemented from core_availability\tree_node.

Member Data Documentation

◆ $show

bool core_availability\tree::$show
protected

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.

◆ $showchildren

bool [] core_availability\tree::$showchildren
protected

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.


The documentation for this class was generated from the following file: