egroupware/phpgwapi/inc/adodb/docs-session.htm

159 lines
6.2 KiB
HTML
Raw Normal View History

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
body,td {font-family:Arial,Helvetica,sans-serif;font-size:11pt}
pre {font-size:9pt}
.toplink {font-size:8pt}
/>
</head>
<body bgcolor="#FFFFFF">
<h3>ADODB Session Management Manual</h3>
<p>
V3.94 13 Oct 2003 (c) 2000-2003 John Lim (jlim#natsoft.com.my)
<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> &nbsp; <a href=http://php.weblogs.com/adodb_manual>Other Docs</a>
<h3>Introduction</h3>
<p>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.
<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.
<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.
<li>Support for large amounts of session data with CLOBs (see adodb-session-clob.inc.php). Useful
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>
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
<strong>Examples</strong>
GLOBAL $HTTP_SESSION_VARS;
include('adodb.inc.php');
include('adodb-session.php');
session_start();
session_register('AVAR');
$HTTP_SESSION_VARS['AVAR'] += 1;
print "<p>\$HTTP_SESSION_VARS['AVAR']={$HTTP_SESSION_VARS['AVAR']}</p>";
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 "<p>\$HTTP_SESSION_VARS['AVAR']={$HTTP_SESSION_VARS['AVAR']}</p>";
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();
<h4>Installation</h4>
1. Create this table in your database (syntax might vary depending on your db):
<a name=sessiontab></a>
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.
<h4>Notifications</h4>
If you want to receive notifications when a session expires, then
you can tag a session with an <a href="#sessiontab">EXPIREREF</a> 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.
</pre>
<p>
Also see the <a href=docs-adodb.htm>core ADOdb documentation</a>.
</body>
</html>