<html> <head> <title>ADODB Session Management Manual</title> <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> <XSTYLE body,td {font-family:Arial,Helvetica,sans-serif;font-size:11pt} pre {font-size:9pt} .toplink {font-size:8pt} /> </head> <body bgcolor="#FFFFFF"> <h3>ADODB Session Management Manual</h3> <p> V4.20 22 Feb 2004 (c) 2000-2004 John Lim (jlim#natsoft.com.my) <p> <font size=1>This software is dual licensed using BSD-Style and LGPL. This means you can use it in compiled proprietary and commercial products. </font> <p>Useful ADOdb links: <a href=http://php.weblogs.com/adodb>Download</a> <a href=http://php.weblogs.com/adodb_manual>Other Docs</a> <h3>Introduction</h3> <p> We store state information specific to a user or web client in session variables. These session variables persist throughout a session, as the user moves from page to page. <p> To use session variables, call session_start() at the beginning of your web page, before your HTTP headers are sent. Then for every variable you want to keep alive for the duration of the session, call session_register($variable_name). By default, the session handler will keep track of the session by using a cookie. You can save objects or arrays in session variables also. <p>The default method of storing sessions is to store it in a file. However if you have special needs such as you: <ul> <li>Have multiple web servers that need to share session info</li> <li>Need to do special processing of each session</li> <li>Require notification when a session expires</li> </ul> <p>Then the ADOdb session handler provides you with the above additional capabilities by storing the session information as records in a database table that can be shared across multiple servers. <p><b>Important Upgrade Notice:</b> Since ADOdb 4.05, the session files have been moved to its own folder, adodb/session. This is a rewrite of the session code by Ross Smith. The old session code is in adodb/session/old. <h4>ADOdb Session Handler Features</h4> <ul> <li>Ability to define a notification function that is called when a session expires. Typically used to detect session logout and release global resources. <li>Optimization of database writes. We crc32 the session data and only perform an update to the session data if there is a data change. <li>Support for large amounts of session data with CLOBs (see adodb-session-clob.php). Useful for Oracle. <li>Support for encrypted session data, see adodb-cryptsession.inc.php. Enabling encryption is simply a matter of including adodb-cryptsession.inc.php instead of adodb-session.inc.php. </ul> <h3>Setup</h3> <p>There are 3 session management files that you can use: <pre> adodb-session.php : The default adodb-session-clob.php : Use this if you are storing DATA in clobs adodb-cryptsession.php : Use this if you want to store encrypted session data in the database <strong>Examples</strong> <font color=#004040> include('adodb/adodb.inc.php'); <b> $ADODB_SESSION_DRIVER='mysql'; $ADODB_SESSION_CONNECT='localhost'; $ADODB_SESSION_USER ='scott'; $ADODB_SESSION_PWD ='tiger'; $ADODB_SESSION_DB ='sessiondb';</b> <b>include('adodb/session/adodb-session.php');</b> session_start(); # # Test session vars, the following should increment on refresh # $_SESSION['AVAR'] += 1; print "<p>\$_SESSION['AVAR']={$_SESSION['AVAR']}</p>"; </font> To force non-persistent connections, call adodb_session_open first before session_start(): <font color=#004040> include('adodb/adodb.inc.php'); <b> $ADODB_SESSION_DRIVER='mysql'; $ADODB_SESSION_CONNECT='localhost'; $ADODB_SESSION_USER ='scott'; $ADODB_SESSION_PWD ='tiger'; $ADODB_SESSION_DB ='sessiondb';</b> <b>include('adodb/session/adodb-session.php'); adodb_sess_open(false,false,false);</b> session_start(); </font color=#004040> To use a encrypted sessions, simply replace the file: <font color=#004040> include('adodb/adodb.inc.php'); <b> $ADODB_SESSION_DRIVER='mysql'; $ADODB_SESSION_CONNECT='localhost'; $ADODB_SESSION_USER ='scott'; $ADODB_SESSION_PWD ='tiger'; $ADODB_SESSION_DB ='sessiondb'; include('adodb/session/adodb-cryptsession.php');</b> session_start(); </font> And the same technique for adodb-session-clob.php: <font color=#004040> include('adodb/adodb.inc.php'); <b> $ADODB_SESSION_DRIVER='mysql'; $ADODB_SESSION_CONNECT='localhost'; $ADODB_SESSION_USER ='scott'; $ADODB_SESSION_PWD ='tiger'; $ADODB_SESSION_DB ='sessiondb'; include('adodb/session/adodb-session-clob.php');</b> session_start(); </font> <h4>Installation</h4> 1. Create this table in your database (syntax might vary depending on your db): <a name=sessiontab></a> <font color=#004040> create table sessions ( SESSKEY char(32) not null, EXPIRY int(11) unsigned not null, EXPIREREF varchar(64), DATA text not null, primary key (sesskey) );</font> For the adodb-session-clob.php version, create this: <font color=#004040> create table sessions ( SESSKEY char(32) not null, EXPIRY int(11) unsigned not null, EXPIREREF varchar(64), DATA CLOB, primary key (sesskey) );</font> 2. Then define the following parameters. You can either modify this file, or define them before this file is included: <font color=#004040> $ADODB_SESSION_DRIVER='database driver, eg. mysql or ibase'; $ADODB_SESSION_CONNECT='server to connect to'; $ADODB_SESSION_USER ='user'; $ADODB_SESSION_PWD ='password'; $ADODB_SESSION_DB ='database'; $ADODB_SESSION_TBL = 'sessions'; # setting this is optional </font> When the session is created, $<b>ADODB_SESS_CONN</b> holds the connection object. 3. Recommended is PHP 4.0.6 or later. There are documented session bugs in earlier versions of PHP. </pre> <h3>Notifications</h3> <p>If you want to receive notification when a session expires, then tag the session record with a <a href="#sessiontab">EXPIREREF</a> tag (see the definition of the sessions table above). Before any session record is deleted, ADOdb will call a notification function, passing in the EXPIREREF. <p> When a session is first created, we check a global variable $ADODB_SESSION_EXPIRE_NOTIFY. This is an array with 2 elements, the first being the name of the session variable you would like to store in the EXPIREREF field, and the 2nd is the notification function's name. <p> Suppose we want to be notified when a user's session has expired, based on the userid. The user id in the global session variable $USERID. The function name is 'NotifyFn'. So we define: <pre> <font color=#004040> $ADODB_SESSION_EXPIRE_NOTIFY = array('USERID','NotifyFn'); </font></pre> And when the NotifyFn is called (when the session expires), we pass the $USERID as the first parameter, eg. NotifyFn($userid, $sesskey). The session key (which is the primary key of the record in the sessions table) is the 2nd parameter. <p> Here is an example of a Notification function that deletes some records in the database and temporary files: <pre><font color=#004040> function NotifyFn($expireref, $sesskey) { global $ADODB_SESS_CONN; # the session connection object $user = $ADODB_SESS_CONN->qstr($expireref); $ADODB_SESS_CONN->Execute("delete from shopping_cart where user=$user"); system("rm /work/tmpfiles/$expireref/*"); }</font> </pre> <p> <p> NOTE: If you want to change the EXPIREREF after the session record has been created, you will need to modify any session variable to force a database record update. <h4>Compression/Encryption Schemes</h4> Since ADOdb 4.05, thanks to Ross Smith, multiple encryption and compression schemes are supported. Currently, supported: <pre> MD5Crypt (crypt.inc.php) MCrypt Secure (Horde's emulation of MCrypt, if MCrypt module is not available.) GZip BZip2 </pre> These are stackable. E.g. <pre> ADODB_Session::filter(new ADODB_Compress_Bzip2()); ADODB_Session::filter(new ADODB_Encrypt_MD5()); </pre> will compress and then encrypt the record in the database. <p> Also see the <a href=docs-adodb.htm>core ADOdb documentation</a>. </body> </html>