library/adodb/docs/docs-session.old.htm

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
   2 <html>
   3 <head>
   4   <title>ADODB Old Session Management Manual</title>
   5   <meta http-equiv="Content-Type"
   6  content="text/html; charset=iso-8859-1">
   7   <style type="text/css">
   8 body, td {
   9 /*font-family: Arial, Helvetica, sans-serif;*/
  10 font-size: 11pt;
  11 }
  12 pre {
  13 font-size: 9pt;
  14 background-color: #EEEEEE; padding: .5em; margin: 0px;
  15 }
  16 .toplink {
  17 font-size: 8pt;
  18 }
  19   </style>
  20 </head>
  21 <body style="background-color: rgb(255, 255, 255);">
  22 <h3>ADODB Session Management Manual</h3>
  23 <p>
  24 V5.14 8 Sept 2011  (c) 2000-2010 John Lim (jlim#natsoft.com)
  25 </p>
  26 <p> <font size="1">This software is dual licensed using BSD-Style and
  27 LGPL. This means you can use it in compiled proprietary and commercial
  28 products. </font>
  29 <p>Useful ADOdb links: <a href="http://adodb.sourceforge.net/#download">Download</a>
  30 &nbsp; <a href="http://adodb.sourceforge.net/#docs">Other Docs</a>
  31 </p>
  32 <h3>Introduction</h3>
  33 <p>This documentation discusses the old adodb-session.php.
  34 Here is the <a href=docs-session.htm>new documentation</a> on the newer adodb-session2.php.
  35 <p> We store state information specific to a user or web client in
  36 session variables. These session variables persist throughout a
  37 session, as the user moves from page to page. </p>
  38 <p>To use session variables, call session_start() at the beginning of
  39 your web page, before your HTTP headers are sent. Then for every
  40 variable you want to keep alive for the duration of the session, call
  41 session_register($variable_name). By default, the session handler will
  42 keep track of the session by using a cookie. You can save objects or
  43 arrays in session variables also.
  44 </p>
  45 <p>The default method of storing sessions is to store it in a file.
  46 However if you have special needs such as you:
  47 </p>
  48 <ul>
  49   <li>Have multiple web servers that need to share session info</li>
  50   <li>Need to do special processing of each session</li>
  51   <li>Require notification when a session expires</li>
  52 </ul>
  53 <p>The ADOdb session handler provides you with the above
  54 additional capabilities by storing the session information as records
  55 in a database table that can be shared across multiple servers. </p>
  56 <p>These records will be garbage collected based on the php.ini [session] timeout settings.
  57 You can register a notification function to notify you when the record has expired and
  58 is about to be freed by the garbage collector.</p>
  59 <p><b>Important Upgrade Notice:</b> Since ADOdb 4.05, the session files
  60 have been moved to its own folder, adodb/session. This is a rewrite
  61 of the session code by Ross Smith. The old session code is in
  62 adodb/session/old. </p>
  63 <h4>ADOdb Session Handler Features</h4>
  64 <ul>
  65   <li>Ability to define a notification function that is called when a
  66 session expires. Typically
  67 used to detect session logout and release global resources. </li>
  68   <li>Optimization of database writes. We crc32 the session data and
  69 only perform an update
  70 to the session data if there is a data change. </li>
  71   <li>Support for large amounts of session data with CLOBs (see
  72 adodb-session-clob.php). Useful
  73 for Oracle. </li>
  74   <li>Support for encrypted session data, see
  75 adodb-cryptsession.php. Enabling encryption is simply a matter of
  76 including adodb-cryptsession.php instead of adodb-session.php. </li>
  77 </ul>
  78 <h3>Setup</h3>
  79 <p>There are 3 session management files that you can use:
  80 </p>
  81 <pre>adodb-session.php        : The default<br>adodb-session-clob.php   : Use this if you are storing DATA in clobs<br>adodb-cryptsession.php   : Use this if you want to store encrypted session data in the database<br><br>
  82 </pre>
  83 <p><strong>Examples</strong>
  84 <p><pre>
  85  <font
  86  color="#004040">    include('adodb/adodb.inc.php');<br>    <br><b>    $ADODB_SESSION_DRIVER='mysql';<br>    $ADODB_SESSION_CONNECT='localhost';<br>    $ADODB_SESSION_USER ='scott';<br>    $ADODB_SESSION_PWD ='tiger';<br>    $ADODB_SESSION_DB ='sessiondb';</b><br>    <br>    <b>include('adodb/session/adodb-session.php');</b><br>    session_start();<br>    <br>    #<br>    # Test session vars, the following should increment on refresh<br>    #<br>    $_SESSION['AVAR'] += 1;<br>    print "&lt;p&gt;\$_SESSION['AVAR']={$_SESSION['AVAR']}&lt;/p&gt;";<br></font></pre>
  87
  88 <p>To force non-persistent connections, call adodb_session_open() first before session_start():
  89 <p>
  90  <pre>
  91  <font color="#004040"><br>    include('adodb/adodb.inc.php');<br>    <br><b>    $ADODB_SESSION_DRIVER='mysql';<br>    $ADODB_SESSION_CONNECT='localhost';<br>    $ADODB_SESSION_USER ='scott';<br>    $ADODB_SESSION_PWD ='tiger';<br>    $ADODB_SESSION_DB ='sessiondb';</b><br>    <br>    <b>include('adodb/session/adodb-session.php');<br>    adodb_sess_open(false,false,false);</b><br>    session_start();<br> </font>
  92  </pre>
  93 <p> The 3rd parameter to adodb_sess_open($path, $sessname, $connectMode)  sets the connection method. You can pass in the following:</p>
  94 <table width="50%" border="1">
  95   <tr>
  96     <td><b>$connectMode</b></td>
  97     <td><b>Connection Method</b></td>
  98   </tr>
  99   <tr>
 100     <td>true</td>
 101     <td><p>PConnect( )</p></td>
 102   </tr>
 103   <tr>
 104     <td>false</td>
 105     <td>Connect( )</td>
 106   </tr>
 107   <tr>
 108     <td>'N'</td>
 109     <td>NConnect( )</td>
 110   </tr>
 111   <tr>
 112     <td>'P'</td>
 113     <td>PConnect( )</td>
 114   </tr>
 115   <tr>
 116     <td>'C'</td>
 117     <td>Connect( )</td>
 118   </tr>
 119 </table>
 120 <p>To use a encrypted sessions, simply replace the file adodb-session.php:</p>
 121  <pre> <font
 122  color="#004040"><br>    include('adodb/adodb.inc.php');<br>    <br><b>    $ADODB_SESSION_DRIVER='mysql';<br>    $ADODB_SESSION_CONNECT='localhost';<br>    $ADODB_SESSION_USER ='scott';<br>    $ADODB_SESSION_PWD ='tiger';<br>    $ADODB_SESSION_DB ='sessiondb';<br>    <br>    include('adodb/session/adodb-cryptsession.php');</b><br>    session_start();</font><br>
 123  </pre>
 124  <p>And the same technique for adodb-session-clob.php:</p>
 125  <pre>  <font
 126  color="#004040"><br>    include('adodb/adodb.inc.php');<br>    <br><b>    $ADODB_SESSION_DRIVER='mysql';<br>    $ADODB_SESSION_CONNECT='localhost';<br>    $ADODB_SESSION_USER ='scott';<br>    $ADODB_SESSION_PWD ='tiger';<br>    $ADODB_SESSION_DB ='sessiondb';<br>    <br>    include('adodb/session/adodb-session-clob.php');</b><br>    session_start();</font>
 127  </pre>
 128  <p>An alternative way to set persistant or non-persistent connections is to call the following function before session_start() is called.
 129  <pre>
 130         ADODB_Session::persist('P'); # 'C' for non-persistent connections
 131  </pre>
 132  <h4>Installation</h4>
 133 <p>1. Create this table in your database (MySQL syntax):
 134 <p><pre> <a
 135  name="sessiontab"></a> <font color="#004040">
 136    create table sessions (
 137        SESSKEY char(32) not null,
 138        EXPIRY int(11) unsigned not null,
 139        EXPIREREF varchar(64),
 140            DATA text not null,
 141            primary key (sesskey)
 142            );</font>
 143  </pre>
 144
 145  <p>You may want to rename the 'data' field to 'session_data' as
 146         'data' appears to be a reserved word for one or more of the following:
 147         <ul>
 148         <li>    ANSI SQL
 149         <li>    IBM DB2
 150         <li>    MS SQL Server
 151         <li>    Postgres
 152         <li>    SAP
 153                 </ul>
 154 <p>
 155         If you do, then execute:
 156 <pre>
 157                 ADODB_Session::dataFieldName('session_data');
 158 </pre>
 159  <p> For the adodb-session-clob.php version, create this:
 160 <p>  <pre>
 161     <font
 162  color="#004040"><br>    create table sessions (<br>       SESSKEY char(32) not null,<br>       EXPIRY int(11) unsigned not null,<br>       EXPIREREF varchar(64),<br>       DATA CLOB,<br>      primary key (sesskey)<br>  );</font>
 163  </pre>
 164  <p>2. Then define the following parameters. You can either modify this file, or define them before this file is included:
 165  <pre>      <font
 166  color="#004040"><br>    $ADODB_SESSION_DRIVER='database driver, eg. mysql or ibase';<br>    $ADODB_SESSION_CONNECT='server to connect to';<br>    $ADODB_SESSION_USER ='user';<br>    $ADODB_SESSION_PWD ='password';<br>    $ADODB_SESSION_DB ='database';<br>    $ADODB_SESSION_TBL = 'sessions'; # setting this is optional<br>     </font>
 167  </pre><p>
 168      When the session is created, $<b>ADODB_SESS_CONN</b> holds the connection object.<br>    <br>  3. Recommended is PHP 4.0.6 or later. There are documented session bugs in earlier versions of PHP.
 169 <h3>Notifications</h3>
 170 <p>You can receive notification when your session is cleaned up by the session garbage collector or
 171 when you call session_destroy().
 172 <p>PHP's session extension will automatically run a special garbage collection function based on
 173 your php.ini session.cookie_lifetime and session.gc_probability settings. This will in turn call
 174 adodb's garbage collection function, which can be setup to do notification.
 175 <p>
 176 <pre>
 177         PHP Session --> ADOdb Session  --> Find all recs  --> Send          --> Delete queued
 178         GC Function     GC Function        to be deleted      notification      records
 179         executed at     called by                             for all recs
 180         random time     Session Extension                     queued for deletion
 181 </pre>
 182 <p>When a session is created, we need to store a value in the session record (in the EXPIREREF field), typically
 183 the userid of the session. Later when the session has expired,  just before the record is deleted,
 184 we reload the EXPIREREF field and call the notification function with the value of EXPIREREF, which
 185 is the userid of the person being logged off.
 186 <p>ADOdb uses a global variable $ADODB_SESSION_EXPIRE_NOTIFY that you must predefine before session
 187 start to store the notification configuration.
 188 $ADODB_SESSION_EXPIRE_NOTIFY is an array with 2 elements, the
 189 first being the name of the session variable you would like to store in
 190 the EXPIREREF field, and the 2nd is the notification function's name. </p>
 191 <p>For example, suppose we want to be notified when a user's session has expired,
 192 based on the userid. When the user logs in, we store the id in the global session variable
 193 $USERID. The function name is 'NotifyFn'.
 194 <p>
 195 So we define (before session_start() is called): </p>
 196 <pre> <font color="#004040">
 197         $ADODB_SESSION_EXPIRE_NOTIFY = array('USERID','NotifyFn');
 198 </font></pre>
 199 And when the NotifyFn is called (when the session expires), the
 200 $USERID is passed in as the first parameter, eg. NotifyFn($userid, $sesskey). The
 201 session key (which is the primary key of the record in the sessions
 202 table) is the 2nd parameter.
 203 <p> Here is an example of a Notification function that deletes some
 204 records in the database and temporary files: </p>
 205 <pre><font color="#004040">
 206         function NotifyFn($expireref, $sesskey)
 207         {
 208                 global $ADODB_SESS_CONN; # the session connection object
 209                 $user = $ADODB_SESS_CONN-&gt;qstr($expireref);
 210
 211                 $ADODB_SESS_CONN-&gt;Execute("delete from shopping_cart where user=$user");
 212                 system("rm /work/tmpfiles/$expireref/*");
 213         }</font>
 214                           </pre>
 215 <p> NOTE 1: If you have register_globals disabled in php.ini, then you
 216 will have to manually set the EXPIREREF. E.g. </p>
 217 <pre> <font color="#004040">
 218 $GLOBALS['USERID'] = GetUserID();
 219 $ADODB_SESSION_EXPIRE_NOTIFY = array('USERID','NotifyFn');</font>
 220 </pre>
 221 <p> NOTE 2: If you want to change the EXPIREREF after the session
 222 record has been created, you will need to modify any session variable
 223 to force a database record update.
 224 </p>
 225 <h4>Neat Notification Tricks</h4>
 226 <p><i>ExpireRef</i> normally holds the user id of the current session.
 227 </p>
 228 <p>1. You can then write a session monitor, scanning expireref to see
 229 who is currently logged on.
 230 </p>
 231 <p>2. If you delete the sessions record for a specific user, eg.
 232 </p>
 233 <pre>delete from sessions where expireref = '$USER'<br></pre>
 234 then the user is logged out. Useful for ejecting someone from a
 235 site.
 236 <p>3. You can scan the sessions table to ensure no user
 237 can be logged in twice. Useful for security reasons.
 238 </p>
 239 <h3>Using Oracle CLOBs</h3>
 240 <p>Suppose you are storing the DATA field in a CLOB:
 241  <pre><font color="#004040">
 242    CREATE TABLE sessions (
 243        SESSKEY VARCHAR(32) NOT NULL,
 244        EXPIRY NUMBER(16)  NOT NULL,
 245        EXPIREREF VARCHAR(64),
 246        DATA CLOB,
 247       PRIMARY KEY (sesskey)
 248   );</font>
 249  </pre>
 250  <p>Then your PHP code could look like this:
 251          <pre>
 252         ADODB_SESSION_DRIVER='oci8';
 253         $ADODB_SESSION_CONNECT=$tnsname;
 254         $ADODB_SESSION_USER ='scott';
 255         $ADODB_SESSION_PWD = 'tiger';
 256         $ADODB_SESSION_DB ='';
 257
 258         $ADODB_SESSION_USE_LOBS = 'clob';
 259         $ADODB_SESSION_TBL = 'sessions';
 260
 261         $ADODB_SESS_DEBUG=0;
 262
 263         include(ADODB_DIR.'/session/adodb-session.php');
 264
 265         ADODB_Session::persist('P'); # use 'C' for non-persistent connects
 266
 267         session_start();
 268  </pre>
 269  <p>Note that you can set persistance using ADODB_Session::persist('P').
 270
 271 <h3>Compression/Encryption Schemes</h3>
 272 Since ADOdb 4.05, thanks to Ross Smith, multiple encryption and
 273 compression schemes are supported. Currently, supported are:
 274 <p>
 275 <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>
 276 <p>These are stackable. E.g.
 277 <p><pre>ADODB_Session::filter(new ADODB_Compress_Bzip2());<br>ADODB_Session::filter(new ADODB_Encrypt_MD5());<br></pre>
 278 will compress and then encrypt the record in the database.
 279 <h3>adodb_session_regenerate_id()</h3>
 280 <p>Dynamically change the current session id with a newly generated one and update database. Currently only
 281 works with cookies. Useful to improve security by reducing the risk of session-hijacking.
 282 See this article on <a href=http://shiflett.org/articles/security-corner-feb2004>Session Fixation</a> for more info
 283 on the theory behind this feature. Usage:
 284 <pre>
 285         $ADODB_SESSION_DRIVER='mysql';
 286         $ADODB_SESSION_CONNECT='localhost';
 287         $ADODB_SESSION_USER ='root';
 288         $ADODB_SESSION_PWD ='abc';
 289         $ADODB_SESSION_DB ='phplens';
 290
 291         include('path/to/adodb/session/adodb-session.php');
 292
 293         session_start();
 294         # Every 10 page loads, reset cookie for safety.
 295         # This is extremely simplistic example, better
 296         # to regenerate only when the user logs in or changes
 297         # user privilege levels.
 298         if ((rand()%10) == 0) adodb_session_regenerate_id();
 299 </pre>
 300 <p>This function calls session_regenerate_id() internally or simulates it if the function does not exist.
 301 <h3>Vacuum/Optimize Database</h3>
 302 <p>During session garbage collection, if postgresql is detected,
 303   ADOdb can be set to run VACUUM. If mysql is detected, then optimize database
 304   could be called.You can turn this on or off using:</p>
 305 <pre>$turnOn = true; # or false
 306 ADODB_Session::optimize($turnOn);
 307 </pre>
 308 <p>The default for optimization is it is disabled.</p>
 309 <h2>More Info</h2>
 310 <p>Also see the <a href="docs-adodb.htm">core ADOdb documentation</a>.
 311 </p>
 312 </body>
 313 </html>