Search moodle.org's
Developer Documentation

See Release Notes
Long Term Support Release

  • Bug fixes for general core bugs in 4.1.x will end 13 November 2023 (12 months).
  • Bug fixes for security issues in 4.1.x will end 10 November 2025 (36 months).
  • PHP version: minimum PHP 7.4.0 Note: minimum PHP version has increased since Moodle 4.0. PHP 8.0.x is supported too.

Differences Between: [Versions 310 and 401] [Versions 311 and 401] [Versions 39 and 401]

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

Copyright: 2014 The Open University
License: http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
File Size: 799 lines (32 kb)
Included or required:0 times
Referenced: 0 times
Includes or requires: 0 files

Defines 1 class


Class: info  - X-Ref

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

__construct($course, $visible, $availability)   X-Ref
Constructs with item details.

param: \stdClass $course Course object
param: int $visible Value of visible flag (eye icon)
param: string $availability Availability definition (JSON format) or null

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

return: \stdClass Moodle course object

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

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

return: \course_modinfo Modinfo

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

return: tree Availability tree

decode_availability($availability, $lax)   X-Ref
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).

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

is_available(&$information, $grabthelot = false, $userid = 0,\course_modinfo $modinfo = null)   X-Ref
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.

param: string $information String describing restrictions in HTML format
param: bool $grabthelot Performance hint: if true, caches information
param: int $userid If set, specifies a different user ID to check availability for
param: \course_modinfo $modinfo Usually leave as null for default. Specify when
return: bool True if this item is available to the user, false otherwise

is_available_for_all()   X-Ref
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: bool True if activity is available for all

get_full_information(\course_modinfo $modinfo = null)   X-Ref
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.

param: \course_modinfo $modinfo Usually leave as null for default
return: string Information string (for admin) about all restrictions on

warn_about_invalid_availability(\coding_exception $e)   X-Ref
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.

param: \coding_exception $e Exception that occurred

update_after_restore($restoreid, $courseid, \base_logger $logger,$dateoffset, \base_task $task)   X-Ref
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).

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

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

param: string $restoreid Restore identifier
return: int Date offset (0 if none)

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

param: string $restoreid Restore identifier
return: \base_task Restore task

update_dependency_id_across_course($courseorid, $table, $oldid, $newid)   X-Ref
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.

param: int|\stdClass $courseorid Course id or object
param: string $table Table name e.g. 'course_modules'
param: int $oldid Previous ID
param: int $newid New ID
return: bool True if anything changed, otherwise false

update_dependency_id($table, $oldid, $newid)   X-Ref
Called on a single item. If necessary, updates availability data where
it has a dependency on an item with a particular id.

param: string $table Table name e.g. 'course_modules'
param: int $oldid Previous ID
param: int $newid New ID
return: bool True if it changed, otherwise false

convert_legacy_fields($rec, $section, $modgroupmembersonlyignored = false)   X-Ref
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).

param: \stdClass $rec Object possibly containing legacy fields
param: bool $section True if this is a section
param: bool $modgroupmembersonlyignored Ignored option, previously used
return: string|null New availability value or null if none

add_legacy_availability_condition($availability, $rec, $show)   X-Ref
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.

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

add_legacy_availability_field_condition($availability, $rec, $show)   X-Ref
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.

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

add_legacy_condition($availability, $condition, $show)   X-Ref
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.

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

filter_user_list(array $users)   X-Ref
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.

param: array $users Array of userid => object
return: array Filtered version of input array

get_user_list_sql($onlyactive)   X-Ref
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).

param: bool $onlyactive True if including only active enrolments
return: array Array of SQL code (may be empty) and params

format_info($inforenderable, $courseorid)   X-Ref
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.

param: \renderable|string $inforenderable Info string or renderable
param: int|\stdClass $courseorid
return: string Correctly formatted info string

completion_value_used($course, $cmid)   X-Ref
No description