/usr/share/doc/libphp-adodb/docs-session.htm is in libphp-adodb 5.15-1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 | <!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
variable you want to keep alive for the duration of the session, use $_SESSION['variablename'].
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/session-fixation">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>
|