diff options
Diffstat (limited to 'trunk/adodb5/docs-session.htm')
| -rw-r--r-- | trunk/adodb5/docs-session.htm | 343 |
1 files changed, 0 insertions, 343 deletions
diff --git a/trunk/adodb5/docs-session.htm b/trunk/adodb5/docs-session.htm deleted file mode 100644 index dcf97e08..00000000 --- a/trunk/adodb5/docs-session.htm +++ /dev/null @@ -1,343 +0,0 @@ -<!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.18 3 Sep 2012 (c) 2000-2012 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/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> |