Note:

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

Enrolment plugins: Difference between revisions

From MoodleDocs
m (Protected "Enrolment plugins": Developer Docs Migration ([Edit=Allow only administrators] (indefinite)))
 
(7 intermediate revisions by 3 users not shown)
Line 1: Line 1:
{{Template:Migrated|newDocId=/docs/apis/plugintypes/enrol/}}
Since Moodle 2.0 all enrolment plugins must extend [https://github.com/moodle/moodle/blob/master/lib/enrollib.php enrol_plugin] base class which is defined at the end of lib/enrollib.php. This base class contains all standard methods together with developer documentation.
Since Moodle 2.0 all enrolment plugins must extend [https://github.com/moodle/moodle/blob/master/lib/enrollib.php enrol_plugin] base class which is defined at the end of lib/enrollib.php. This base class contains all standard methods together with developer documentation.


Course enrolment information is stored in tables <code>enrol</code> and <code>user_enrolments</code> and optionally other custom database tables defined by individual enrolment plugins. Each plugin has complete total over own instance record and user enrolments, by defaults user enrolments are protected and can not be modified manually by teachers.
Course enrolment information is stored in tables <syntaxhighlight lang="php">enrol</syntaxhighlight> and <syntaxhighlight lang="php">user_enrolments</syntaxhighlight> and optionally other custom database tables defined by individual enrolment plugins. Each plugin has complete total over own instance record and user enrolments, by defaults user enrolments are protected and can not be modified manually by teachers.


Enrolment gives users following privileges:
Enrolment gives users following privileges:
Line 18: Line 19:
Fully automatic plugins are configured at the system level, they synchronise user enrolments with information stored in external systems (ex.: enrol_ldap, enrol_database and enrol_category). Some non-interactive plugins may require configuration of enrolment instances (ex.: enrol_cohort and enrol_meta).
Fully automatic plugins are configured at the system level, they synchronise user enrolments with information stored in external systems (ex.: enrol_ldap, enrol_database and enrol_category). Some non-interactive plugins may require configuration of enrolment instances (ex.: enrol_cohort and enrol_meta).


Interactive enrolment plugins require user interaction during enrolment (ex.: enrol_self and enrol_paypal). These plugins need to override <code>enrol_plugin::show_enrolme_link()</code>, <code>enrol_plugin::enrol_page_hook()</code> and to implement adding and editing of enrol instance.
Interactive enrolment plugins require user interaction during enrolment (ex.: enrol_self and enrol_paypal). These plugins need to override <syntaxhighlight lang="php">enrol_plugin::show_enrolme_link()</syntaxhighlight>, <syntaxhighlight lang="php">enrol_plugin::enrol_page_hook()</syntaxhighlight> and to implement adding and editing of enrol instance.


==Enrolment expiration and suspending==
==Enrolment expiration and suspending==
User has active enrolment if all following conditions are met:
User has active enrolment if all following conditions are met:
* user has record in <code>user_enrolments</code> table,
* user has record in <syntaxhighlight lang="php">user_enrolments</syntaxhighlight> table,
* user enrolment already started,
* user enrolment already started,
* user enrolment is not past timeend,
* user enrolment is not past timeend,
* user enrolment has active status,
* user enrolment has active status,
* enrol instance has active status in <code>enrol</code> table,
* enrol instance has active status in <syntaxhighlight lang="php">enrol</syntaxhighlight> table,
* enrol plugin is enabled.
* enrol plugin is enabled.


Most synchronisation plugins include a setting called ''External unenrol action''. It is used to decide what happens when previously enrolled user is not supposed to be enrolled any more. Synchronisation is usually executed from cli/sync.php or as part of standard cron.
Most synchronisation plugins include a setting called ''External unenrol action''. It is used to decide what happens when previously enrolled user is not supposed to be enrolled any more. Synchronisation is usually executed from cli/sync.php or as part of standard cron.


Time based expiration was implemented in Moodle 2.5. Plugins that set timeend in user_enrolments table may want to specify expiration action and optional expiration notification, see <code>enrol_plugin::process_expirations()</code> and <code>enrol_plugin::send_expiry_notifications()</code>.
Time based expiration was implemented in Moodle 2.5. Plugins that set timeend in user_enrolments table may want to specify expiration action and optional expiration notification, see <syntaxhighlight lang="php">enrol_plugin::process_expirations()</syntaxhighlight> and <syntaxhighlight lang="php">enrol_plugin::send_expiry_notifications()</syntaxhighlight>.


==Manual enrolment modifications==
==Manual enrolment modifications==


The standard user enrolment UI does not use the following methods directly, so developers need to describe all possible UI enrolments actions via <code>enrol_plugin::get_user_enrolment_actions()</code>. It is very important to obey these restrictions in all externallib methods!
The standard user enrolment UI does not use the following methods directly, so developers need to describe all possible UI enrolments actions via <syntaxhighlight lang="php">enrol_plugin::get_user_enrolment_actions()</syntaxhighlight>. It is very important to obey these restrictions in all externallib methods!


The following methods describe the allowed modifications for each enrolment instance:
The following methods describe the allowed modifications for each enrolment instance:


* <code>enrol_plugin::roles_protected()</code> - True means that protected roles (nonempty component+itemid) cannot be modified by any other plugin. Return false if you want to allow users to remove all roles assigned by this plugin. Since Moodle 2.5 it is allowed to assign roles with component+itemid even if roles are not protected.
* <syntaxhighlight lang="php">enrol_plugin::roles_protected()</syntaxhighlight> - True means that protected roles (nonempty component+itemid) cannot be modified by any other plugin. Return false if you want to allow users to remove all roles assigned by this plugin. Since Moodle 2.5 it is allowed to assign roles with component+itemid even if roles are not protected.
* <code>enrol_plugin::allow_enrol()</code> - True means other code may call <code>enrol_plugin::enrol_user()</code>, false means only plugin may enrol users. Each plugin is responsible for implementing its own UI for enrolment. See <code>enrol_plugin::get_manual_enrol_link()</code>.
* <syntaxhighlight lang="php">enrol_plugin::allow_enrol()</syntaxhighlight> - True means other code may call <syntaxhighlight lang="php">enrol_plugin::enrol_user()</syntaxhighlight>, false means only plugin may enrol users. Each plugin is responsible for implementing its own UI for enrolment. See <syntaxhighlight lang="php">enrol_plugin::get_manual_enrol_link()</syntaxhighlight>.
* <code>enrol_plugin::allow_unenrol()</code> and <code>enrol_plugin::allow_unenrol_user()</code> - Is other code allowed to unenrol everybody from one instance or one specific user? True is required for course reset and manual user unenrolment.
* <syntaxhighlight lang="php">enrol_plugin::allow_unenrol()</syntaxhighlight> and <syntaxhighlight lang="php">enrol_plugin::allow_unenrol_user()</syntaxhighlight> - Is other code allowed to unenrol everybody from one instance or one specific user? True is required for course reset and manual user unenrolment.
* <code>enrol_plugin:allow_manage()</code> - Return true if plugin allows manual modification of user enrolments from other code. False is usually returned from plugins that synchronise data with external systems, otherwise the manual changes would be reverted immediately upon synchronisation.
* <syntaxhighlight lang="php">enrol_plugin:allow_manage()</syntaxhighlight> - Return true if plugin allows manual modification of user enrolments from other code. False is usually returned from plugins that synchronise data with external systems, otherwise the manual changes would be reverted immediately upon synchronisation.
 


{{Moodle 3.4}}
{{Moodle 3.4}}
From Moodle 3.4 onwards, enrolment plugins don't have to override <code>enrol_plugin::get_user_enrolment_actions()</code>, unless your enrolment plugin provides other enrolment actions in addition to editing enrolment and user unenrolment. To support editing enrolment for your plugin, simply override <code>enrol_plugin::allow_manage()</code> to return true. To support unenrolment, be sure to override <code>enrol_plugin::allow_unenrol_user()</code> or <code>enrol_plugin::allow_unenrol()</code> to return true. For example:
From Moodle 3.4 onwards, enrolment plugins don't have to override '''''enrol_plugin::get_user_enrolment_actions()''''', unless your enrolment plugin provides other enrolment actions in addition to editing enrolment and user unenrolment.
<code>
 
To support editing enrolment for your plugin, simply override ''enrol_plugin::allow_manage()'' to return true. To support unenrolment, be sure to override ''enrol_plugin::allow_unenrol_user()'' or ''enrol_plugin::allow_unenrol()'' to return true. For example:
<syntaxhighlight lang="php">
class enrol_my_awesome_plugin extends enrol_plugin {
class enrol_my_awesome_plugin extends enrol_plugin {
     public function allow_manage(stdClass $instance) {
     public function allow_manage(stdClass $instance) {
         // Simply making this function return true will render the edit enrolment action in the participants list if the user has the 'enrol/pluginname:manage' capability
         // Simply making this function return true will render the edit enrolment action in the participants list if the user has the 'enrol/pluginname:manage' capability.
         return true;
         return true;
     }
     }
Line 57: Line 61:
     }
     }
}  
}  
</code>
</syntaxhighlight>
 


Should your enrolment plugin provides other enrolment actions aside from editing enrolment and unenrolment, you may override <code>enrol_plugin::get_user_enrolment_actions()</code>. For example:
Should your enrolment plugin provide other enrolment actions aside from editing enrolment and unenrolment, you may override ''enrol_plugin::get_user_enrolment_actions()''. For example:
<code>
<syntaxhighlight lang="php">
public function get_user_enrolment_actions(course_enrolment_manager $manager, $ue) {
public function get_user_enrolment_actions(course_enrolment_manager $manager, $ue) {
     // Get the standard user enrolment actions.
     // Get the standard user enrolment actions.
Line 71: Line 74:
     return $actions;
     return $actions;
}
}
</code>
</syntaxhighlight>


==Standard capabilities==
==Standard capabilities==


* '''enrol/xxx:enrol''' - Must be defined when <code>enrol_plugin::allow_enrol()</code> returns true.
* '''enrol/xxx:enrol''' - Must be defined when <syntaxhighlight lang="php">enrol_plugin::allow_enrol()</syntaxhighlight> returns true.
* '''enrol/xxx:unenrol''' - Must be implemented when <code>enrol_plugin::allow_unenrol()</code> or <code>enrol_plugin::allow_unenrol_user()</code> returns true.
* '''enrol/xxx:unenrol''' - Must be implemented when <syntaxhighlight lang="php">enrol_plugin::allow_unenrol()</syntaxhighlight> or <syntaxhighlight lang="php">enrol_plugin::allow_unenrol_user()</syntaxhighlight> returns true.
* '''enrol/xxx:manage''' - Must be implemented when <code>enrol_plugin::allow_manage()</code> returns true.
* '''enrol/xxx:manage''' - Must be implemented when <syntaxhighlight lang="php">enrol_plugin::allow_manage()</syntaxhighlight> returns true.
* '''enrol/xxx:unenrolself''' - Usually implemented when plugin support self-unenrolment.
* '''enrol/xxx:unenrolself''' - Usually implemented when plugin support self-unenrolment.
* '''enrol/xxx:config''' - Implemented when plugin allows user to modify instance properties. Automatic synchronisation plugins do not usually need this capability.
* '''enrol/xxx:config''' - Implemented when plugin allows user to modify instance properties. Automatic synchronisation plugins do not usually need this capability.
Line 85: Line 88:
In Moodle 3.1 changes were made to the enrolment plugin base class so that plugins do not have to define their own add/edit interface. In order to use this new logic, the enrolment plugin class must override and return true from this function:
In Moodle 3.1 changes were made to the enrolment plugin base class so that plugins do not have to define their own add/edit interface. In order to use this new logic, the enrolment plugin class must override and return true from this function:


<code>
<syntaxhighlight lang="php">
     /**                                                                                                                             
     /**                                                                                                                             
     * We are a good plugin and don't invent our own UI/validation code path.                                                       
     * We are a good plugin and don't invent our own UI/validation code path.                                                       
Line 94: Line 97:
         return true;                                                                                                                 
         return true;                                                                                                                 
     }
     }
</code>
</syntaxhighlight>


This means that the following functions from the plugin will be called to build the add/edit form, perform validation of the data and add standard navigation links to the manage enrolments page and course navigation.
This means that the following functions from the plugin will be called to build the add/edit form, perform validation of the data and add standard navigation links to the manage enrolments page and course navigation.


<code>
<syntaxhighlight lang="php">
     /**                                                                                                                             
     /**                                                                                                                             
     * Add elements to the edit instance form.                                                                                       
     * Add elements to the edit instance form.                                                                                       
Line 108: Line 111:
     */                                                                                                                             
     */                                                                                                                             
     public function edit_instance_form($instance, MoodleQuickForm $mform, $context) {
     public function edit_instance_form($instance, MoodleQuickForm $mform, $context) {
</code>
</syntaxhighlight>


<code>
<syntaxhighlight lang="php">
     /**                                                                                                                             
     /**                                                                                                                             
     * Perform custom validation of the data used to edit the instance.                                                             
     * Perform custom validation of the data used to edit the instance.                                                             
Line 123: Line 126:
     */                                                                                                                             
     */                                                                                                                             
     public function edit_instance_validation($data, $files, $instance, $context) {
     public function edit_instance_validation($data, $files, $instance, $context) {
</code>
</syntaxhighlight>


<code>
<syntaxhighlight lang="php">
     /**                                                                                                                             
     /**                                                                                                                             
     * Return true if we can add a new instance to this course.                                                                     
     * Return true if we can add a new instance to this course.                                                                     
Line 133: Line 136:
     */                                                                                                                             
     */                                                                                                                             
     public function can_add_instance($courseid) {                                                                                   
     public function can_add_instance($courseid) {                                                                                   
</code>
</syntaxhighlight>


In future - only plugins using this standard ui code path will provide a useful API for e.g. tool_uploadcourse to add/edit enrolment instances with complete validation of the submitted data.
In future - only plugins using this standard ui code path will provide a useful API for e.g. tool_uploadcourse to add/edit enrolment instances with complete validation of the submitted data.

Latest revision as of 05:36, 7 June 2022

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 all enrolment plugins must extend enrol_plugin base class which is defined at the end of lib/enrollib.php. This base class contains all standard methods together with developer documentation.

Course enrolment information is stored in tables

enrol

and

user_enrolments

and optionally other custom database tables defined by individual enrolment plugins. Each plugin has complete total over own instance record and user enrolments, by defaults user enrolments are protected and can not be modified manually by teachers.

Enrolment gives users following privileges:

  • User with active enrolment may enter course, other users need either temporary guest access right or moodle/course:view capability.
  • "My courses" shows list of active enrolments for current user.
  • Course participation - some activities restrict participation to enrolled users only. The behaviour is defined independently by each activity, for example only enrolled users with submit capability may submit assignments, the capability alone is not enough.
  • Only enrolled users may be members of groups.
  • Gradebook tracks grades of all enrolled users, visibility of grades is controlled by role membership.

Enrolments and role assignments are now separate concepts, you may be enrolled and not have any role and you may have a role in course and not be enrolled. Roles at course context level and below may be controlled by enrolment plugins.

User enrolment process

Manual enrolment plugins are the simplest way to handle user enrolments. This simplest plugin is enrol_manual, users with necessary permissions may enrol or unenrol users manually. enrol_flatfile plugin allows automation of enrolment and unenrolment actions.

Fully automatic plugins are configured at the system level, they synchronise user enrolments with information stored in external systems (ex.: enrol_ldap, enrol_database and enrol_category). Some non-interactive plugins may require configuration of enrolment instances (ex.: enrol_cohort and enrol_meta).

Interactive enrolment plugins require user interaction during enrolment (ex.: enrol_self and enrol_paypal). These plugins need to override

enrol_plugin::show_enrolme_link()

,

enrol_plugin::enrol_page_hook()

and to implement adding and editing of enrol instance.

Enrolment expiration and suspending

User has active enrolment if all following conditions are met:

  • user has record in
    user_enrolments
    
    table,
  • user enrolment already started,
  • user enrolment is not past timeend,
  • user enrolment has active status,
  • enrol instance has active status in
    enrol
    
    table,
  • enrol plugin is enabled.

Most synchronisation plugins include a setting called External unenrol action. It is used to decide what happens when previously enrolled user is not supposed to be enrolled any more. Synchronisation is usually executed from cli/sync.php or as part of standard cron.

Time based expiration was implemented in Moodle 2.5. Plugins that set timeend in user_enrolments table may want to specify expiration action and optional expiration notification, see

enrol_plugin::process_expirations()

and

enrol_plugin::send_expiry_notifications()

.

Manual enrolment modifications

The standard user enrolment UI does not use the following methods directly, so developers need to describe all possible UI enrolments actions via

enrol_plugin::get_user_enrolment_actions()

. It is very important to obey these restrictions in all externallib methods!

The following methods describe the allowed modifications for each enrolment instance:

  • enrol_plugin::roles_protected()
    
    - True means that protected roles (nonempty component+itemid) cannot be modified by any other plugin. Return false if you want to allow users to remove all roles assigned by this plugin. Since Moodle 2.5 it is allowed to assign roles with component+itemid even if roles are not protected.
  • enrol_plugin::allow_enrol()
    
    - True means other code may call
    enrol_plugin::enrol_user()
    
    , false means only plugin may enrol users. Each plugin is responsible for implementing its own UI for enrolment. See
    enrol_plugin::get_manual_enrol_link()
    
    .
  • enrol_plugin::allow_unenrol()
    
    and
    enrol_plugin::allow_unenrol_user()
    
    - Is other code allowed to unenrol everybody from one instance or one specific user? True is required for course reset and manual user unenrolment.
  • enrol_plugin:allow_manage()
    
    - Return true if plugin allows manual modification of user enrolments from other code. False is usually returned from plugins that synchronise data with external systems, otherwise the manual changes would be reverted immediately upon synchronisation.


Moodle 3.4

From Moodle 3.4 onwards, enrolment plugins don't have to override enrol_plugin::get_user_enrolment_actions(), unless your enrolment plugin provides other enrolment actions in addition to editing enrolment and user unenrolment.

To support editing enrolment for your plugin, simply override enrol_plugin::allow_manage() to return true. To support unenrolment, be sure to override enrol_plugin::allow_unenrol_user() or enrol_plugin::allow_unenrol() to return true. For example:

class enrol_my_awesome_plugin extends enrol_plugin {
    public function allow_manage(stdClass $instance) {
        // Simply making this function return true will render the edit enrolment action in the participants list if the user has the 'enrol/pluginname:manage' capability.
        return true;
    }
    public function allow_unenrol(stdClass $instance) {
        // Simply making this function return true will render the unenrolment action in the participants list if the user has the 'enrol/pluginname:unenrol' capability.
        return true;
    }
}

Should your enrolment plugin provide other enrolment actions aside from editing enrolment and unenrolment, you may override enrol_plugin::get_user_enrolment_actions(). For example:

public function get_user_enrolment_actions(course_enrolment_manager $manager, $ue) {
    // Get the standard user enrolment actions.
    $actions = parent::get_user_enrolment_actions();

    // Add your custom user enrolment actions here...
    $actions[] = ...;
    ...
    return $actions;
}

Standard capabilities

  • enrol/xxx:enrol - Must be defined when
    enrol_plugin::allow_enrol()
    
    returns true.
  • enrol/xxx:unenrol - Must be implemented when
    enrol_plugin::allow_unenrol()
    
    or
    enrol_plugin::allow_unenrol_user()
    
    returns true.
  • enrol/xxx:manage - Must be implemented when
    enrol_plugin::allow_manage()
    
    returns true.
  • enrol/xxx:unenrolself - Usually implemented when plugin support self-unenrolment.
  • enrol/xxx:config - Implemented when plugin allows user to modify instance properties. Automatic synchronisation plugins do not usually need this capability.

Standard Editing UI

In Moodle 3.1 changes were made to the enrolment plugin base class so that plugins do not have to define their own add/edit interface. In order to use this new logic, the enrolment plugin class must override and return true from this function:

    /**                                                                                                                            
     * We are a good plugin and don't invent our own UI/validation code path.                                                       
     *                                                                                                                              
     * @return boolean                                                                                                              
     */                                                                                                                             
    public function use_standard_editing_ui() {                                                                                     
        return true;                                                                                                                
    }

This means that the following functions from the plugin will be called to build the add/edit form, perform validation of the data and add standard navigation links to the manage enrolments page and course navigation.

    /**                                                                                                                             
     * Add elements to the edit instance form.                                                                                      
     *                                                                                                                              
     * @param stdClass $instance                                                                                                    
     * @param MoodleQuickForm $mform                                                                                                
     * @param context $context                                                                                                      
     * @return bool                                                                                                                 
     */                                                                                                                             
    public function edit_instance_form($instance, MoodleQuickForm $mform, $context) {
    /**                                                                                                                             
     * Perform custom validation of the data used to edit the instance.                                                             
     *                                                                                                                              
     * @param array $data array of ("fieldname"=>value) of submitted data                                                           
     * @param array $files array of uploaded files "element_name"=>tmp_file_path                                                    
     * @param object $instance The instance loaded from the DB                                                                      
     * @param context $context The context of the instance we are editing                                                           
     * @return array of "element_name"=>"error_description" if there are errors,                                                    
     *         or an empty array if everything is OK.                                                                               
     * @return void                                                                                                                 
     */                                                                                                                             
    public function edit_instance_validation($data, $files, $instance, $context) {
    /**                                                                                                                             
     * Return true if we can add a new instance to this course.                                                                     
     *                                                                                                                              
     * @param int $courseid                                                                                                         
     * @return boolean                                                                                                              
     */                                                                                                                             
    public function can_add_instance($courseid) {

In future - only plugins using this standard ui code path will provide a useful API for e.g. tool_uploadcourse to add/edit enrolment instances with complete validation of the submitted data.

See also