library/adodb/docs-session.htm

   1 <html>
   2 <head>
   3 <title>ADODB Session Management Manual</title>
   4 <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
   5 <XSTYLE
   6     body,td {font-family:Arial,Helvetica,sans-serif;font-size:11pt}
   7     pre {font-size:9pt}
   8     .toplink {font-size:8pt}
   9     />
  10 </head>
  11 <body bgcolor="#FFFFFF">
  12 <h3>ADODB Session Management Manual</h3>
  13 <p>
  14 V4.20 22 Feb 2004 (c) 2000-2004 John Lim (jlim#natsoft.com.my)
  15 <p> <font size=1>This software is dual licensed using BSD-Style and LGPL. This
  16   means you can use it in compiled proprietary and commercial products. </font>
  17 <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>
  18
  19 <h3>Introduction</h3>
  20 <p>
  21 We store state information specific to a user or web client in session variables. These session variables
  22  persist throughout a session, as the user moves from page to page.
  23 <p>
  24 To use session variables, call session_start() at the beginning of your web page,
  25 before your HTTP headers are sent. Then for every variable you want to keep alive
  26 for the duration of the session, call session_register($variable_name). By default,
  27 the session handler will keep track of the session by using a cookie. You can save objects
  28  or arrays in session variables also.
  29 <p>The default method of storing sessions is to store it in a file. However if
  30   you have special needs such as you:
  31 <ul>
  32   <li>Have multiple web servers that need to share session info</li>
  33   <li>Need to do special processing of each session</li>
  34   <li>Require notification when a session expires</li>
  35 </ul>
  36 <p>Then the ADOdb session handler provides you with the above additional capabilities
  37   by storing the session information as records in a database table that can be
  38   shared across multiple servers.
  39 <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
  40 of the session code by Ross Smith. The old session code is in adodb/session/old.
  41 <h4>ADOdb Session Handler Features</h4>
  42 <ul>
  43 <li>Ability to define a notification function that is called when a session expires. Typically
  44 used to detect session logout and release global resources.
  45 <li>Optimization of database writes. We crc32 the session data and only perform an update
  46 to the session data if there is a data change.
  47 <li>Support for large amounts of session data with CLOBs (see adodb-session-clob.php). Useful
  48 for Oracle.
  49 <li>Support for encrypted session data, see adodb-cryptsession.inc.php. Enabling encryption
  50 is simply a matter of including adodb-cryptsession.inc.php instead of adodb-session.inc.php.
  51 </ul>
  52 <h3>Setup</h3>
  53 <p>There are 3 session management files that you can use:
  54 <pre>
  55 adodb-session.php        : The default
  56 adodb-session-clob.php   : Use this if you are storing DATA in clobs
  57 adodb-cryptsession.php   : Use this if you want to store encrypted session data in the database
  58
  59 <strong>Examples</strong>
  60  <font color=#004040>
  61     include('adodb/adodb.inc.php');
  62
  63 <b>    $ADODB_SESSION_DRIVER='mysql';
  64     $ADODB_SESSION_CONNECT='localhost';
  65     $ADODB_SESSION_USER ='scott';
  66     $ADODB_SESSION_PWD ='tiger';
  67     $ADODB_SESSION_DB ='sessiondb';</b>
  68
  69     <b>include('adodb/session/adodb-session.php');</b>
  70     session_start();
  71
  72     #
  73     # Test session vars, the following should increment on refresh
  74     #
  75     $_SESSION['AVAR'] += 1;
  76     print "&lt;p>\$_SESSION['AVAR']={$_SESSION['AVAR']}&lt;/p>";
  77 </font>
  78 To force non-persistent connections, call adodb_session_open first before session_start():
  79  <font color=#004040>
  80     include('adodb/adodb.inc.php');
  81
  82 <b>    $ADODB_SESSION_DRIVER='mysql';
  83     $ADODB_SESSION_CONNECT='localhost';
  84     $ADODB_SESSION_USER ='scott';
  85     $ADODB_SESSION_PWD ='tiger';
  86     $ADODB_SESSION_DB ='sessiondb';</b>
  87
  88     <b>include('adodb/session/adodb-session.php');
  89     adodb_sess_open(false,false,false);</b>
  90     session_start();
  91  </font color=#004040>
  92 To use a encrypted sessions, simply replace the file:
  93  <font color=#004040>
  94     include('adodb/adodb.inc.php');
  95
  96 <b>    $ADODB_SESSION_DRIVER='mysql';
  97     $ADODB_SESSION_CONNECT='localhost';
  98     $ADODB_SESSION_USER ='scott';
  99     $ADODB_SESSION_PWD ='tiger';
 100     $ADODB_SESSION_DB ='sessiondb';
 101
 102     include('adodb/session/adodb-cryptsession.php');</b>
 103     session_start();
 104     </font>
 105 And the same technique for adodb-session-clob.php:
 106  <font color=#004040>
 107     include('adodb/adodb.inc.php');
 108
 109 <b>    $ADODB_SESSION_DRIVER='mysql';
 110     $ADODB_SESSION_CONNECT='localhost';
 111     $ADODB_SESSION_USER ='scott';
 112     $ADODB_SESSION_PWD ='tiger';
 113     $ADODB_SESSION_DB ='sessiondb';
 114
 115     include('adodb/session/adodb-session-clob.php');</b>
 116     session_start();
 117     </font>
 118  <h4>Installation</h4>
 119  1. Create this table in your database (syntax might vary depending on your db):
 120  <a name=sessiontab></a> <font color=#004040>
 121   create table sessions (
 122        SESSKEY char(32) not null,
 123        EXPIRY int(11) unsigned not null,
 124        EXPIREREF varchar(64),
 125        DATA text not null,
 126       primary key (sesskey)
 127   );</font>
 128
 129   For the adodb-session-clob.php version, create this:
 130    <font color=#004040>
 131     create table sessions (
 132        SESSKEY char(32) not null,
 133        EXPIRY int(11) unsigned not null,
 134        EXPIREREF varchar(64),
 135        DATA CLOB,
 136       primary key (sesskey)
 137   );</font>
 138
 139   2. Then define the following parameters. You can either modify
 140      this file, or define them before this file is included:
 141       <font color=#004040>
 142     $ADODB_SESSION_DRIVER='database driver, eg. mysql or ibase';
 143     $ADODB_SESSION_CONNECT='server to connect to';
 144     $ADODB_SESSION_USER ='user';
 145     $ADODB_SESSION_PWD ='password';
 146     $ADODB_SESSION_DB ='database';
 147     $ADODB_SESSION_TBL = 'sessions'; # setting this is optional
 148         </font>
 149     When the session is created, $<b>ADODB_SESS_CONN</b> holds the connection object.
 150
 151   3. Recommended is PHP 4.0.6 or later. There are documented session bugs
 152   in earlier versions of PHP.
 153 </pre>
 154
 155     <h3>Notifications</h3>
 156 <p>If you want to receive notification when a session expires, then
 157      tag the session record with a <a href="#sessiontab">EXPIREREF</a> tag (see the
 158     definition of the sessions table above).  Before any session record is deleted,
 159         ADOdb will call a notification function, passing in the EXPIREREF.
 160 <p>
 161 When a session is first created, we check a global variable $ADODB_SESSION_EXPIRE_NOTIFY.
 162     This is an array with 2 elements, the first being the name of the session variable
 163     you would like to store in the EXPIREREF field, and the 2nd is the
 164     notification function's name.
 165         <p>
 166          Suppose we want to be notified when a user's session
 167     has expired, based on the userid. The user id in the global session variable $USERID.
 168         The function name is 'NotifyFn'. So we define:
 169     <pre> <font color=#004040>
 170         $ADODB_SESSION_EXPIRE_NOTIFY = array('USERID','NotifyFn');
 171     </font></pre>
 172     And when the NotifyFn is called (when the session expires), we pass the $USERID
 173     as the first parameter, eg. NotifyFn($userid, $sesskey). The session key (which is
 174         the primary key of the record in the sessions table) is the 2nd parameter.
 175   <p>
 176     Here is an example of a Notification function that deletes some records in the database
 177         and temporary files:
 178     <pre><font color=#004040>
 179         function NotifyFn($expireref, $sesskey)
 180         {
 181         global $ADODB_SESS_CONN; # the session connection object
 182
 183           $user = $ADODB_SESS_CONN->qstr($expireref);
 184           $ADODB_SESS_CONN->Execute("delete from shopping_cart where user=$user");
 185           system("rm /work/tmpfiles/$expireref/*");
 186         }</font>
 187     </pre>
 188         <p>
 189
 190     <p>
 191     NOTE: If you want to change the EXPIREREF after the session record has been
 192     created, you will need to modify any session variable to force a database
 193     record update.
 194 <h4>Compression/Encryption Schemes</h4>
 195 Since ADOdb 4.05, thanks to Ross Smith,  multiple encryption and compression schemes are supported.
 196   Currently, supported:
 197 <pre>
 198   MD5Crypt (crypt.inc.php)
 199   MCrypt
 200   Secure (Horde's emulation of MCrypt, if MCrypt module is not available.)
 201   GZip
 202   BZip2
 203 </pre>
 204 These are stackable. E.g.
 205 <pre>
 206 ADODB_Session::filter(new ADODB_Compress_Bzip2());
 207 ADODB_Session::filter(new ADODB_Encrypt_MD5());
 208 </pre>
 209 will compress and then encrypt the record in the database.
 210 <p>
 211 Also see the <a href=docs-adodb.htm>core ADOdb documentation</a>.
 212 </body>
 213 </html>