View source for Development:Enrolment plugins

==How to write an Enrolment plugin in Moodle 1.9==

Create a new directory called <code>/enrol/</code>'''<code>PLUGINNAME</code>'''. Within this directory, create a file <code>/enrol/</code>'''<code>PLUGINNAME</code>'''<code>/enrol.php</code> which contains the declaration for a class called <code>enrolment_plugin_</code>'''<code>PLUGINNAME</code>'''.

<code php>
class enrolment_plugin_PLUGINNAME {
    // Functions go here
    // ...
}
</code>

=== Mandatory functions ===

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

<code php>
    /**
     * 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;
    }
</code>

=== Automated enrolment ===

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

<code php>
    /**
     * 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.auth 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;
    }
</code>

=== Interactive enrolment ===

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

<code php>
    /**
     * 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';
    }
</code>

=== Cron ===

Your plugin can perform cron tasks if it contains a <code>cron()</code> function:

<code php>
    /**
     * 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!';
    }
</code>

=== Database ===

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

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

Then create a directory <code>enrol/PLUGINNAME/db</code>, 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 [http://www.pdncommunity.com/pdn/board/message?board.id=sandbox&view=by_date_ascending&message.id=9802#M9802 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 :<br />
$header = '';<br />
$header .= "POST /cgi-bin/webscr HTTP/1.0\r\n";<br />
$header .= "Content-Type: application/x-www-form-urlencoded\r\n";<br />
$header .= "Content-Length: " . strlen($req) . "\r\n\r\n";<br />
$paypaladdr = empty($CFG->usepaypalsandbox) ? 'www.paypal.com' : 'www.sandbox.paypal.com';<br />
$fp = fsockopen ($paypaladdr, 80, $errno, $errstr, 30);
* Change that code to :<br />
$header = '';<br />
$header .= "POST /cgi-bin/webscr HTTP/1.0\r\n";<br />
$header .= "Content-Type: application/x-www-form-urlencoded\r\n";<br />
$header .= "Content-Length: " . strlen($req) . "\r\n\r\n";<br />
$paypaladdr = empty($CFG->usepaypalsandbox) ? 'www.paypal.com' : 'ssl://www.sandbox.paypal.com';<br />
$fp = fsockopen ($paypaladdr, 443, $errno, $errstr, 30);<br />
* Try the course purchase again. 

If the above still is not working you will need to seek help in the [http://moodle.org/mod/forum/view.php?id=2981 Enrolment Plugins] Forum.

==Enrolment plugins 1.7==

===Background===
# isteacher(), isstudent(), isadmin(), iscoursecreator() are all deprecated and should be replaced with checks on has_capability instead.
# enrol_student() and add_teacher() are obsolete, so use the generic role_assign() or the convenience function for "students" called enrol_into_course() instead.
# unenrol_student() and remove_teacher() are obsolete, so use the generic role_unassign() instead.
# 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.
# 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).
# 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===

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

===What still needs to be done===

#enrol/authorize
#enrol/database
#enrol/flatfile
#enrol/ldap
#enrol/paypal

==See also==
*[[Enrolment plugins|Enrolment plugins (administrator)]]
*Using Moodle [http://moodle.org/mod/forum/view.php?id=2981 Enrolment Plugins] forum

[[Category:Developer|Enrolment plugins]]
[[Category:Enrolment]]