343 lines
15 KiB
HTML
343 lines
15 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<html>
|
|
<head>
|
|
<title>ADODB Session Management Manual</title>
|
|
<meta http-equiv="Content-Type"
|
|
content="text/html; charset=iso-8859-1">
|
|
<style type="text/css">
|
|
body, td {
|
|
/*font-family: Arial, Helvetica, sans-serif;*/
|
|
font-size: 11pt;
|
|
}
|
|
pre {
|
|
font-size: 9pt;
|
|
background-color: #EEEEEE; padding: .5em; margin: 0px;
|
|
}
|
|
.toplink {
|
|
font-size: 8pt;
|
|
}
|
|
</style>
|
|
</head>
|
|
<body style="background-color: rgb(255, 255, 255);">
|
|
<h1>ADODB Session 2 Management Manual</h1>
|
|
<p>
|
|
V5.11 5 May 2010 (c) 2000-2010 John Lim (jlim#natsoft.com)
|
|
</p>
|
|
<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://adodb.sourceforge.net/#download">Download</a>
|
|
<a href="http://adodb.sourceforge.net/#docs">Other Docs</a>
|
|
</p>
|
|
<h2>Introduction</h2>
|
|
<p> This document discusses the newer session handler adodb-session2.php. If
|
|
you have used the older adodb-session.php, then be forewarned that you will
|
|
need to alter your session table format. Otherwise everything is <a href="#compat">backward
|
|
compatible</a>.
|
|
Here are the <a href="docs-session.old.htm">older
|
|
docs</a> for
|
|
adodb-session.php.</p>
|
|
<h2>Why Session Variables in a Database? </h2>
|
|
<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>
|
|
<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>
|
|
<p>The default method of storing sessions is to store it in a file.
|
|
However if you have special needs such as you:
|
|
</p>
|
|
<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>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>
|
|
<p>These records will be garbage collected based on the php.ini [session] timeout settings.
|
|
You can register a notification function to notify you when the record has expired and
|
|
is about to be freed by the garbage collector.</p>
|
|
<p>An alternative to using a database backed session handler is to use <a href="http://www.danga.com/memcached/">memcached</a>.
|
|
This is a distributed memory based caching system suitable for storing session
|
|
information.
|
|
</p>
|
|
<h2> The Improved Session Handler</h2>
|
|
<p>In ADOdb 4.91, we added a new session handler, in adodb-session2.php.
|
|
It features the following improvements:
|
|
<ul>
|
|
<li>Fully supports server farms using a new database table format. The
|
|
previous version used the web server time for timestamps, which can cause problems
|
|
on a system with multiple web servers with possibly inconsistent
|
|
times. The new version uses the database server time instead for all timestamps.
|
|
<li>The older database table format is obsolete. The database table must be modified
|
|
to support storage of the database server time mentioned above. Also the field
|
|
named DATA has been changed to SESSDATA. In some databases, DATA is a reserved
|
|
word.
|
|
<li>The functions dataFieldName() and syncSeconds() is obsolete.
|
|
</ul>
|
|
|
|
<p>Usage is
|
|
|
|
<pre>
|
|
include_once("adodb/session/adodb-session2.php");
|
|
ADOdb_Session::config($driver, $host, $user, $password, $database,$options=false);
|
|
session_start();
|
|
|
|
<font
|
|
color="#004040">#<br># Test session vars, the following should increment on refresh<br>#<br>$_SESSION['AVAR'] += 1;<br>print "<p>\$_SESSION['AVAR']={$_SESSION['AVAR']}</p>";</font>
|
|
</pre>
|
|
|
|
<p>When the session is created in session_start( ), the global variable $<b>ADODB_SESS_CONN</b> holds
|
|
the connection object.
|
|
<p>The default name of the table is sessions2. If you want to override it:
|
|
|
|
<pre>
|
|
include_once("adodb/session/adodb-session2.php");
|
|
$options['table'] = 'mytablename';
|
|
ADOdb_Session::config($driver, $host, $user, $password, $database,$options);
|
|
session_start();
|
|
</pre>
|
|
|
|
|
|
<h3>ADOdb Session Handler Features</h3>
|
|
<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>
|
|
<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>
|
|
<li>Support for large amounts of session data with CLOBs (see
|
|
adodb-session-clob2.php). Useful
|
|
for Oracle. </li>
|
|
<li>Support for encrypted session data, see
|
|
adodb-cryptsession2.php. Enabling encryption is simply a matter of
|
|
including adodb-cryptsession2.php instead of adodb-session2.php. </li>
|
|
</ul>
|
|
<h3>Session Handler Files </h3>
|
|
<p>There are 3 session management files that you can use:
|
|
</p>
|
|
<pre>adodb-session2.php : The default<br>adodb-cryptsession2.php : Use this if you want to store encrypted session data in the database<br>adodb-session-clob2.php : Use this if you are storing DATA in clobs and you are NOT using oci8 driver</pre>
|
|
<h2><strong>Usage Examples</strong></h2>
|
|
<p>To force non-persistent connections, call <font color="#004040"><b>Persist</b></font>() first before session_start():
|
|
|
|
|
|
<pre>
|
|
<font color="#004040">
|
|
include_once("adodb/session/adodb-session2.php");
|
|
$driver = 'mysql'; $host = 'localhost'; $user = 'auser'; $pwd = 'secret'; $database = 'sessiondb';
|
|
ADOdb_Session::config($driver, $host, $user, $password, $database, $options=false);<b><br>ADOdb_session::Persist($connectMode=false);</b>
|
|
session_start();<br>
|
|
|
|
# or, using DSN support so you can set other options such as port (since 5.11)
|
|
include_once("adodb/session/adodb-session2.php");
|
|
$dsn = 'mysql://root:pwd@localhost/mydb?persist=1&port=5654';
|
|
ADOdb_Session::config($dsn, '', '', '');
|
|
session_start();
|
|
</font></pre>
|
|
<p> The parameter to the Persist( ) method sets the connection mode. You can
|
|
pass the following:</p>
|
|
<table width="50%" border="1">
|
|
<tr>
|
|
<td><b>$connectMode</b></td>
|
|
<td><b>Connection Method</b></td>
|
|
</tr>
|
|
<tr>
|
|
<td>true</td>
|
|
<td><p>PConnect( )</p></td>
|
|
</tr>
|
|
<tr>
|
|
<td>false</td>
|
|
<td>Connect( )</td>
|
|
</tr>
|
|
<tr>
|
|
<td>'N'</td>
|
|
<td>NConnect( )</td>
|
|
</tr>
|
|
<tr>
|
|
<td>'P'</td>
|
|
<td>PConnect( )</td>
|
|
</tr>
|
|
<tr>
|
|
<td>'C'</td>
|
|
<td>Connect( )</td>
|
|
</tr>
|
|
</table>
|
|
<p>To use a encrypted sessions, simply replace the file adodb-session2.php:</p>
|
|
<pre> <font
|
|
color="#004040"><b><br>include('adodb/session/adodb-cryptsession2.php');</b><br>$driver = 'mysql'; $host = 'localhost'; $user = 'auser'; $pwd = 'secret'; $database = 'sessiondb';
|
|
ADOdb_Session::config($driver, $host, $user, $password, $database,$options=false);<b><br>adodb_sess_open(false,false,$connectMode=false);</b>
|
|
session_start();<br></font></pre>
|
|
<p>And the same technique for adodb-session-clob2.php:</p>
|
|
<pre> <font
|
|
color="#004040"><br><b>include('adodb/session/adodb-session2-clob2.php');</b><br>$driver = 'oci8'; $host = 'localhost'; $user = 'auser'; $pwd = 'secret'; $database = 'sessiondb';
|
|
ADOdb_Session::config($driver, $host, $user, $password, $database,$options=false);<b><br>adodb_sess_open(false,false,$connectMode=false);</b>
|
|
session_start();</font></pre>
|
|
<h2>Installation</h2>
|
|
<p>1. Create this table in your database. Here is the MySQL version:
|
|
<pre> <a
|
|
name="sessiontab"></a> <font color="#004040">
|
|
CREATE TABLE sessions2(
|
|
sesskey VARCHAR( 64 ) NOT NULL DEFAULT '',
|
|
expiry DATETIME NOT NULL ,
|
|
expireref VARCHAR( 250 ) DEFAULT '',
|
|
created DATETIME NOT NULL ,
|
|
modified DATETIME NOT NULL ,
|
|
sessdata LONGTEXT,
|
|
PRIMARY KEY ( sesskey ) ,
|
|
INDEX sess2_expiry( expiry ),
|
|
INDEX sess2_expireref( expireref )
|
|
)</font></pre>
|
|
|
|
<p> For PostgreSQL, use:
|
|
<pre>CREATE TABLE sessions2(
|
|
sesskey VARCHAR( 64 ) NOT NULL DEFAULT '',
|
|
expiry TIMESTAMP NOT NULL ,
|
|
expireref VARCHAR( 250 ) DEFAULT '',
|
|
created TIMESTAMP NOT NULL ,
|
|
modified TIMESTAMP NOT NULL ,
|
|
sessdata TEXT DEFAULT '',
|
|
PRIMARY KEY ( sesskey )
|
|
);
|
|
</pre>
|
|
<pre>create INDEX sess2_expiry on sessions2( expiry );
|
|
create INDEX sess2_expireref on sessions2 ( expireref );</pre>
|
|
<p>Here is the Oracle definition, which uses a CLOB for the SESSDATA field:
|
|
<pre>
|
|
<font
|
|
color="#004040">CREATE TABLE SESSIONS2<br>(<br> SESSKEY VARCHAR2(48 BYTE) NOT NULL,<br> EXPIRY DATE NOT NULL,<br> EXPIREREF VARCHAR2(200 BYTE),<br> CREATED DATE NOT NULL,<br> MODIFIED DATE NOT NULL,<br> SESSDATA CLOB,<br> PRIMARY KEY(SESSKEY)<br>);
|
|
<br>CREATE INDEX SESS2_EXPIRY ON SESSIONS2(EXPIRY);
|
|
CREATE INDEX SESS2_EXPIREREF ON SESSIONS2(EXPIREREF);</font></pre>
|
|
<p> We need to use a CLOB here because for text greater than 4000 bytes long,
|
|
Oracle requires you to use the CLOB data type. If you are using the oci8 driver,
|
|
ADOdb will automatically enable CLOB handling. So you can use either adodb-session2.php
|
|
or adodb-session-clob2.php - in this case it doesn't matter. <br>
|
|
<h2>Notifications</h2>
|
|
<p>You can receive notification when your session is cleaned up by the session garbage collector or
|
|
when you call session_destroy().
|
|
<p>PHP's session extension will automatically run a special garbage collection function based on
|
|
your php.ini session.cookie_lifetime and session.gc_probability settings. This will in turn call
|
|
adodb's garbage collection function, which can be setup to do notification.
|
|
<p>
|
|
<pre>
|
|
PHP Session --> ADOdb Session --> Find all recs --> Send --> Delete queued
|
|
GC Function GC Function to be deleted notification records
|
|
executed at called by for all recs
|
|
random time Session Extension queued for deletion
|
|
</pre>
|
|
<p>When a session is created, we need to store a value in the session record (in the EXPIREREF field), typically
|
|
the userid of the session. Later when the session has expired, just before the record is deleted,
|
|
we reload the EXPIREREF field and call the notification function with the value of EXPIREREF, which
|
|
is the userid of the person being logged off.
|
|
<p>ADOdb uses a global variable $ADODB_SESSION_EXPIRE_NOTIFY that you must predefine before session
|
|
start to store the notification configuration.
|
|
$ADODB_SESSION_EXPIRE_NOTIFY 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>
|
|
<p>For example, suppose we want to be notified when a user's session has expired,
|
|
based on the userid. When the user logs in, we store the id in the global session variable
|
|
$USERID. The function name is 'NotifyFn'.
|
|
<p>
|
|
So we define (before session_start() is called): </p>
|
|
<pre> <font color="#004040">
|
|
$ADODB_SESSION_EXPIRE_NOTIFY = array('USERID','NotifyFn');
|
|
</font></pre>
|
|
And when the NotifyFn is called (when the session expires), the
|
|
$EXPIREREF holding the user id is passed in 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: </p>
|
|
<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> NOTE 1: If you have register_globals disabled in php.ini, then you
|
|
will have to manually set the EXPIREREF. E.g. </p>
|
|
<pre> <font color="#004040">
|
|
$GLOBALS['USERID'] = GetUserID();
|
|
$ADODB_SESSION_EXPIRE_NOTIFY = array('USERID','NotifyFn');</font>
|
|
</pre>
|
|
<p> NOTE 2: 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.
|
|
</p>
|
|
<h3>Neat Notification Tricks</h3>
|
|
<p><i>ExpireRef</i> normally holds the user id of the current session.
|
|
</p>
|
|
<p>1. You can then write a session monitor, scanning expireref to see
|
|
who is currently logged on.
|
|
</p>
|
|
<p>2. If you delete the sessions record for a specific user, eg.
|
|
</p>
|
|
<pre>delete from sessions where expireref = '$USER'<br></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>
|
|
<h2>Compression/Encryption Schemes</h2>
|
|
Since ADOdb 4.05, thanks to Ross Smith, multiple encryption and
|
|
compression schemes are supported. Currently, supported are:
|
|
<p>
|
|
<pre> MD5Crypt (crypt.inc.php)<br> MCrypt<br> Secure (Horde's emulation of MCrypt, if MCrypt module is not available.)<br> GZip<br> BZip2<br></pre>
|
|
<p>These are stackable. E.g.
|
|
<pre>ADODB_Session::filter(new ADODB_Compress_Bzip2());<br>ADODB_Session::filter(new ADODB_Encrypt_MD5());<br></pre>
|
|
will compress and then encrypt the record in the database.
|
|
<h2>Session Cookie Regeneration: adodb_session_regenerate_id()</h2>
|
|
<p>Dynamically change the current session id with a newly generated one and update
|
|
database. Currently only works with cookies. Useful to improve security by
|
|
reducing the risk of session-hijacking. See this article on <a href=http://shiflett.org/articles/security-corner-feb2004>Session
|
|
Fixation</a> for more info
|
|
on the theory behind this feature. Usage:<pre>
|
|
include('path/to/adodb/session/adodb-session2.php');
|
|
|
|
session_start();
|
|
# Approximately every 10 page loads, reset cookie for safety.
|
|
# This is extremely simplistic example, better
|
|
# to regenerate only when the user logs in or changes
|
|
# user privilege levels.
|
|
if ((rand()%10) == 0) adodb_session_regenerate_id();
|
|
</pre>
|
|
<p>This function calls session_regenerate_id() internally or simulates it if the function does not exist.
|
|
<h2>Vacuum/Optimize Database</h2>
|
|
<p>During session garbage collection, if postgresql is detected,
|
|
ADOdb can be set to run VACUUM. If mysql is detected, then optimize database
|
|
could be called.You can turn this on or off using:</p>
|
|
<pre>$turnOn = true; # or false
|
|
ADODB_Session::optimize($turnOn);
|
|
</pre>
|
|
<p>The default is optimization is disabled.</p>
|
|
<h2><a name=compat></a>Backwards Compatability </h2>
|
|
<p>The older method of connecting to ADOdb using global variables is still supported:</p>
|
|
<pre> $ADODB_SESSION_DRIVER='mysql';
|
|
$ADODB_SESSION_CONNECT='localhost';
|
|
$ADODB_SESSION_USER ='root';
|
|
$ADODB_SESSION_PWD ='abc';
|
|
$ADODB_SESSION_DB ='phplens';
|
|
|
|
include('path/to/adodb/session/adodb-<strong>session2</strong>.php'); </pre>
|
|
<p>In the above example, the only things you need to change in your code to upgrade
|
|
is </p>
|
|
<ul>
|
|
<li>your session table format to the new one.</li>
|
|
<li>the include file from adodb-session.php to adodb-session2.php. </li>
|
|
</ul>
|
|
<h2>More Info</h2>
|
|
<p>Also see the <a href="docs-adodb.htm">core ADOdb documentation</a>. And if
|
|
you are interested in the obsolete adodb-session.php, see <a href="docs-session.old.htm">old
|
|
session documentation</a>. </p>
|
|
</body>
|
|
</html>
|