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-03-15 23:17:52 +01:00
|
|
|
V4.20 22 Feb 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>
|
|
|
|
|
<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>
|
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>
|
|
|
|
|
|
|
|
|
|
<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());
|
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>
|
