Source for file sl_lsllib.php

Documentation is available at sl_lsllib.php

  1. <?php    
  2.     /**
  3.     * Sloodle LSL handling library.
  4.     *
  5.     * Provides the central API functionality, automatically combining several other API elements.
  6.     *
  7.     * @package sloodle
  8.     * @copyright Copyright (c) 2007-8 Sloodle (various contributors)
  9.     * @license http://www.gnu.org/licenses/gpl-3.0.html GNU GPL v3
  10.     * @since Sloodle 0.2
  11.     *
  12.     * @contributor Peter R. Bloomfield
  13.     *
  14.     */
  15.     
  16.     // This library expects that the Sloodle config file has already been included
  17.     //  (along with the Moodle libraries)
  18.     
  19.     /** Include the general Sloodle functionality. */
  20.     require_once(SLOODLE_DIRROOT.'/lib/sl_generallib.php');
  21.     /** Include the Sloodle IO library. */
  22.     require_once(SLOODLE_DIRROOT.'/lib/sl_iolib.php');
  23.     /** Include the Sloodle user management library. */
  24.     require_once(SLOODLE_DIRROOT.'/lib/sl_userlib.php');
  25.     
  26.     
  27.     /** 
  28.     * A helper class to automate many API features.
  29.     * Most interaction with the object-oriented parts of the Sloodle API should occur via this class.
  30.     * It brings together the other classes, and automatically handles various features.
  31.     * @package sloodle
  32.     */
  33.     class SloodleLSLHandler
  34.     {
  35.     ///// PUBLIC DATA /////
  36.     
  37.         /**
  38.         * A Sloodle user object.
  39.         * Instantiated to the {@link: SloodleUser} type in the class constructor.
  40.         * No accessors - should be accessed directly.
  41.         * @var SloodleUser 
  42.         * @access public
  43.         */
  44.         var $user = NULL;
  45.         
  46.         /**
  47.         * A Sloodle request handling object.
  48.         * Instantiated to the {@link: SloodleLSLRequest} type in the class constructor.
  49.         * No accessors - should be accessed directly.
  50.         * @var SloodleLSLRequest 
  51.         * @access public
  52.         */
  53.         var $request = NULL;
  54.         
  55.         /**
  56.         * A Sloodle response handling object.
  57.         * Instantiated to the {@link: SloodleLSLResponse} type in the class constructor.
  58.         * No accessors - should be accessed directly.
  59.         * @var SloodleLSLHandler 
  60.         * @access public
  61.         */
  62.         var $response = NULL;
  63.         
  64.         
  65.     ///// FUNCTIONS /////
  66.     
  67.         /**
  68.         * Class constructor.
  69.         * Instantiates member objects.
  70.         * @return void 
  71.         * @access public
  72.         */
  73.         function SloodleLSLHandler()
  74.         {
  75.             // Instantiate and link our components
  76.             $this->user = new SloodleUser();
  77.             $this->response = new SloodleLSLResponse();
  78.             $this->request = new SloodleLSLRequest($this->response, $this->user);
  79.         }
  80.         
  81.         /**
  82.         * Performs an internal 'login' based on user identified in request.
  83.         * Checks for avatar UUID and/or name request parameters, and checks for an associated Moodle account.
  84.         * If found, the user is logged-in (details stored in Moodle's global $USER variable).
  85.         * @param bool $require If true (default), the function will terminate the script with an error message if login fails. (Error message will be LSL-friendly).
  86.         * @param bool $suppress_autoreg If true (not default), the function will always suppress auto-registration of new users. Note: this parameter will be ignored if auto-registration is disabled.
  87.         * @return bool True if login was successful. False if login failed, but parameter $require was false.
  88.         * @access public
  89.         */
  90.         function login_by_request($require = TRUE, $suppress_autoreg = FALSE)
  91.         {
  92.             // Make sure the request is processed and authenticated
  93.             $this->request->process_request_data(TRUE); // Force re-processing to ensure accurate user data
  94.             if (!$this->request->authenticate_request($require)) return FALSE;
  95.             
  96.             // Make sure the items of data were specified
  97.             if ($this->request->get_avatar_uuid() == NULL && $this->request->get_avatar_name() == NULL) {
  98.                 if ($require) {
  99.                     $this->response->set_status_code(-311);
  100.                     $this->response->set_status_descriptor('USER_AUTH');
  101.                     $this->response->add_data_line('User not identified in request.');
  102.                     $this->response->render_to_output();
  103.                     exit();
  104.                 }
  105.                 return FALSE;
  106.             }
  107.             
  108.             // Is the user already fully registered?
  109.             if ($this->user->get_sloodle_user_id() > 0 && $this->user->get_moodle_user_id() > 0) {
  110.                 // Yes - attempt to login
  111.                 if (!$this->user->login_moodle_user()) {
  112.                     // Login failed
  113.                     if ($require) {
  114.                         $this->response->set_status_code(-301);
  115.                         $this->response->set_status_descriptor('USER_AUTH');
  116.                         $this->response->add_data_line('Failed to login Moodle user for unkown reason.');
  117.                         $this->response->render_to_output();
  118.                         exit();
  119.                     }
  120.                     return FALSE;
  121.                 }
  122.                 
  123.                 // Login succeeded
  124.                 return TRUE;
  125.             }
  126.             
  127.             // Is auto-registration disabled or suppressed?
  128.             if (sloodle_is_automatic_registration_on() == FALSE || $suppress_autoreg == TRUE) {
  129.                 // We cannot do auto-registration
  130.                 if ($require) {
  131.                     $this->response->set_status_code(-321);
  132.                     $this->response->set_status_descriptor('USER_AUTH');
  133.                     $this->response->add_data_line('User not registered, and auto registration was not permitted.');
  134.                     if ($suppress_autoreg) $this->response->add_data_line('Note: auto registration was explicitly suppressed.');
  135.                     $this->response->render_to_output();
  136.                     exit();
  137.                 }
  138.                 return FALSE;
  139.             }
  140.             
  141.             
  142.             // Make sure we have both the avatar name and UUID
  143.             // [Note: if the user was fully registered with Sloodle and not Moodle, and only name OR UUID was provided,
  144.             //   then the earlier data processing will have retrieved the missing value... cunning, eh? :-)]
  145.             if (is_null($this->request->get_avatar_uuid())) {
  146.                 if ($require) {
  147.                     $this->response->set_status_code(-311);
  148.                     $this->response->set_status_descriptor('USER_AUTO_REG');
  149.                     $this->response->add_data_line('User auto registration not possible - avatar UUID was not provided or found in the database.');
  150.                     $this->response->render_to_output();
  151.                     exit();
  152.                 }
  153.                 return FALSE;
  154.             }
  155.             if (is_null($this->request->get_avatar_name())) {
  156.                 if ($require) {
  157.                     $this->response->set_status_code(-311);
  158.                     $this->response->set_status_descriptor('USER_AUTO_REG');
  159.                     $this->response->add_data_line('User auto registration not possible - avatar name was not provided or found in the database.');
  160.                     $this->response->render_to_output();
  161.                     exit();
  162.                 }
  163.                 return FALSE;
  164.             }
  165.         
  166.             // Do we need to register a Moodle account?
  167.             if ($this->user->get_moodle_user_id() <= 0) {
  168.                 // Extract the first and last name parts
  169.                 $firstname = NULL;
  170.                 $lastname = NULL;
  171.         $avname = $this->request->get_avatar_name();
  172.         $avbits = array();
  173.                 // Expecting that all SL names are first last, with a space in between
  174.                 if (preg_match('/^(.*)\s(.*?)$/', $avname, $avbits)) {
  175.                     $firstname = $avbits[1];
  176.                     $lastname = $avbits[2];
  177.                 } else {
  178.                     // Something wasn't quite right about the name
  179.                     if ($require) {
  180.                         $this->response->set_status_code(-322);
  181.                         $this->response->set_status_descriptor('USER_AUTO_REG');
  182.                         $this->response->add_data_line('User auto registration failed - could not extract first and last names from avatar name "'.$avname.'".');
  183.                         $this->response->render_to_output();
  184.                         exit();
  185.                     }
  186.                     return FALSE;
  187.                 }
  188.                 
  189.                 // Register the new Moodle account
  190.                 $autoreg = $this->user->create_moodle_user($firstname, $lastname, $this->request->get_avatar_uuid().'@lsl.secondlife.com');
  191.                 // Did something go wrong?
  192.                 if ($autoreg !== TRUE) {
  193.                     if ($require) {
  194.                         $this->response->set_status_code(-322);
  195.                         $this->response->set_status_descriptor('USER_AUTO_REG');
  196.                         $this->response->add_data_line('Moodle user creation failed.');
  197.                         if (is_string($autoreg)) $this->response->add_data_line($autoreg);
  198.                         $this->response->render_to_output();
  199.                         exit();
  200.                     }
  201.                     return FALSE;
  202.                 }
  203.             }
  204.             
  205.             // Do we need to register a Sloodle entry?
  206.             if ($this->user->get_sloodle_user_id() <= 0) {
  207.                 // Create the Sloodle entry
  208.                 $newsloodle = $this->user->create_sloodle_user(
  209.                                 $this->request->get_avatar_uuid(),
  210.                                 $this->request->get_avatar_name(),
  211.                                 $this->user->get_moodle_user_id()
  212.                                 ); // Other parameters can be default
  213.                 // Did it fail?
  214.                 if ($newsloodle !== TRUE) {
  215.                     if ($require) {
  216.                         $this->response->set_status_code(-322);
  217.                         $this->response->set_status_descriptor('USER_AUTO_REG');
  218.                         $this->response->add_data_line('Sloodle user creation failed.');
  219.                         if (is_string($newsloodle)) $this->response->add_data_line($newsloodle);
  220.                         $this->response->render_to_output();
  221.                         exit();
  222.                     }
  223.                     return FALSE;
  224.                 }
  225.             } else {
  226.                 // We already have a Sloodle user
  227.                 // Just link the users together
  228.                 $link = $this->user->link_users();
  229.                 if ($link !== TRUE) {
  230.                     if ($require) {
  231.                         $this->response->set_status_code(-322);
  232.                         $this->response->set_status_descriptor('USER_AUTO_REG');
  233.                         $this->response->add_data_line('Failed to link new Sloodle and Moodle users together.');
  234.                         if (is_string($link)) $this->response->add_data_line($link);
  235.                         $this->response->render_to_output();
  236.                         exit();
  237.                     }
  238.                     return FALSE;
  239.                 }
  240.             }
  241.             
  242.             // User has been auto-registered, so add a side-effect code to our response
  243.             $this->response->add_side_effect(322);
  244.             // Finally, attempt to login the new user
  245.             return $this->user->login_moodle_user();
  246.         }
  247.         
  248.         /**
  249.         * Authenticates the avatar identified in the request by the login security token.
  250.         * Uses the avatar UUID and/or name, and the security token request to parameters to
  251.         *  check against the details in the database.
  252.         * @param bool $use_cache If true (not default) then the function will use the user data stored in Sloodle user cache of the {@link: $user} member object (instead of querying the database for new data).
  253.         * @return bool True if authentication was successful, or false if not.
  254.         * @access public
  255.         */
  256.         function confirm_by_login_security_token($use_cache = FALSE)
  257.         {
  258.             // Was a login security token specified in the request? Do nothing if not
  259.             if ($this->request->get_login_security_token() == NULL) return FALSE;
  260.             // Are we using the cache?
  261.             if (!$use_cache) {
  262.                 // No - fetch fresh data and ensure it worked
  263.                 if ($this->update_sloodle_user_cache_from_db() !== TRUE) return FALSE;
  264.             }
  265.             
  266.             // Make sure the login security token is specified in the cache
  267.             if (!isset($this->user->sloodle_user_cache->loginsecuritytoken)) return FALSE;
  268.             // Compare the security tokens
  269.             return ($this->request->get_login_security_token() === $this->user->sloodle_user_cache->loginsecuritytoken);
  270.         }
  271.         
  272.         /**
  273.         * Checks that a user is enrolled in a course, based on request data.
  274.         * Fetches user and course identification from the standard request parameters.
  275.         * @param bool $require If true (default) then the function will terminate with an LSL-friendly error message if user is not enrolled, or not all data was present.
  276.         * @param bool $use_cache If true (not default) then the courses cache in the {@link: $user} member will be used, instead of querying the database for fresh data.
  277.         * @return bool True if the user is enrolled, or false otherwise.
  278.         * @access public
  279.         */
  280.         function is_user_enrolled_by_request( $require = TRUE, $use_cache = FALSE )
  281.         {
  282.             // Make sure the course exists
  283.             $course = $this->request->get_course_record($require);
  284.             // Is the user enrolled?
  285.             if (!$this->user->is_user_in_course($course->id, $use_cache)) {
  286.                 if ($require) {
  287.                     $this->response->set_status_code(-421);
  288.                     $this->response->set_status_descriptor('USER_ENROL');
  289.                     $this->response->add_data_line('User not enroled in course, and auto-enrolment is not yet implemented.');
  290.                     $this->response->render_to_output();
  291.                     exit();
  292.                 }
  293.                 return FALSE;
  294.             }
  295.             
  296.             // Everything seems fine
  297.             return TRUE;
  298.         }
  299.         
  300.     }
  301.     
  302.  
  303. ?>

Documentation generated on Tue, 04 Mar 2008 15:08:48 +0000 by phpDocumentor 1.4.0