ADODB Session Management Manual

V3.60 16 June 2003 (c) 2000-2003 John Lim (jlim#natsoft.com.my)

This software is dual licensed using BSD-Style and LGPL. Where there is any discrepancy, the BSD-Style license will take precedence. This means you can use it in proprietary and commercial products.

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 multiple web servers, or need to do special processing of each session, or require notification when a session expires, you need to override the default session storage behaviour.

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 by multiple servers.

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 in this file:
  	$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.

  4. If you want to receive notifications when a session expires, then
  	 you can tag a session with an EXPIREREF, and before the session
	 record is deleted, we can call a function that will pass the EXPIREREF
	 as the first parameter, and the session key as the second parameter.
	 
	 To do this, define a notification function, say NotifyFn:
	 
	 	function NotifyFn($expireref, $sesskey)
	 	{
	 	}
	 
	 Then define a global variable, with the first parameter being the
	 global variable you would like to store in the EXPIREREF field, and
	 the second is the function name.
	 
	 In this example, we want to be notified when a user's session 
	 has expired, so we store the user id in $USERID, and make this
	 the value stored in the EXPIREREF field:
	 
	 	$ADODB_SESSION_EXPIRE_NOTIFY = array('USERID','NotifyFn');

Also see the core ADOdb documentation.