SloodleLSLHandler

From SLIS Second Life Wiki

Declaration

class SloodleLSLHandler
Defined in: lib/sl_lsllib.php

Summary

This PHP class is the central part of the Sloodle PHP API, as it automatically brings together all of the other main classes in the API upon construction. This prevents the need for programmers to continually 'reinvent the wheel' while developing Sloodle scripts. It is typically used by Linker Scripts to:

Handle and process the incoming request
Find and manage the avatar and Moodle user data
Construct and render appropriately formatted responses

The main class in each of these steps are SloodleLSLRequest, SloodleUser, and SloodleResponse respectively. It is important to remember that most (but not all) of the underlying functionality takes places within these classes, but that the SloodleLSLHandler provides the means for those other classes to communicate. This can be seen in the following UML diagram, which shows that the SloodleLSLRequest object also takes on references to the SloodleUser and SloodleResponse objects (if these references are not provided, then the SloodleLSLRequest class creates its own). Additionally, there are certain functions in the SloodleLSLHandler class which use the underlying objects together.

Compatibility

This class conforms to PHP4 syntax, and so scope visibility qualifiers (public, private, protected) are not available. However, unlike in the other API classes, all member data should be considered public.

Data

This class contains the following member values (all of which should be considered public):

var $user

Assigned NULL by default. At construction time it is set to a new instance of the SloodleUser class.

var $response

Assigned NULL by default. At construction time it is set to a new instance of the SloodleLSLResponse class.

var $request

Assigned NULL by default. At construction time it is set to a new instance of the SloodleLSLRequest class. The $user and $response members are constructed first, and passed into the constructor of this object.

Functions

SloodleLSLHandler()

Constructor -- constructs objects for each of the members: $user, $response, and $request.

login_by_request($require = TRUE, $suppress_autoreg = FALSE)

Checks to see if sufficient data was passed into the $request member such that an avatar can be recognised. If so, it checks to see if that avatar has been registered to a specific Moodle account. If so, then that user's details are fetched from the database, and the user is 'logged-in' for purposes of this single request. (i.e. their data is set into Moodle's global $USER variable).

If parameter $require is boolean TRUE (default), then the script will terminate if login fails, e.g. not enough data was provided, or there was no linked Moodle account. The $response member is used to output an error message prior to terminate.

If parameter $suppress_autoreg is TRUE, then the script will not auto-register the user under any circumstances, even if auto-registration is enabled in the Sloodle Module Configuration page (see User Authentication Method for more information).

If login was successful, then the function returns TRUE. If $require is FALSE, then the function will return FALSE if login fails.

confirm_by_login_security_token($use_cache = FALSE)

This function is used to check the $request data to compare avatar and Login Security Token details against the database. This acts like an internal 'username and password' combination, to ensure that the login request is genuine. It is used in the registration process when using web registration.

If the details all match correctly, then the function returns TRUE. If there is a mismatch, or if any of the data is unrecognised or missing, then the function returns FALSE.

The $use_cache parameter can be used to prevent an additional database query if you know that the Sloodle user data cache in the $user member is fully up-to-date. In such cases, set this parameter to TRUE. However, most of the time, you can probably ignore this parameter and let it refresh the user cache for you. It will default to FALSE if unspecified.

is_user_enrolled_by_request($require = TRUE, $use_cache = FALSE)

This function will check whether or not the avatar identified in the $request data is registered to a particular Moodle account. If so, it checks if that Moodle user in enrolled in the course identified in the $request data.

If the user is confirmed as enrolled, then the function returns TRUE. Under all other circumstances, the function will either return FALSE, or terminate the script with an error message. (The latter behaviour is the default, but can be changed by setting the $require parameter to FALSE).