/program/lib/dbsessionlib.php - functions to keep PHP-sessions in the database
This file provides the functions to handle sessions via the database rather than via files or other standard PHP-mechanisms.
Useful information about storing sessions can be found in these user comments: http://php.net/manual/en/function.session-set-save-handler.php
Important issues:
Sessions are stored in a table called 'sessions'. This table is defined as follows:
session_id serial session_key varchar(172) session_data longtext user_id int unsigned user_information varchar(255) ctime datetime atime datetime primary key(session_id) foreign key(user_id) references users(user_id) unique index(session_key)
Note: the size of the session_key was reduced from 255 to 172 after version 2011051100 to prevent database problems (see update_core_2011092100()).
'close' a session that was opened with dbsession_open() before
Since this function has no way to tell _which_ session should be closed, it is utterly useless (but it has to exist to satisfy session_set_save_handler()) The function dbsession_open() has the same uselessness, so they are a perfect pair.
create a new session in the session table, return the unique sessionkey
this creates generates a new unique session key and stores it in a new record in the sessions table. Additional information is recorded in the new record too: the user_id and auxiliary information. This information makes that a session can always be linked to a particular user (which is handy when dealing with locked pages, etc.). This routine attempts to create a unique session key a number of times. If it doesn't work out, the routine returns FALSE.
the optional parameter $user_information can be used to store additional information about this user, e.g. the IP-address. This is useful for generating messages like 'Node xxx is currently locked by user YYYY logged in from ZZZZ'.
Note that the generation of a unique session key is salted with both the main url of this website and the special salt that was recorded once during installation time. Also, pseudo-random data is added via rand(). Hopefully this will be hard to guess, even though we use md5() to condense this (semi-)random information into only 128 bits.
remove a session record from the sessions table (it should still exist)
remove the specified record from the sessions table. it is an error if the record does not exist.
check to see if $session_key exists in the session table
This checks the existence of a session in the sessions table. Session keys are only generated from dbsession_create(). This prevents us accepting spurious session keys via a manipulated cookie. If the session key does not exist, the call fails and FALSE is returned.
remove all sessions that were created more than $max_life seconds ago
not only are sessions terminated when there is no more activity for $time_out seconds (@see dbsession_garbage_collection()) but also the total lifetime of a session is limited to $life_time seconds. This routine is not part of the required session handlers but it can be called periodically (@see cron.php}.
remove all sessions that are last accessed more than $time_out seconds ago, maybe even more
we have our own session expire limit in $CFG->session_expiry and we overrule the $ime_out value here (ie. we ignore the php.ini setting) A session times out after $CFG->session_expiry seconds of inactivity. Also a session is terminated twice that amount of time after the start of the session. Both checks are performed here.
retrieve the session_id (pkey) that corresponds with session_key
this is very similar to dbsession_exists(). This routine returns the actual session_id integer, whereas dbsession_exists() only returns TRUE.
'open' a session
this 'opens' a session. note that this function is unable to identify the session because it is only presented with
read the (serialised) session data from the database
workhorse for removing obsolete sessions from the database
this logs and subsequently removes obsolete sessions from the sessions table It is a workhorse function for both dbsession_garbage_collection() and dbsession_expire().
Session records are removed when the $time_field in the sessions table contains a date/time that is older than $seconds seconds ago. Before the records are removed, we retrieve them and log pertinent information from each one via logger(), for future reference.
Note that we try to continue with deleting records, even if the logging appears to have generated errors.
setup database based handlers for session management
this is basically shorthand for session_set_save_handler() this routine replaces the existing session handlers with the handlers specified below in this file.
write the (serialised) data to the database
Documentation generated on Tue, 28 Jun 2016 19:09:07 +0200 by phpDocumentor 1.4.0