Moodle PHP Documentation 4.5
Moodle 4.5dev (Build: 20240606) (d3ae1391abe)
core_availability\info Class Reference

Base class for conditional availability information (for module or section). More...

Inheritance diagram for core_availability\info:
core_availability\info_module core_availability\info_section

Public Member Functions

 __construct ($course, $visible, $availability)
 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_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 ($availabilty)
 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)
 
bool $visible
 Visibility flag (eye icon)
 

Static Protected Attributes

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

Detailed Description

Base class for conditional availability information (for module or section).

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

Constructor & Destructor Documentation

◆ __construct()

core_availability\info::__construct ( $course,
$visible,
$availability )

Constructs with item details.

Parameters
stdClass$courseCourse object
int$visibleValue of visible flag (eye icon)
string$availabilityAvailability definition (JSON format) or null

Member Function Documentation

◆ add_legacy_availability_condition()

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

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$availabilityCurrent availability conditions
stdClass$recObject containing information from old table
bool$showTrue if 'show' option should be enabled
Return values
stringNew availability conditions

◆ add_legacy_availability_field_condition()

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

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$availabilityCurrent availability conditions
stdClass$recObject containing information from old table
bool$showTrue if 'show' option should be enabled
Return values
stringNew availability conditions

◆ add_legacy_condition()

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

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$availabilityCurrent availability conditions
string$conditionCondition text '{...}'
bool$showTrue if 'show' option should be enabled
Return values
stringNew availability conditions

◆ completion_value_used()

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

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$courseMoodle course object
int$cmidCourse-module id
Return values
boolTrue if this is used in a condition, false otherwise

◆ convert_legacy_fields()

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

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$recObject possibly containing legacy fields
bool$sectionTrue if this is a section
bool$modgroupmembersonlyignoredIgnored option, previously used
Return values
string|nullNew availability value or null if none

◆ decode_availability()

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

Decodes availability data from JSON format.

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).
Parameters
string$availabilityAvailability string in JSON format
boolean$laxIf true, throw exceptions only for invalid structure
Return values
treeAvailability tree
Exceptions
coding_exceptionIf data is not valid JSON format

◆ filter_user_list()

core_availability\info::filter_user_list ( array $users)

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$usersArray of userid => object
Return values
arrayFiltered version of input array

Reimplemented in core_availability\info_module.

◆ format_info()

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

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$inforenderableInfo string or renderable
int | stdClass$courseorid
Return values
stringCorrectly formatted info string

◆ get_availability_tree()

core_availability\info::get_availability_tree ( )

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

Return values
treeAvailability tree

◆ get_context()

core_availability\info::get_context ( )
abstract

Gets context used for checking capabilities for this item.

Return values
contextContext for this item

Reimplemented in core_availability\info_module, and core_availability\info_section.

◆ get_course()

core_availability\info::get_course ( )

Obtains the course associated with this availability information.

Return values
stdClassMoodle course object

◆ get_full_information()

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

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$modinfoUsually leave as null for default
Return values
stringInformation string (for admin) about all restrictions on this item

◆ get_groups()

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

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$groupingidGrouping ID or 0 (default) for all groups
int$useridUser 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 ( )

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_modinfoModinfo
Exceptions
coding_exceptionIf called at incorrect times

◆ get_restore_date_offset()

static core_availability\info::get_restore_date_offset ( $restoreid)
static

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

Parameters
string$restoreidRestore identifier
Return values
intDate offset (0 if none)
Exceptions
coding_exceptionIf not in a restore (or not in that restore)

◆ get_restore_task()

static core_availability\info::get_restore_task ( $restoreid)
static

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

Parameters
string$restoreidRestore identifier
Return values
base_taskRestore task
Exceptions
coding_exceptionIf not in a restore (or not in that restore)

◆ get_thing_name()

core_availability\info::get_thing_name ( )
abstractprotected

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
stringName of item

Reimplemented in core_availability\info_module, and core_availability\info_section.

◆ get_user_list_sql()

core_availability\info::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.

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$onlyactiveTrue if including only active enrolments
Return values
arrayArray of SQL code (may be empty) and params

Reimplemented in core_availability\info_module.

◆ get_view_hidden_capability()

core_availability\info::get_view_hidden_capability ( )
abstractprotected

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

Return values
stringName of capability used to view hidden items of this type

Reimplemented in core_availability\info_module, and core_availability\info_section.

◆ is_available()

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

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$informationString describing restrictions in HTML format
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$useridIf set, specifies a different user ID to check availability for
course_modinfo$modinfoUsually leave as null for default. Specify when calling recursively from inside get_fast_modinfo()
Return values
boolTrue if this item is available to the user, false otherwise

◆ is_available_for_all()

core_availability\info::is_available_for_all ( )

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
boolTrue if activity is available for all

◆ set_in_database()

core_availability\info::set_in_database ( $availabilty)
abstractprotected

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

Parameters
string$availabiltyNew JSON value

Reimplemented in core_availability\info_module, and core_availability\info_section.

◆ update_after_restore()

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

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$restoreidRestore identifier
int$courseidTarget course id
base_logger$loggerLogger for any warnings
int$dateoffsetDate offset to be added to any dates (0 = none)
base_task$taskRestore task

◆ update_dependency_id()

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

Called on a single item.

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

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

◆ update_dependency_id_across_course()

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

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$courseoridCourse id or object
string$tableTable name e.g. 'course_modules'
int$oldidPrevious ID
int$newidNew ID
Return values
boolTrue if anything changed, otherwise false

◆ warn_about_invalid_availability()

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

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$eException that occurred

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