SloodleUser

Contents 1 Declaration 2 Summary 3 Compatibility 4 Data 4.1 Private 4.1.1 var $sloodle_user_id 4.1.2 var $moodle_user_id 4.2 Public 4.2.1 var $sloodle_user_cache 4.2.2 var $moodle_user_cache 4.2.3 var $enrolled_courses_cache 5 Functions 5.1 Construction 5.1.1 SloodleUser() 5.2 Accessors 5.2.1 get_sloodle_user_id() 5.2.2 set_sloodle_user_id($id) 5.2.3 get_moodle_user_id() 5.2.4 set_moodle_user_id($id) 5.3 User Links 5.3.1 users_linked($use_cache = FALSE) 5.3.2 link_users() 5.3.3 unlink_sloodle_user() 5.4 Database Functions 5.4.1 delete_sloodle_user() 5.4.2 update_sloodle_user_cache_from_db() 5.4.3 update_moodle_user_cache_from_db() 5.4.4 update_sloodle_user_cache_to_db() 5.4.5 insert_sloodle_user_cache_to_db() 5.4.6 create_sloodle_user($uuid, $avname, $userid, $loginposition, $loginpositionexpires, $loginpositionregion, $loginsecuritytoken) 5.4.7 delete_login_position() 5.4.8 generate_login_position($expires) 5.4.9 create_moodle_user($firstname, $lastname, $email) 5.5 User Searching Functions 5.5.1 find_sloodle_user($uuid, $name, $cache_data = TRUE) 5.5.2 find_linked_sloodle_user($cache_data = TRUE) 5.5.3 find_linked_moodle_user($use_cache = FALSE, $cache_data = TRUE) 5.5.4 find_sloodle_user_by_login_position($position, $cache_data = TRUE) 5.6 Login Functions 5.6.1 login_moodle_user() 5.6.2 regenerate_login_security_token($cache_data = TRUE) 5.6.3 has_login_security_token($use_cache = FALSE) 5.7 Course Functions 5.7.1 update_enrolled_courses_cache_from_db() 5.7.2 is_user_in_course($course_id, $use_cache = FALSE)

Declaration

class SloodleUser
Defined in: lib/sl_lsllib.php
Contained by: SloodleLSLHandler, SloodleLSLRequest

Summary

This PHP class is responsible for Sloodle and Moodle user handling in the Sloodle PHP API, providing functionality for finding, managing and manipulating user data. Note that a "Sloodle user" is really just an avatar.

At any one time, an object of this class type can have on Sloodle user selected, and/or one Moodle user selected. Typically, an HTTP request from an LSL script will contain an avatar's UUID and/or name. This class can be used to track down the relevant Sloodle user data, and whatever Moodle account may be linked to it. (It can also do the reverse, as well as create user entries, and link/unlink separate users).

Compatibility

This class conforms to PHP4 syntax, and so scope visibility qualifiers (public, private, protected) are not available. Some of the data should be considered private, whereas the 'cache' variables can be considered public.

Data

Private

This class contains the following member values, which should be considered private:

var $sloodle_user_id

This variable will always been an integer, storing the database ID of an avatar's entry in the 'sloodle_users' table (i.e. the currently 'selected' user). Note: 0 is an invalid ID, so if the value is not positive, then it can be considered empty.

You can get/set this value using the member accessor functions get_sloode_user_id() and set_sloodle_user_id($id).

var $moodle_user_id

This variable will always been an integer, storing the database ID of a Moodle user's account entry in the Moodle 'user' table (i.e. the currently 'selected' user). Note: 0 is an invalid ID, so if the value is not positive, then it can be considered empty.

You can get/set this value using the member accessor functions get_moode_user_id() and set_moodle_user_id($id).

Public

This class contains the following member values, which should be considered public:

var $sloodle_user_cache

This variable will be used to store the data from the latest database query for Sloodle user data (i.e. avatar name/UUID etc.). Initially default to NULL, but after construction it will always be a custom object, where each member corresponds to a field in the 'sloodle_users' table. Various functions will overwrite the data here with updated data, but some can also use this cached data to perform more efficient queries (i.e. use the cache instead of making a new database query).

• Note: if a function updates the cache, it will always match the user identified in member $sloodle_user_id. However, changing the ID will not update the cache, so you cannot be guaranteed that the cache and the ID number are in sync!

var $moodle_user_cache

This variable will be used to store the data from the latest database query for Moodle user data (i.e. name, email address etc.). Initially default to NULL, but after construction it will always be a custom object, where each member corresponds to a field in the Moodle 'user' table. Various functions will overwrite the data here with updated data, but some can also use this cached data to perform more efficient queries (i.e. use the cache instead of making a new database query).

• Note: if a function updates the cache, it will always match the user identified in member $moodle_user_id. However, changing the ID will not update the cache, so you cannot be guaranteed that the cache and the ID number are in sync!

var $enrolled_courses_cache

Initially defaulted to NULL, but after construction, will always be a numeric array (although it may an empty array). Certain functions can use or update the cache with a list of integer ID's that the current Moodle user (i.e. the one identified by member $moodle_user_id) is enrolled in. As with the other caches, this can be used to avoid additional queries for the same database data.

Functions

Construction

SloodleUser()

Constructor -- initialises the cache objects and array.

Accessors

get_sloodle_user_id()

Accessor: returns the member $sloodle_user_id.

set_sloodle_user_id($id)

Accessor: sets the member $sloodle_user_id.

• Parameter $id should be a positive or zero integer.

get_moodle_user_id()

Accessor: returns the member $sloodle_user_id.

set_moodle_user_id($id)

Accessor: sets the member $moodle_user_id.

• Parameter $id should be a positive or zero integer.

User Links

These functions handle the linking between avatars and Moodle accounts (see Registration and Enrolment for more details).

users_linked($use_cache = FALSE)

Checks if the avatar identified by member $sloodle_user_id is linked to the Moodle account identified by member $moodle_user_id.

The $use_cache parameter can be set to TRUE to force the query to use the Sloodle and Moodle user caches, isntead of fetching new data for each user. WARNING: ensure that both user caches are up-to-date if you use this!

Returns TRUE if the avatar is linked, FALSE if not, or a string containing an error message if an error occurs. Common errors may include:

• One or both of the user ID's is 0, or does not identify a valid user
• Parameter $use_cache was set to true, but there is not data in one or both of the user caches

link_users()

This function will link the avatar identified by member $sloodle_user_id with the Moodle account identified by member $moodle_user_id.

Returns TRUE if successful in linking the avatar to the Moodle account, FALSE if the database update failed, or a string containing an error message if an error occurs. Common errors may include:

• One or both of the user ID's is 0, or does not identify a valid user

unlink_sloodle_user()

If a Sloodle user (i.e. an avatar) is selected by having an ID in member $sloodle_user_id, then this function will remove any link from that avatar to a Moodle account. Note: when an avatar is linked to a Moodle account, the link physically only exists in the Sloodle user data, so nothing needs to be done on the Moodle side.

Returns TRUE if successful, FALSE if the database update fails, or a string if an error occurs. The only typical error is if the $sloodle_user_id member is not a valid ID.

Database Functions

These functions are used for general database manipulation of user data. Most of them will return TRUE if successful, FALSE if the database operation fails, or a string error message if there is another problem. Such problems are usually related to an invalid parameter, or not having a valid user identified in the $sloodle_user_id or $moodle_user_id members.

delete_sloodle_user()

If a Sloodle user is currently identified by the $sloodle_user_id member, then the associated entry in the database will be deleted. The function will return TRUE if successful, FALSE if the database operation fails, or a string error message if there is another problem.

update_sloodle_user_cache_from_db()

This function will query the database for avatar data about the Sloodle user identified in member $sloodle_user_id. The new data will be stored in the $sloodle_user_cache member, and the function will return TRUE if successful. It will return FALSE if it fails, or a string if an error occurs.

update_moodle_user_cache_from_db()

This function will query the database for account data about the Moodle user identified in member $moodle_user_id. The new data will be stored in the $moodle_user_cache member, and the function will return TRUE if successful. It will return FALSE if it fails, or a string if an error occurs.

update_sloodle_user_cache_to_db()

If you have previously retrieved database data into the Sloodle user cache (member $sloodle_user_cache), then you can modify the cache manually, and send your changes back to the database using this function. It will return TRUE if successful, FALSE if the database operation fails, or a string error message if there is another problem.

insert_sloodle_user_cache_to_db()

If you have manually created a Sloodle user (i.e. avatar) entry in the $sloodle_user_cache member, then you can insert it as a new database entry using this function. It will return TRUE if successful, FALSE if the database operation fails, or a string error message if another problem occurs. Note: the new ID value will be written to to the $sloodle_user_id member prior to function return. (Although the cache itself will not be updated... perhaps we should change this behaviour? :-)).

create_sloodle_user($uuid, $avname, $userid, $loginposition, $loginpositionexpires, $loginpositionregion, $loginsecuritytoken)

This function will create a new Sloodle user entry in the database, based on the parameters specified in the function. All parameters are optional and can be left blank, although it is recommended that you specify as much as possible. Note: a new login security token will be generated automatically if you do not specify one. If successful, the new Sloodle user ID will be stored in member $sloodle_user_id, and the $sloodle_user_cache member will be updated.

The function will return TRUE if successful, FALSE if the database operation fails, or a string error message if another problem occurs.

delete_login_position()

If the Sloodle user identified by member $sloodle_user_id currently has a LoginZone position allocated to them, then this function will delete it. It will return TRUE if successful, FALSE if the database operation fails, or a string error message if another problem occurs.

generate_login_position($expires)

This function will attempt to allocate a new, unique LoginZone position to the Sloodle user identified by member $sloodle_user_id. Parameter $expires should be an integer timestamp indicating when the LoginZone position should expire (it must be greater than the current time).

If successful, the function updates the Sloodle user cache ($sloodle_user_cache), and returns TRUE. If a unique LoginZone position could not be created, then FALSE is returned. If any other error occurs (including database errors) then a string error message is returned.

create_moodle_user($firstname, $lastname, $email)

• NOTE: may want to replace the contents of this function with a call to a standard Moodle user-creation function?

This function will create a new Moodle user account, with the details specified in parameters $firstname, $lastname and $email. It will generate a username by concatenating the first and last names, and if necessary, appending a random 3 digit number to ensure uniqueness. If successful, the new data will be written to the $moodle_user_id and $moodle_user_cache members, and the function will return TRUE. Otherwise, a string error message will be returned.

User Searching Functions

These functions are used for automatically finding avatars or users based on certain criteria. They will typically update the ID's and (optionally) the caches, and return TRUE or FALSE to indicate successful or failure.

find_sloodle_user($uuid, $name, $cache_data = TRUE)

This function will attempt to find an avatar in the database with the specified UUID (parameter $uuid), and if that fails, it will attempt to find them by name ($name). If an avatar is found, then its ID is stored in the $sloodle_user_id member, and the function returns TRUE. (Note: if parameter $cache_data is TRUE (default), then the database data is also stored in the $sloodle_user_cache member.)

If no matching user is found then the function returns FALSE. If there is an error, such as the UUID and name being empty, then a string error message is returned.

find_linked_sloodle_user($cache_data = TRUE)

This function will attempt to find an avatar (Sloodle user) in the database which is linked to the Moodle user identified by member $moodle_user_id. If successful, it will store the Sloodle user ID in member $sloodle_user_id, and return TRUE. (Note: if parameter $cache_data is TRUE (default), then the database data is also stored in the $sloodle_user_cache member.)

If there is no linked Sloodle user, then FALSE is returned. If an error occurss, such as an invalid Moodle user ID or multiple avatars linked to the Moodle account, then a string error message will be returned.

find_linked_moodle_user($use_cache = FALSE, $cache_data = TRUE)

Attempts to find the Moodle user account linked to the current Sloodle user. Note: if parameter $use_cache is FALSE (default) then it will query the database for the Sloodle user identified in member $sloodle_user_id to get link data. Otherwise, it will use the $sloodle_user_cache member to look for link data.

If a linked Moodle account is found, then the user ID is stored in member $moodle_user_id, and TRUE is returned. (Note: if parameter $cache_data is TRUE (default), then the database data is also stored in the $moodle_user_cache member.)

If there is no linked Moodle account, then FALSE is returned. If a problem occurs, such invalid user ID's, then a string error message is returned.

find_sloodle_user_by_login_position($position, $cache_data = TRUE)

This function will attempt to find a Sloodle user with the given LoginZone position. If successful, it will store the Sloodle user's ID in the $sloodle_user_id member, and TRUE will be returned. (Note: if parameter $cache_data is TRUE (default), then the database data is also stored in the $sloodle_user_cache member.)

If no matching Sloodle user is found, then FALSE is returned. Otherwise, if an error occurs, such as an invalid user ID, then a string error message is returned.

Login Functions

These functions relate to 'logging-in' a user for purposes of the currently executing script. This only affects general Moodle user actions carried out by the current script, and does not affect the user's web-browsing experience, which is entirely separate.

login_moodle_user()

This function willl attempt to 'login' the Moodle user identified in member $moodle_user_id by storing their user data in Moodle's global $USER variable. If the Moodle user ID is invalid, or the user cannot be found, then FALSE is returned.

regenerate_login_security_token($cache_data = TRUE)

This function generate a new login security token for the Sloodle user identified by member $sloodle_user_id. It will return TRUE if successful, or FALSE if it fails (failure occurs if the user ID is invalid, or if the database query fails).

(Note: if parameter $cache_data is TRUE (default), and the operation is succesful, then the new database data is also stored in the $sloodle_user_cache member.)

has_login_security_token($use_cache = FALSE)

This function checks to see whether or not the Sloodle user already has a security token. If parameter $use_cache is TRUE then it will check the cached data for a login security token, and return TRUE if it was found, or FALSE otherwise.

If the $use_cache parameter is FALSE (default) then the function will fetch new database data to perform the query.

Course Functions

These functions deal with Moodle courses in relation to the current Moodle user.

update_enrolled_courses_cache_from_db()

This function will use the Moodle functions to find a list of courses which the Moodle user identified by member $moodle_user_cache is enrolled in. It will store an array of the integer ID's of those courses in the $enrolled_courses_cache member if successful, and return TRUE. If it fails (e.g. because the user is not recognised), then it will return FALSE.

is_user_in_course($course_id, $use_cache = FALSE)

Checks whether or not the user identified by the $moodle_user_id member is enrolled in the course identified by parameter $course_id. Returns TRUE if so, or FALSE if not (or if an error occurs).

Note: if parameter $use_cache is TRUE then the function will use the $enrolled_courses_cache member as-is to perform the check. Otherwise, it will update that cache first, and then perform the check.

This page is part of the SLOODLE documentation
Docs: Users | Administrators | Developers
Wiki Frontpage Sloodle.org