ADODB Session Management Manual

This software is dual licensed using BSD-Style and LGPL. This means you can use it in compiled proprietary and commercial products.

Useful ADOdb links: Download Other Docs

Introduction

PHP is packed with good features. One of the most popular is session variables. These are variables that persist throughout a session, as the user moves from page to page. Session variables are great holders of state information and other useful stuff.

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.

The default method of storing sessions is to store it in a file. However if you have special needs such as you:

Have multiple web servers that need to share session info
Need to do special processing of each session
Require notification when a session expires

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.

ADOdb Session Handler Features

Ability to define a notification function that is called when a session expires. Typically used to detect session logout and release global resources.
Optimization of database writes. We crc32 the session data and only perform an update to the session data if there is a data change.
Support for large amounts of session data with CLOBs (see adodb-session-clob.inc.php). Useful for Oracle.
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.

Setup

There are 3 session management files that you can use:

adodb-session.inc.php        : The default
adodb-session-clob.inc.php   : Use this if you are storing DATA in clobs
adodb-cryptsession.inc.php   : Use this if you want to store encrypted session data in the database

Examples
 
 	GLOBAL $HTTP_SESSION_VARS;
	include('adodb.inc.php');
	include('adodb-session.php');
	session_start();
	session_register('AVAR');
	$HTTP_SESSION_VARS['AVAR'] += 1;
	print "\$HTTP_SESSION_VARS['AVAR']={$HTTP_SESSION_VARS['AVAR']}";
	
To force non-persistent connections, call adodb_session_open first before session_start():

 	GLOBAL $HTTP_SESSION_VARS;
	include('adodb.inc.php');
	include('adodb-session.php');
	adodb_sess_open(false,false,false);
	session_start();
	session_register('AVAR');
	$HTTP_SESSION_VARS['AVAR'] += 1;
	print "\$HTTP_SESSION_VARS['AVAR']={$HTTP_SESSION_VARS['AVAR']}";

To use a encrypted sessions, simply replace the file:

	GLOBAL $HTTP_SESSION_VARS;
	include('adodb.inc.php');
	include('adodb-cryptsession.php');
	session_start();
	
And the same technique for adodb-session-clob.inc.php:

	GLOBAL $HTTP_SESSION_VARS;
	include('adodb.inc.php');
	include('adodb-session-clob.php');
	session_start();
	
 Installation
 1. Create this table in your database (syntax might vary depending on your db):
 
  create table sessions (
	   SESSKEY char(32) not null,
	   EXPIRY int(11) unsigned not null,
	   EXPIREREF varchar(64),
	   DATA text not null,
	  primary key (sesskey)
  );
  
  For the adodb-session-clob.inc.php version, create this:
  
	create table sessions (
	   SESSKEY char(32) not null,
	   EXPIRY int(11) unsigned not null,
	   EXPIREREF varchar(64),
	   DATA CLOB,
	  primary key (sesskey)
  );

  2. Then define the following parameters. You can either modify
     this file, or define them before this file is included:
	 
  	$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'
	
  3. Recommended is PHP 4.0.6 or later. There are documented
	 session bugs in earlier versions of PHP.

    Notifications
    If you want to receive notifications when a session expires, then
    you can tag a session with an EXPIREREF tag (see the definition of
    the sessions table above), and before the session record is deleted, 
    we can call a function that will pass the contents of the EXPIREREF
    field as the first parameter, and the session key as the 2nd parameter.
	 
    To do this, define a notification function, say NotifyFn:
    
    	function NotifyFn($expireref, $sesskey)
    	{
    	}
    
    Then you need to define a global variable $ADODB_SESSION_EXPIRE_NOTIFY.
    This is an array with 2 elements, the first being the name of the variable
    you would like to store in the EXPIREREF field, and the 2nd is the 
    notification function's name.
    
    In this example, we want to be notified when a user's session 
    has expired, so we store the user id in the global variable $USERID, 
    store this value in the EXPIREREF field:
    
    	$ADODB_SESSION_EXPIRE_NOTIFY = array('USERID','NotifyFn');
    
    Then when the NotifyFn is called, we are passed the $USERID as the first
    parameter, eg. NotifyFn($userid, $sesskey).
	
	NOTE: When you want to change the EXPIREREF, you will need to modify a session
	variable to force a database record update because we checksum the session
	variables, and only perform the update when the checksum changes.

Also see the core ADOdb documentation.