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

Class handles conditional availability information for an activity. More...

Inheritance diagram for core_availability\info_module:
core_availability\info

Public Member Functions

 __construct (\cm_info $cm)
 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_course_module ()
 Gets the course-module object.
 
 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=true)
 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 is_user_visible ($cmorid, $userid=0, $checkcourse=true)
 Checks if an activity is visible to the given user.
 
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.
 
cm_info $cm
 Activity.
 
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

Class handles conditional availability information for an activity.

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

Constructor & Destructor Documentation

◆ __construct()

core_availability\info_module::__construct ( \cm_info $cm)

Constructs with item details.

Parameters
cm_info$cmCourse-module 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$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 )
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$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 )
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$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 )
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$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 )
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$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 )
protectedinherited

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_module::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.

When called on a module, this test DOES also include restrictions on the section (if any).

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

◆ 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$inforenderableInfo string or renderable
int | stdClass$courseorid
Return values
stringCorrectly 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
treeAvailability tree

◆ get_context()

core_availability\info_module::get_context ( )

Gets context used for checking capabilities for this item.

Return values
contextContext 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
stdClassMoodle course object

◆ get_course_module()

core_availability\info_module::get_course_module ( )

Gets the course-module object.

Intended for use by conditions.

Return values
cm_infoCourse module

◆ 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$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 )
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$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 ( )
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_modinfoModinfo
Exceptions
coding_exceptionIf 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$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)
staticinherited

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

Reimplemented from core_availability\info.

◆ get_user_list_sql()

core_availability\info_module::get_user_list_sql ( $onlyactive = true)

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

◆ get_view_hidden_capability()

core_availability\info_module::get_view_hidden_capability ( )
protected

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

◆ is_user_visible()

static core_availability\info_module::is_user_visible ( $cmorid,
$userid = 0,
$checkcourse = true )
static

Checks if an activity is visible to the given user.

Unlike other checks in the availability system, this check includes the $cm->visible flag. It is equivalent to $cm->uservisible.

If you have already checked (or do not care whether) the user has access to the course, you can set $checkcourse to false to save it checking course access.

When checking for the current user, you should generally not call this function. Instead, use get_fast_modinfo to get a cm_info object, then simply check the $cm->uservisible flag. This function is intended to obtain that information for a separate course-module object that wasn't loaded with get_fast_modinfo, or for a different user.

This function has a performance cost unless the availability system is disabled, and you supply a $cm object with necessary fields, and you don't check course access.

Parameters
int | stdClass | cm_info$cmoridObject or id representing activity
int$useridUser id (0 = current user)
bool$checkcourseIf true, checks whether the user has course access
Return values
boolTrue if the activity is visible to the specified user
Exceptions
moodle_exceptionIf the cmid doesn't exist

◆ set_in_database()

core_availability\info_module::set_in_database ( $availabilty)
protected

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

Parameters
string$availabiltyNew 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$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 )
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$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 )
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$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)
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$eException that occurred

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