MDL-8973 auth hooks final cleanup; merged from MOODLE_18_STABLE

lib/authlib.php

@@ -56,6 +56,11 @@ class auth_plugin_base {
     var $authtype;
 
     /**
+
+     * This is the primary method that is used by the authenticate_user_login()
+     * function in moodlelib.php. This method should return a boolean indicating
+     * whether or not the username and password authenticate successfully.
+     *
      * Returns true if the username and password work and false if they are
      * wrong or don't exist.
      *
@@ -69,7 +74,7 @@ class auth_plugin_base {
     }
 
     /**
-     * Returns true if this authentication plugin can change the user's
+     * Returns true if this authentication plugin can change the users'
      * password.
      *
      * @return bool
@@ -80,8 +85,8 @@ class auth_plugin_base {
     }
 
     /**
-     * Returns the URL for changing the user's pw, or empty if the default can
-     * be used.
+     * Returns the URL for changing the users' passwords, or empty if the default
+     * URL can be used. This method is used if can_change_password() returns true.
      *
      * @return string
      */
@@ -91,7 +96,9 @@ class auth_plugin_base {
     }
 
     /**
-     * Returns true if this authentication plugin is 'internal'.
+     * Returns true if this authentication plugin is "internal" (which means that
+     * Moodle stores the users' passwords and other details in the local Moodle
+     * database).
      *
      * @return bool
      */
@@ -101,7 +108,9 @@ class auth_plugin_base {
     }
 
     /**
-     * Change a user's password
+     * Updates the user's password. In previous versions of Moodle, the function
+     * auth_user_update_password accepted a username as the first parameter. The
+     * revised function expects a user object.
      *
      * @param  object  $user        User table object  (with system magic quotes)
      * @param  string  $newpassword Plaintext password (with system magic quotes)
@@ -237,6 +246,16 @@ class auth_plugin_base {
         return array();
     }
 
+    /**
+     * Prints a form for configuring this authentication plugin.
+     *
+     * This function is called from admin/auth.php, and outputs a full page with
+     * a form for configuring this plugin.
+     */
+    function config_form($config, $err, $user_fields) {
+        //override if needed
+    }
+
     /**
      * A chance to validate form data, and last chance to
      * do stuff before it is inserted in config_plugin
@@ -246,34 +265,54 @@ class auth_plugin_base {
     }
 
     /**
-     * Prelogin actions.
+     * Processes and stores configuration data for this authentication plugin.
      */
-    function prelogin_hook() {
+    function process_config($config) {
+        //override if needed
+        return true;
+    }
+
+    /**
+     * Hook for overriding behavior of login page.
+     * This method is called from login/index.php page for all enabled auth plugins.
+     */
+    function loginpage_hook() {
+        global $frm;  // can be used to override submitted login form
+        global $user; // can be used to replace authenticate_user_login()
+
         //override if needed
     }
 
     /**
      * Post authentication hook.
+     * This method is called from authenticate_user_login() for all enabled auth plugins.
+     *
+     * @param object $user user object, later used for $USER
+     * @param string $username (with system magic quotes)
+     * @param string $password plain text password (with system magic quotes)
      */
-    function user_authenticated_hook($user, $username, $password) {
-    /// TODO: review following code - looks hackish :-( mnet should obsole this, right?
-    /// Log in to a second system if necessary
-        global $CFG;
-
-        if (!empty($CFG->sso)) {
-            include_once($CFG->dirroot .'/sso/'. $CFG->sso .'/lib.php');
-            if (function_exists('sso_user_login')) {
-                if (!sso_user_login($username, $password)) {   // Perform the signon process
-                    notify('Second sign-on failed');
-                }
-            }
-        }
+    function user_authenticated_hook(&$user, $username, $password) {
+        //override if needed
     }
 
     /**
-     * Prelogout actions.
+     * Pre logout hook.
+     * This method is called from require_logout() for all enabled auth plugins,
      */
     function prelogout_hook() {
+        global $USER; // use $USER->auth to find the plugin used for login
+
+        //override if needed
+    }
+
+    /**
+     * Hook for overriding behavior of logout page.
+     * This method is called from login/logout.php page for all enabled auth plugins.
+     */
+    function logoutpage_hook() {
+        global $USER;     // use $USER->auth to find the plugin used for login
+        global $redirect; // can be used to override redirect after logout
+
         //override if needed
     }
 }