Class handles conditional availability information for a section. More...

Inheritance diagram for core_availability\info_section:

Public Member Functions
	__construct (\section_info $section)
	Constructs with item details.

	filter_user_list (array $users)
	Tests against a user list.

	get_availability_tree ()
	Gets the availability tree, decoding it if not already done.

	get_context ()
	Gets context used for checking capabilities for this item.

	get_course ()
	Obtains the course associated with this availability information.

	get_full_information (\course_modinfo $modinfo=null)
	Obtains a string describing all availability restrictions (even if they do not apply any more).

	get_groups (int $groupingid=0, int $userid=0)
	Returns groups that the given user belongs to on the course.

	get_modinfo ()
	Obtains the modinfo associated with this availability information.

	get_section ()
	Gets the section object.

	get_user_list_sql ($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.

	is_available (&$information, $grabthelot=false, $userid=0, course_modinfo $modinfo=null)
	Determines whether this particular item is currently available according to the availability criteria.

	is_available_for_all ()
	Checks whether this activity is going to be available for all users.

	update_after_restore ($restoreid, $courseid, base_logger $logger, $dateoffset, base_task $task)
	Called during restore (near end of restore).

Static Public Member Functions
static	add_legacy_availability_condition ($availability, $rec, $show)
	Adds a condition from the legacy availability condition.

static	add_legacy_availability_field_condition ($availability, $rec, $show)
	Adds a condition from the legacy availability field condition.

static	completion_value_used ($course, $cmid)
	Used in course/lib.php because we need to disable the completion tickbox JS (using the non-JS version instead, which causes a page reload) if a completion tickbox value may affect a conditional activity.

static	convert_legacy_fields ($rec, $section, $modgroupmembersonlyignored=false)
	Converts legacy data from fields (if provided) into the new availability syntax.

static	format_info ($inforenderable, $courseorid)
	Formats the $cm->availableinfo string for display.

static	get_restore_date_offset ($restoreid)
	Gets the date offset (amount by which any date values should be adjusted) for the current restore.

static	get_restore_task ($restoreid)
	Gets the restore task (specifically, the task that calls the update_after_restore method) for the current restore.

static	update_dependency_id_across_course ( $courseorid, $table, $oldid, $newid)
	In rare cases the system may want to change all references to one ID (e.g.

Protected Member Functions
	decode_availability ($availability, $lax)
	Decodes availability data from JSON format.

	get_thing_name ()
	Obtains the name of the item (cm_info or section_info, at present) that this is controlling availability of.

	get_view_hidden_capability ()
	Gets the capability used to view hidden activities/sections (as appropriate).

	set_in_database ($availability)
	Stores an updated availability tree JSON structure into the relevant database table.

	update_dependency_id ($table, $oldid, $newid)
	Called on a single item.

	warn_about_invalid_availability (\coding_exception $e)
	In some places we catch coding_exception because if a bug happens, it would be fatal for the course page GUI; instead we just show a developer debug message.

Static Protected Member Functions
static	add_legacy_condition ($availability, $condition, $show)
	Adds a condition to an AND group.

Protected Attributes
string	$availability
	Availability data as JSON string.

tree	$availabilitytree
	Availability configuration, decoded from JSON; null if unset.

stdClass	$course
	Course.

array	$groups = []
	The groups each user belongs to.

course_modinfo	$modinfo = null
	Modinfo (available only during some functions)

section_info	$section
	Section.

bool	$visible
	Visibility flag (eye icon)

Static Protected Attributes
static array null	$restoreinfo = null
	Array of information about current restore if any.

Detailed Description

Class handles conditional availability information for a section.

Copyright: 2014 The Open University

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

Constructor & Destructor Documentation

◆ __construct()

core_availability\info_section::__construct ( \section_info $section )

Constructs with item details.

Parameters

section_info $section Section object

Member Function Documentation

◆ add_legacy_availability_condition()

static core_availability\info::add_legacy_availability_condition	(	$availability,
		$rec,
		$show )

staticinherited

Adds a condition from the legacy availability condition.

(For use during restore only.)

This function assumes that the activity either has no conditions, or that it has an AND tree with one or more conditions.

Parameters

string \| null	$availability	Current availability conditions
stdClass	$rec	Object containing information from old table
bool	$show	True if 'show' option should be enabled

Return values

string New availability conditions

◆ add_legacy_availability_field_condition()

static core_availability\info::add_legacy_availability_field_condition	(	$availability,
		$rec,
		$show )

staticinherited

Adds a condition from the legacy availability field condition.

(For use during restore only.)

This function assumes that the activity either has no conditions, or that it has an AND tree with one or more conditions.

Parameters

string \| null	$availability	Current availability conditions
stdClass	$rec	Object containing information from old table
bool	$show	True if 'show' option should be enabled

Return values

string New availability conditions

◆ add_legacy_condition()

static core_availability\info::add_legacy_condition	(	$availability,
		$condition,
		$show )

staticprotectedinherited

Adds a condition to an AND group.

(For use during restore only.)

This function assumes that the activity either has no conditions, or that it has only conditions added by this function.

Parameters

string \| null	$availability	Current availability conditions
string	$condition	Condition text '{...}'
bool	$show	True if 'show' option should be enabled

Return values

string New availability conditions

◆ completion_value_used()

static core_availability\info::completion_value_used	(		$course,
			$cmid )

staticinherited

Used in course/lib.php because we need to disable the completion tickbox JS (using the non-JS version instead, which causes a page reload) if a completion tickbox value may affect a conditional activity.

Parameters

stdClass	$course	Moodle course object
int	$cmid	Course-module id

Return values

bool	True if this is used in a condition, false otherwise

◆ convert_legacy_fields()

static core_availability\info::convert_legacy_fields	(	$rec,
		$section,
		$modgroupmembersonlyignored = false )

staticinherited

Converts legacy data from fields (if provided) into the new availability syntax.

Supported fields: availablefrom, availableuntil, showavailability (and groupingid for sections).

It also supports the groupmembersonly field for modules. This part was optional in 2.7 but now always runs (because groupmembersonly has been removed).

Parameters

stdClass	$rec	Object possibly containing legacy fields
bool	$section	True if this is a section
bool	$modgroupmembersonlyignored	Ignored option, previously used

Return values

string|null New availability value or null if none

◆ decode_availability()

core_availability\info::decode_availability	(		$availability,
			$lax )

protectedinherited

Decodes availability data from JSON format.

This function also validates the retrieved data as follows:

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

Parameters

string	$availability	Availability string in JSON format
boolean	$lax	If true, throw exceptions only for invalid structure

Return values

tree	Availability tree

Exceptions

coding_exception If data is not valid JSON format

◆ filter_user_list()

core_availability\info::filter_user_list ( array $users )

inherited

Tests against a user list.

Users who cannot access the activity due to availability restrictions will be removed from the list.

Note this only includes availability restrictions (those handled within this API) and not other ways of restricting access.

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 $users Array of userid => object

Return values

array Filtered version of input array

Reimplemented in core_availability\info_module.

◆ format_info()

static core_availability\info::format_info	(		$inforenderable,
			$courseorid )

staticinherited

Formats the $cm->availableinfo string for display.

This includes filling in the names of any course-modules that might be mentioned. Should be called immediately prior to display, or at least somewhere that we can guarantee does not happen from within building the modinfo object.

Parameters

renderable \| string	$inforenderable	Info string or renderable
int \| stdClass	$courseorid

Return values

string Correctly formatted info string

◆ get_availability_tree()

core_availability\info::get_availability_tree ( )

inherited

Gets the availability tree, decoding it if not already done.

Return values

tree	Availability tree

◆ get_context()

core_availability\info_section::get_context ( )

Gets context used for checking capabilities for this item.

Return values

context Context for this item

Reimplemented from core_availability\info.

◆ get_course()

core_availability\info::get_course ( )

inherited

Obtains the course associated with this availability information.

Return values

stdClass Moodle course object

◆ get_full_information()

core_availability\info::get_full_information ( \course_modinfo $modinfo = null )

inherited

Obtains a string describing all availability restrictions (even if they do not apply any more).

Used to display information for staff editing the website.

The modinfo parameter must be specified when it is called from inside get_fast_modinfo, to avoid infinite recursion.

This function displays debugging() messages if the availability information is invalid.

Parameters

course_modinfo $modinfo Usually leave as null for default

Return values

string Information string (for admin) about all restrictions on this item

◆ get_groups()

core_availability\info::get_groups	(	int	$groupingid = 0,
		int	$userid = 0 )

inherited

Returns groups that the given user belongs to on the course.

Note: If not already available, this may make a database query.

This will include groups the user is not allowed to see themselves, so check visibility before displaying groups to the user.

Parameters

int	$groupingid	Grouping ID or 0 (default) for all groups
int	$userid	User ID or 0 (default) for current user

Return values

int[] Array of int (group id) => int (same group id again); empty array if none

◆ get_modinfo()

core_availability\info::get_modinfo ( )

inherited

Obtains the modinfo associated with this availability information.

Note: This field is available ONLY for use by conditions when calculating availability or information.

Return values

course_modinfo Modinfo

Exceptions

coding_exception If called at incorrect times

◆ get_restore_date_offset()

static core_availability\info::get_restore_date_offset ( $restoreid )

staticinherited

Gets the date offset (amount by which any date values should be adjusted) for the current restore.

Parameters

string $restoreid Restore identifier

Return values

int	Date offset (0 if none)

Exceptions

coding_exception If not in a restore (or not in that restore)

◆ get_restore_task()

static core_availability\info::get_restore_task ( $restoreid )

staticinherited

Gets the restore task (specifically, the task that calls the update_after_restore method) for the current restore.

Parameters

string $restoreid Restore identifier

Return values

base_task Restore task

Exceptions

coding_exception If not in a restore (or not in that restore)

◆ get_section()

core_availability\info_section::get_section ( )

Gets the section object.

Intended for use by conditions.

Return values

section_info Section

◆ get_thing_name()

core_availability\info_section::get_thing_name ( )

protected

Obtains the name of the item (cm_info or section_info, at present) that this is controlling availability of.

Name should be formatted ready for on-screen display.

Return values

string Name of item

Reimplemented from core_availability\info.

◆ get_user_list_sql()

core_availability\info::get_user_list_sql ( $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 function returns an array with '' and an empty array, if there are no restrictions on users from these conditions.

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

Parameters

bool $onlyactive True if including only active enrolments

Return values

array Array of SQL code (may be empty) and params

Reimplemented in core_availability\info_module.

◆ get_view_hidden_capability()

core_availability\info_section::get_view_hidden_capability ( )

protected

Gets the capability used to view hidden activities/sections (as appropriate).

Return values

string Name of capability used to view hidden items of this type

Reimplemented from core_availability\info.

◆ is_available()

core_availability\info::is_available	(	&	$information,
			$grabthelot = false,
			$userid = 0,
		course_modinfo	$modinfo = null )

inherited

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.

Depending on options selected, a description of the restrictions which mean the student can't view it (in HTML format) may be stored in $information. If there is nothing in $information and this function returns false, then the activity should not be displayed at all.

This function displays debugging() messages if the availability information is invalid.

Parameters

string	$information	String describing restrictions in HTML format
bool	$grabthelot	Performance 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	$userid	If set, specifies a different user ID to check availability for
course_modinfo	$modinfo	Usually leave as null for default. Specify when calling recursively from inside get_fast_modinfo()

Return values

bool	True if this item is available to the user, false otherwise

◆ is_available_for_all()

core_availability\info::is_available_for_all ( )

inherited

Checks whether this activity is going to be available for all users.

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

Return values

bool	True if activity is available for all

◆ set_in_database()

core_availability\info_section::set_in_database ( $availabilty )

protected

Stores an updated availability tree JSON structure into the relevant database table.

Parameters

string $availabilty New JSON value

Reimplemented from core_availability\info.

◆ update_after_restore()

core_availability\info::update_after_restore	(		$restoreid,
			$courseid,
		base_logger	$logger,
			$dateoffset,
		base_task	$task )

inherited

Called during restore (near end of restore).

Updates any necessary ids and writes the updated tree to the database. May output warnings if necessary (e.g. if a course-module cannot be found after restore).

Parameters

string	$restoreid	Restore identifier
int	$courseid	Target course id
base_logger	$logger	Logger for any warnings
int	$dateoffset	Date offset to be added to any dates (0 = none)
base_task	$task	Restore task

◆ update_dependency_id()

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

protectedinherited

Called on a single item.

If necessary, updates availability data where it has a dependency on an item with a particular id.

Parameters

string	$table	Table name e.g. 'course_modules'
int	$oldid	Previous ID
int	$newid	New ID

Return values

bool	True if it changed, otherwise false

◆ update_dependency_id_across_course()

static core_availability\info::update_dependency_id_across_course	(	$courseorid,
		$table,
		$oldid,
		$newid )

staticinherited

In rare cases the system may want to change all references to one ID (e.g.

one course-module ID) to another one, within a course. This function does that for the conditional availability data for all modules and sections on the course.

Parameters

int \| stdClass	$courseorid	Course id or object
string	$table	Table name e.g. 'course_modules'
int	$oldid	Previous ID
int	$newid	New ID

Return values

bool	True if anything changed, otherwise false

◆ warn_about_invalid_availability()

core_availability\info::warn_about_invalid_availability ( \coding_exception $e )

protectedinherited

In some places we catch coding_exception because if a bug happens, it would be fatal for the course page GUI; instead we just show a developer debug message.

Parameters

coding_exception $e Exception that occurred

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

availability/classes/info_section.php

Public Member Functions

Static Public Member Functions

Protected Member Functions

Static Protected Member Functions

Protected Attributes

Static Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ __construct()

Member Function Documentation

◆ add_legacy_availability_condition()

◆ add_legacy_availability_field_condition()

◆ add_legacy_condition()

◆ completion_value_used()

◆ convert_legacy_fields()

◆ decode_availability()

◆ filter_user_list()

◆ format_info()

◆ get_availability_tree()

◆ get_context()

◆ get_course()

◆ get_full_information()

◆ get_groups()

◆ get_modinfo()

◆ get_restore_date_offset()

◆ get_restore_task()

◆ get_section()

◆ get_thing_name()

◆ get_user_list_sql()

◆ get_view_hidden_capability()

◆ is_available()

◆ is_available_for_all()

◆ set_in_database()

◆ update_after_restore()

◆ update_dependency_id()

◆ update_dependency_id_across_course()

◆ warn_about_invalid_availability()