If you want to create a new page for developers, you should create it on the Moodle Developer Resource site.

Availability API

From MoodleDocs

This content of this page has been updated and migrated to the new Moodle Developer Resources. The information contained on the page should no longer be seen up-to-date.

Why not view this page on the new site and help us to migrate more content to the new site!

Availability API
Project state Integration review
Tracker issue MDL-44070
Assignee sam marshall (OU)

Moodle 2.7

The availability API controls access to activities and sections. For example, a teacher could restrict access so that an activity cannot be accessed until a certain date, or so that a section cannot be accessed unless users have a certain grade in a quiz.

The conditional availability system defaults to off; users enable it from the advanced features page in settings. You can still call the API functions even if the system is turned off.

Change from Moodle 2.6 and below

This replaces the previous API (2.6 and below) in conditionlib.php. The main differences in the new code are:

  • Supports plugins for different types of condition.
  • Allows conditions to be combined in Boolean logic tree structures.

If you have code using conditionlib.php, you'll see deprecation warnings advising you how to modify your code.

Using the API

In most cases you do not need to use the API directly because the system handles it. For example, if you are writing a module:

  • The system will automatically prevent users accessing your module if they do not meet an availability condition (unless they have the ability to access hidden activities). This happens when you call require_login and pass your module information.
  • Your module's form will automatically have controls for setting availability restriction, as part of the standard form controls.

However for special cases you might need to use API features. There are two main uses, shown below.

Check if the current user can access an activity

To check if the current user can access an activity (supposing you have a $course and $cmid):

$modinfo = get_fast_modinfo($course);
$cm = $modinfo->get_cm($cmid);
if ($cm->uservisible) {
    // User can access the activity.
} else if ($cm->availableinfo) {
    // User cannot access the activity, but on the course page they will
    // see a link to it, greyed-out, with information (HTML format) from
    // $cm->availableinfo about why they can't access it.
} else {
    // User cannot access the activity and they will not see it at all.

There are similar properties for sections.

  • You do not need to check the section properties when checking access for an activity, as the system takes these into account. (If the user cannot access a section, then $cm->uservisible will return false for all activities within the section.)
  • You do not need to additionally check $cm->visible; $cm->uservisible already takes this into account too.

These properties are worked out for the current user. You can also obtain them for a different user by passing a user ID to get_fast_modinfo, although be aware that doing this repeatedly for different users will be slow.

Display a list of users who may be able to access the current activity

Sometimes you need to display a list of users who may be able to access the current activity.

While you could use the above approach for each user, this would be slow and also is generally not what you require. For example, if you have an activity such as an assignment which is set to be available to students until a certain date, and if you want to display a list of potential users within that activity, you probably don't want to make the list blank immediately the date occurs.

The system divides availability conditions into two types:

  • Applied to user lists. (Group, grouping, profile condition.)
  • Not applied to user lists. (Date, completion, grade.)

In general, the conditions which we expect are likely to change over time (such as dates) or as a result of user actions (such as grades) are not applied to user lists.

If you have a list of users (for example you could obtain this using one of the 'get enrolled users' functions), you can filter it to include only those users who are allowed to see an activity with this code:

$info = new \core_availability\info_module($cm);
$filtered = $info->filter_user_list($users);
  • This does not currently include the $cm->visible setting, nor does it take into account the viewhiddenactivities setting.

Implementing new availability conditions

It is easy to write new availability conditions. See Availability conditions.

Using availability conditions in other areas

The availability API is provided for activities (course-modules) and sections. It is also possible to use it in other areas such as within a module. See Availability API for items within a module.

Programmatically setting availability conditions

If you want to programmatically set up an availability condition (e.g. set an activity to only be available to users of a particular group, the best code to do that is:

$restriction = \core_availability\tree::get_root_json(
$DB->set_field('course_modules', 'availability',
        json_encode($restriction), ['id' => $cmid]);
rebuild_course_cache($course->id, true);