Enrolment API

Important: 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!

Since Moodle 2.0 there is a new concept of user enrolments, they are fully independent from the roles and capabilities. Capabilities are very often used in combination with enrolment status.

What is enrolment?

Enrolled users may fully participate in a course. Active user enrolment allows user to enter course. Only enrolled users may be group members. Grades are stored only for enrolled users.

Unenrolment

Unenrolment is irreversible operation that purges user participation information. Full unenrolment is suitable only if you do not need to preserve all course participation information including user grades.

Enrolment status

Instead of full unenrolment it is usually better to only suspend user enrolment. If there are other ways to enter the course (such guest access) it is recommended to remove user roles at the same time.

Activity participation

Activity developers decide the enrolment related behaviour of module.

There are some general guidelines:

• Only users with active enrolments should receive notifications.
• Activities should display enrolled users with some capability as participants.
• By default only users with active enrolments should be displayed in reports.
• There should be option to display all enrolled users including suspended enrolments.
• For performance reasons invisible participation data should be purged on unenrolment.
• Contributions visible by other participants should be kept after unenrolment (such as forum posts).

API functions

enrol_send_welcome_email_options()

Some enrol methods has the support for sending welcome emails to users. This method returns a list of all possible options for sending welcome email when the user enrol in a course and each option has a respective constant defined on enrollib.php:

define('ENROL_DO_NOT_SEND_EMAIL', 0); // Do not send the welcome email.
define('ENROL_SEND_EMAIL_FROM_COURSE_CONTACT', 1); // Send welcome email from course contact.
define('ENROL_SEND_EMAIL_FROM_KEY_HOLDER', 2); // Send welcome email from course key holder.
define('ENROL_SEND_EMAIL_FROM_NOREPLY', 3); // Send welcome email from no reply.

The main idea is to make send email options consistent across enrolment methods that support this feature. See an example below:

$sendoptions = enrol_send_welcome_email_options();
print_object($sendoptions);

The example above will output:

Array 
(
       [1] => 'No'
       [2] => 'From the course contact'
       [3] => 'From the key holder'
       [4] => 'From the no-reply address'
)

is_enrolled()

Is user participating in the course? Returns true for students and teachers, false for administrators and other managers. User enrolments can be either active or suspended, suspended users can not enter the course (unless there is some kind of guest access allowed) or have moodle/course:view capability and are usually hidden in the UI.

function is_enrolled(context $context, $user = null, $withcapability = '', $onlyactive = false)

Good example is choice module where we have one slot for each participant, people that are not enrolled are not allowed to vote

is_enrolled($context, $USER, 'mod/choice:choose')

. Another example is assignment where users need to be enrolled and have capability to submit assignemnts

is_enrolled($this->context, $USER, 'mod/assignment:submit')

.

get_enrolled_users()

Sometimes you need to know the list of users that can participate in some activity.

function get_enrolled_sql(context $context, $withcapability = '', $groupid = 0, $onlyactive = false)
function get_enrolled_users(context $context, $withcapability = '', $groupid = 0, $userfields = 'u.*', $orderby = '', $limitfrom = 0, $limitnum = 0)
function count_enrolled_users(context $context, $withcapability = '', $groupid = 0)

For example you want to know who is able to summit assignment right now:

$submissioncandidates = get_enrolled_users($modcontext, 'mod/assignment:submit');

The assignment module needs to hold data for all users that are enrolled including the users with suspended enrolments and without any roles. Module developers may decide to purge all user data when user is fully unenrolled.

SQL select from get_enrolled_sql() is often used for performance reasons - you can use it in joins to get specific information for enrolled users only.

See also

• Enrolment plugins
• Enrolment usage overview
• New enrolments in 2.0