2003-10-19 21:05:23 +02:00
< html >
< head >
< title > ADODB Session Management Manual< / title >
< meta http-equiv = "Content-Type" content = "text/html; charset=iso-8859-1" >
< XSTYLE
2004-03-15 23:17:52 +01:00
body,td {font-family:Arial,Helvetica,sans-serif;font-size:11pt}
pre {font-size:9pt}
.toplink {font-size:8pt}
/>
< / head >
2003-10-19 21:05:23 +02:00
< body bgcolor = "#FFFFFF" >
< h3 > ADODB Session Management Manual< / h3 >
< p >
2004-07-10 09:19:40 +02:00
V4.50 6 July 2004 (c) 2000-2004 John Lim (jlim#natsoft.com.my)
2003-10-19 21:05:23 +02:00
< 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 >
2004-07-10 09:19:40 +02:00
< table border = 1 > < tr > < td > < font color = red > Kindly note that the ADOdb home page has moved to < a href = http://adodb.sourceforge.net/ > http://adodb.sourceforge.net/< / a > because of the persistent
unreliability of http://php.weblogs.com. < b > Please change your links< / b > !< / font > < / td > < tr > < / table >
< p > Useful ADOdb links: < a href = http://adodb.sourceforge.net/#download > Download< / a > < a href = http://adodb.sourceforge.net/#docs > Other Docs< / a >
2003-10-19 21:05:23 +02:00
< h3 > Introduction< / h3 >
2004-03-15 23:17:52 +01:00
< 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.
2003-10-19 21:05:23 +02:00
< 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.
2004-03-15 23:17:52 +01:00
< 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.
2003-10-19 21:05:23 +02:00
< 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.
2004-03-15 23:17:52 +01:00
< li > Support for large amounts of session data with CLOBs (see adodb-session-clob.php). Useful
2003-10-19 21:05:23 +02:00
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 >
2004-03-15 23:17:52 +01:00
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
2003-10-19 21:05:23 +02:00
< strong > Examples< / strong >
2004-03-15 23:17:52 +01:00
< 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 >
2003-10-19 21:05:23 +02:00
To force non-persistent connections, call adodb_session_open first before session_start():
2004-03-15 23:17:52 +01:00
< 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>
2003-10-19 21:05:23 +02:00
To use a encrypted sessions, simply replace the file:
2004-03-15 23:17:52 +01:00
< 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 >
2003-10-19 21:05:23 +02:00
< h4 > Installation< / h4 >
1. Create this table in your database (syntax might vary depending on your db):
2004-03-15 23:17:52 +01:00
< a name = sessiontab > < / a > < font color = #004040 >
2003-10-19 21:05:23 +02:00
create table sessions (
2004-03-15 23:17:52 +01:00
SESSKEY char(32) not null,
EXPIRY int(11) unsigned not null,
EXPIREREF varchar(64),
DATA text not null,
primary key (sesskey)
);< / font >
2003-10-19 21:05:23 +02:00
2004-03-15 23:17:52 +01:00
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 >
2003-10-19 21:05:23 +02:00
2. Then define the following parameters. You can either modify
this file, or define them before this file is included:
2004-03-15 23:17:52 +01:00
< 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.
2003-10-19 21:05:23 +02:00
2004-03-15 23:17:52 +01:00
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
2003-10-19 21:05:23 +02:00
you would like to store in the EXPIREREF field, and the 2nd is the
notification function's name.
2004-03-15 23:17:52 +01:00
< 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 >
2004-06-08 16:09:55 +02:00
NOTE 1: If you have register_globals disabled in php.ini, then you will have to
manually set the EXPIREREF. E.g.
< pre > < font color = #004040 >
$GLOBALS['USERID'] =& $_SESSION['USERID'];
$ADODB_SESSION_EXPIRE_NOTIFY = array('USERID','NotifyFn');
< / font > < / pre >
2004-03-15 23:17:52 +01:00
< p >
2004-06-08 16:09:55 +02:00
NOTE 2: If you want to change the EXPIREREF after the session record has been
2004-03-15 23:17:52 +01:00
created, you will need to modify any session variable to force a database
record update.
2004-06-08 16:09:55 +02:00
< h4 > Neat Notification Tricks< / h4 >
< p > < i > ExpireRef< / i > normally holds the user id of the current session.
< p >
1. You can then write a session monitor, scanning expireref to see
who is currently logged on.
< p >
2. If you delete the sessions record for a specific user, eg.
< pre >
delete from sessions where expireref = '$USER'
< / pre >
then the user is logged out. Useful for ejecting someone from a
site.
< p >
3. You can scan the sessions table to ensure no user
can be logged in twice. Useful for security reasons.
< p >
< h3 > Compression/Encryption Schemes< / h3 >
2004-03-15 23:17:52 +01:00
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());
2003-10-19 21:05:23 +02:00
< / pre >
2004-03-15 23:17:52 +01:00
will compress and then encrypt the record in the database.
2003-10-19 21:05:23 +02:00
< p >
Also see the < a href = docs-adodb.htm > core ADOdb documentation< / a > .
< / body >
< / html >
