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 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.
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 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).
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').
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.