Enrolment plugins

Enrolment plugins in Moodle 2.x

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 available methods and developer documentation.

Course enrolment information information is stored in tables enrol and user_enrolments and optionally other custom database tables defined by enrolment plugins. Each plugin have complete control over own instance record and user enrolments, by defaults user enrolments are protected and can not be modified manually by teachers.

Enrolment gives user following privileges:

• User with active enrolment may enter course, without enrolment user needs either temporary guest access right or moodle/course:view capability.
• "My courses" shows list of active enrolments for current user
• User participates in course - 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.

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 context level and bellow may be linked to user enrolments.

TODO... (skodak)

Enrolment plugins in Moodle 1.9

Create a new directory called /enrol/PLUGINNAME. Within this directory, create a file /enrol/PLUGINNAME/enrol.php which contains the declaration for a class called enrolment_plugin_PLUGINNAME. Note that PLUGINNAME must be letters only as it is passed through PARAM_ALPHA.

class enrolment_plugin_PLUGINNAME {

   // Functions go here
   // ...

}

Mandatory functions

Your enrolment plugin class is required to define these two functions, which print and process a configuration form.

   /**
    * Prints out the configuration form for this plugin. All we need
    * to provide is the form fields. The <form> tags and submit button will
    * be provided for us by Moodle.
    *
    * @param object $formdata Equal to the global $CFG variable, or if
    *      process_config() returned false, the form contents
    * @return void
    */
   public function config_form( $formdata ){
       return;
   }

   /**
    * Process the data from the configuration form.
    *
    * @param object $formdata
    * @return boolean True if configuration was successful, False if the user
    *      should be kicked back to config_form() again.
    */
   public function process_config( $formdata ){
       return true;
   }

Optional functions

Automated enrolment

To handle automated enrolment, your function may contain a setup_enrolments($user) function. This will be called each time a user logs in, to allow the plugin to make any changes to their enrolments.

   /**
    * OPTIONAL: Set up non-interactive enrolments for user. This is the most
    * important function for non-interactive enrolment plugins (such as LDAP
    * and external database). It is called each time a user logs in.
    * 
    * @param object $user
    * @return void
    */
   public function setup_enrolments( $user ){
       // Note that when you're setting up role assignments, you should use the
       // mdl_role_assignment.enrol column to indicate which role assignments
       // are from this plugin.
       role_assign($someroleid, $user->id, null, $somecontextid, 0, 0, 0, 'PLUGINNAME');
       role_unassign($someroleid, $user->id, null, $somecontextid, 'PLUGINNAME');
       
       return;
   }

Interactive enrolment

Your plugin can handle interactive enrolment (i.e. self-enrolment) by implementing these four functions. (See the manual enrolment plugin enrol/manual/enrol.php for an example that uses all of these.)

   /**
    * OPTIONAL: Prints the entry form/page for interactive enrolment into a course.
    * 
    * This is only called from course/enrol.php. Most plugins will probably
    * override this to print payment forms, etc, or even just a notice to say
    * that manual enrollment is disabled.
    * 
    * @param object $course
    * @return void
    */
   public function print_entry(){
   }

   /**
    * OPTIONAL: The other half to print_entry(), this checks the form data.
    * 
    * This function checks that the user has completed the task on the enrollment
    * entry page and enrolls them.
    * 
    * @param object $form
    * @param object $course 
    * @return void
    */
   public function check_entry( $form, $course ){
       // some logic
       // some role_assign();
   }

   /**
    * OPTIONAL: Check if the given enrolment key matches a group enrolment key for
    * the given course.
    * 
    * @param int $courseid
    * @param string $enrolmentkey
    * @return mixed The group id of the group which the key matches, or false
    *       if it matches none
    */
   public function check_group_entry( $courseid, $password ){
       // some logic
       if ( $itlooksgood ){
           return $groupid;
       } else {
           return false;
       }
   }

   /**
    * OPTIONAL: Return a string with icons that give enrolment information
    * for this course.
    * 
    * @param object $course
    * @return string
    */
   public function get_access_icons( $course ){
       return 'put icons here';
   }

Cron

Your plugin can perform cron tasks if it contains a cron() function:

   /**
    * OPTIONAL: If this function exists, it will be called each time
    * admin/cron.php runs. It takes no arguments and returns no values,
    * but anything written to $this->log will be printed to the cron output.
    * 
    * @return void
    */
   public function cron(){
       $this->log = 'Print this in the cron log!';
   }

Language Strings

Create a lang directory and file under your plugin's directory, like this enrol/PLUGINNAME/lang/en_utf8/enrol_PLUGINNAME.php. Plugins are expected to provide at least these two strings:

<?php

// The name of your plugin. Displayed on admin menus. $string['enrolname'] = 'My plugin';

// Description of your plugin. Shown on the plugin's configuration screen. $string['description'] = 'This is what my plugin does.';

?>

Those two strings will be accessed automatically by Moodle in various situations. You can (and should) of course include other language strings in your plugin's lang file(s). These can be accessed like normal language strings, using "enrol_PLUGINNAME" as the module name, e.g. get_string('anotherstring', 'enrol_PLUGINNAME').

Database

If your plugin needs to have its own Moodle database tables, create a file called enrol/PLUGINNAME/version.php like this:

<?php $plugin->version = 2010091600; // Version of your plugin $plugin->requires = 2007101000; // Required Moodle version (from /version.php) ?>

Then create a directory enrol/PLUGINNAME/db, and use the XMLDB editor to set up your tables.

Testing paypal using the paypal developer sandbox

For moodle 1.4 - 1.8

If you follow these steps, you can test paypal payments using the paypal developer sandbox instead of the real paypal site. No money is actually charged to any account. All other actions are the same as if you were using the real paypal site.

• create a paypal developer account at https://developer.paypal.com/cgi-bin/devscr?cmd=_home
• change the address being used to send data to paypal to use the sandbox. in enrol/paypal/enrol.html:
  • change the form post action to be https://www.sandbox.paypal.com/cgi-bin/webscr instead of https://www.paypal.com/cgi-bin/webscr
• change the address that is used to check the acknowledgment from paypal. in enrol/paypal/ipn.php, change:
  • $fp = fsockopen ('www.paypal.com', 80, $errno, $errstr, 30);
• to
  • $fp = fsockopen ('www.sandbox.paypal.com', 80, $errno, $errstr, 30);
• create a couple of user accounts in the paypal sandbox and test enrolling in a course that requires payment (note that you need to be logged into the paypal sandbox while doing this testing)
• under the "business" sandbox account you created, log in, go to "Profile", "Instant Payment Notification", and enter the full web-visible HTTPS URL to ../enrol/paypal/ipn.php. Failing to do this is a common mistake, and the cause of most headaches with this plugin.

For moodle 1.8.2 - 1.9.x

The above changes to the code were made part of the release starting with version 1.8.2

If you follow these steps, you can test paypal payments using the paypal developer sandbox instead of the real paypal site. No money is actually charged to any account. All other actions are the same as if you were using the real paypal site.

• create a paypal developer account at https://developer.paypal.com/cgi-bin/devscr?cmd=_home
• create a couple of user accounts in the paypal sandbox and test enrolling in a course that requires payment (note that you need to be logged into the paypal sandbox while doing this testing)
• under the "business" sandbox account you created, log in, go to "Profile", "Instant Payment Notification", and enter the full web-visible HTTPS URL to ../enrol/paypal/ipn.php. Failing to do this is a common mistake, and the cause of most headaches with this plugin.
• add the following line to config.php located in the root directory of your installation (where you installed Moodle).
  • $CFG->usepaypalsandbox = 'TRUE';
• Add the business account email address from "business" account you created to the paypal module settings (in 1.9.x - Site Administration>Courses>Enrolments>Paypal>Edit)
• You should be ready to test
• When finished be sure to remove the line that was added to config.php in your root directory.

Note about Paypal Sandbox

Only implement these changes if the above is not working and Moodle is returning the "...Unfortunately your payment..." message after returning from Paypal Sandbox.

At the time of this writing (14 June 2008) some changes are necessary to test successfully in the Paypal Sandbox. Details can be found here. This could change at any time at which point this may become unnecessary. For now do the following (only tested in 1.9.x so far):

• Locate ipn.php in your installation on your server by migrating to to ../enrol/paypal/ipn.php
• Create a backup copy of ipn.php and give it a name something like ipn.php-backup
• Return to ipn.php and locate the following code :
  

$header = ;
$header .= "POST /cgi-bin/webscr HTTP/1.0\r\n";
$header .= "Content-Type: application/x-www-form-urlencoded\r\n";
$header .= "Content-Length: " . strlen($req) . "\r\n\r\n";
$paypaladdr = empty($CFG->usepaypalsandbox) ? 'www.paypal.com' : 'www.sandbox.paypal.com';
$fp = fsockopen ($paypaladdr, 80, $errno, $errstr, 30);

• Change that code to :
  

$header = ;
$header .= "POST /cgi-bin/webscr HTTP/1.0\r\n";
$header .= "Content-Type: application/x-www-form-urlencoded\r\n";
$header .= "Content-Length: " . strlen($req) . "\r\n\r\n";
$paypaladdr = empty($CFG->usepaypalsandbox) ? 'www.paypal.com' : 'ssl://www.sandbox.paypal.com';
$fp = fsockopen ($paypaladdr, 443, $errno, $errstr, 30);

• Try the course purchase again.

If the above still is not working you will need to seek help in the Enrolment Plugins Forum.

Enrolment plugins 1.7

Background

1. isteacher(), isstudent(), isadmin(), iscoursecreator() are all deprecated and should be replaced with checks on has_capability instead.
2. enrol_student() and add_teacher() are obsolete, so use the generic role_assign() or the convenience function for "students" called enrol_into_course() instead.
3. unenrol_student() and remove_teacher() are obsolete, so use the generic role_unassign() instead.
4. All the roles have a "shortname", so by default we can refer to them using "teacher", "student", "editingteacher" etc. Note that new roles may have different names. Enrolment plugins can use these to map outside data onto the inside roles without needing to know internal role id numbers. For example, it would be really handy for the flatfile plugin to refer to roles directly like this.
5. Each plugin used to implement get_student_courses() and get_teacher_courses() for use at login time. These now need to be converted to one new function called $enrol->setup_enrolments($user) which looks up sets all enrolments for a given user (using role_assign and role_unassign).
6. All the session arrays like $USER->student[] and $USER->teacher[] are gone and should not be relied on. You can check what roles a user already has by calling get_user_roles() on that course context.

What's been done

1. enrol/manual has been converted to use the new functions
2. enrol/imsenterprise has been converted - testing needed though

What still needs to be done

1. enrol/authorize
2. enrol/database
3. enrol/flatfile
4. enrol/ldap
5. enrol/paypal

See also

• Enrolment plugins (administrator)
• Using Moodle Enrolment Plugins forum