[2] | 1 | <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> |
---|
| 2 | <html> |
---|
| 3 | <head> |
---|
| 4 | <title>ADODB 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 | V4.50 6 July 2004 (c) 2000-2004 John Lim (jlim#natsoft.com.my) |
---|
| 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 | <table border="1"> |
---|
| 30 | <tbody> |
---|
| 31 | <tr> |
---|
| 32 | <td><font color="red">Kindly note that the ADOdb home page has |
---|
| 33 | moved to <a href="http://adodb.sourceforge.net/">http://adodb.sourceforge.net/</a> |
---|
| 34 | because of the persistent unreliability of http://php.weblogs.com. <b>Please |
---|
| 35 | change your links</b>!</font></td> |
---|
| 36 | </tr> |
---|
| 37 | <tr> |
---|
| 38 | </tr> |
---|
| 39 | </tbody> |
---|
| 40 | </table> |
---|
| 41 | </p> |
---|
| 42 | <p>Useful ADOdb links: <a href="http://adodb.sourceforge.net/#download">Download</a> |
---|
| 43 | <a href="http://adodb.sourceforge.net/#docs">Other Docs</a> |
---|
| 44 | </p> |
---|
| 45 | <h3>Introduction</h3> |
---|
| 46 | <p> We store state information specific to a user or web client in |
---|
| 47 | session variables. These session variables persist throughout a |
---|
| 48 | session, as the user moves from page to page. </p> |
---|
| 49 | <p>To use session variables, call session_start() at the beginning of |
---|
| 50 | your web page, before your HTTP headers are sent. Then for every |
---|
| 51 | variable you want to keep alive for the duration of the session, call |
---|
| 52 | session_register($variable_name). By default, the session handler will |
---|
| 53 | keep track of the session by using a cookie. You can save objects or |
---|
| 54 | arrays in session variables also. |
---|
| 55 | </p> |
---|
| 56 | <p>The default method of storing sessions is to store it in a file. |
---|
| 57 | However if you have special needs such as you: |
---|
| 58 | </p> |
---|
| 59 | <ul> |
---|
| 60 | <li>Have multiple web servers that need to share session info</li> |
---|
| 61 | <li>Need to do special processing of each session</li> |
---|
| 62 | <li>Require notification when a session expires</li> |
---|
| 63 | </ul> |
---|
| 64 | <p>Then the ADOdb session handler provides you with the above |
---|
| 65 | additional capabilities by storing the session information as records |
---|
| 66 | in a database table that can be shared across multiple servers. </p> |
---|
| 67 | <p><b>Important Upgrade Notice:</b> Since ADOdb 4.05, the session files |
---|
| 68 | have been moved to its own folder, adodb/session. This is a rewrite |
---|
| 69 | of the session code by Ross Smith. The old session code is in |
---|
| 70 | adodb/session/old. </p> |
---|
| 71 | <h4>ADOdb Session Handler Features</h4> |
---|
| 72 | <ul> |
---|
| 73 | <li>Ability to define a notification function that is called when a |
---|
| 74 | session expires. Typically |
---|
| 75 | used to detect session logout and release global resources. </li> |
---|
| 76 | <li>Optimization of database writes. We crc32 the session data and |
---|
| 77 | only perform an update |
---|
| 78 | to the session data if there is a data change. </li> |
---|
| 79 | <li>Support for large amounts of session data with CLOBs (see |
---|
| 80 | adodb-session-clob.php). Useful |
---|
| 81 | for Oracle. </li> |
---|
| 82 | <li>Support for encrypted session data, see |
---|
| 83 | adodb-cryptsession.inc.php. Enabling encryption is simply a matter of |
---|
| 84 | including adodb-cryptsession.inc.php instead of adodb-session.inc.php. </li> |
---|
| 85 | </ul> |
---|
| 86 | <h3>Setup</h3> |
---|
| 87 | <p>There are 3 session management files that you can use: |
---|
| 88 | </p> |
---|
| 89 | <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> |
---|
| 90 | </pre> |
---|
| 91 | <p><strong>Examples</strong> |
---|
| 92 | <p><pre> |
---|
| 93 | <font |
---|
| 94 | 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 "<p>\$_SESSION['AVAR']={$_SESSION['AVAR']}</p>";<br></font></pre> |
---|
| 95 | <p>To force non-persistent connections, call adodb_session_open first before session_start():<p> |
---|
| 96 | <pre> |
---|
| 97 | <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> |
---|
| 98 | </pre> |
---|
| 99 | <p> To use a encrypted sessions, simply replace the file:</p> |
---|
| 100 | <pre> <font |
---|
| 101 | 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> |
---|
| 102 | </pre> |
---|
| 103 | <p>And the same technique for adodb-session-clob.php:</p> |
---|
| 104 | <pre> <font |
---|
| 105 | 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> |
---|
| 106 | </pre> |
---|
| 107 | <h4>Installation</h4> |
---|
| 108 | <p>1. Create this table in your database (syntax might vary depending on your db): |
---|
| 109 | <p><pre> <a |
---|
| 110 | name="sessiontab"></a> <font 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 text not null,<br> primary key (sesskey)<br> );</font><br> |
---|
| 111 | </pre> |
---|
| 112 | <p> For the adodb-session-clob.php version, create this: |
---|
| 113 | <pre> |
---|
| 114 | <font |
---|
| 115 | 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> |
---|
| 116 | </pre> |
---|
| 117 | <p>2. Then define the following parameters. You can either modify this file, or define them before this file is included: |
---|
| 118 | <pre> <font |
---|
| 119 | 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> |
---|
| 120 | </pre><p> |
---|
| 121 | 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 <br> in earlier versions of PHP. |
---|
| 122 | <h3>Notifications</h3> |
---|
| 123 | <p>If you want to receive notification when a session expires, then tag |
---|
| 124 | the session record with a <a href="#sessiontab">EXPIREREF</a> tag (see |
---|
| 125 | the definition of the sessions table above). Before any session record |
---|
| 126 | is deleted, ADOdb will call a notification function, passing in the |
---|
| 127 | EXPIREREF. |
---|
| 128 | </p> |
---|
| 129 | <p>When a session is first created, we check a global variable |
---|
| 130 | $ADODB_SESSION_EXPIRE_NOTIFY. This is an array with 2 elements, the |
---|
| 131 | first being the name of the session variable you would like to store in |
---|
| 132 | the EXPIREREF field, and the 2nd is the notification function's name. </p> |
---|
| 133 | <p> Suppose we want to be notified when a user's session has expired, |
---|
| 134 | based on the userid. The user id in the global session variable |
---|
| 135 | $USERID. The function name is 'NotifyFn'. So we define: </p> |
---|
| 136 | <pre> <font color="#004040"><br> $ADODB_SESSION_EXPIRE_NOTIFY = array('USERID','NotifyFn');<br> </font></pre> |
---|
| 137 | And when the NotifyFn is called (when the session expires), we pass the |
---|
| 138 | $USERID as the first parameter, eg. NotifyFn($userid, $sesskey). The |
---|
| 139 | session key (which is the primary key of the record in the sessions |
---|
| 140 | table) is the 2nd parameter. |
---|
| 141 | <p> Here is an example of a Notification function that deletes some |
---|
| 142 | records in the database and temporary files: </p> |
---|
| 143 | <pre><font color="#004040"><br> function NotifyFn($expireref, $sesskey)<br> {<br> global $ADODB_SESS_CONN; # the session connection object<br><br> $user = $ADODB_SESS_CONN->qstr($expireref);<br> $ADODB_SESS_CONN->Execute("delete from shopping_cart where user=$user");<br> system("rm /work/tmpfiles/$expireref/*");<br> }</font><br> </pre> |
---|
| 144 | <p> NOTE 1: If you have register_globals disabled in php.ini, then you |
---|
| 145 | will have to manually set the EXPIREREF. E.g. </p> |
---|
| 146 | <pre> <font color="#004040"> |
---|
| 147 | $GLOBALS['USERID'] =& $_SESSION['USERID']; |
---|
| 148 | $ADODB_SESSION_EXPIRE_NOTIFY = array('USERID','NotifyFn');</font> |
---|
| 149 | </pre> |
---|
| 150 | <p> NOTE 2: If you want to change the EXPIREREF after the session |
---|
| 151 | record has been created, you will need to modify any session variable |
---|
| 152 | to force a database record update. |
---|
| 153 | </p> |
---|
| 154 | <h4>Neat Notification Tricks</h4> |
---|
| 155 | <p><i>ExpireRef</i> normally holds the user id of the current session. |
---|
| 156 | </p> |
---|
| 157 | <p>1. You can then write a session monitor, scanning expireref to see |
---|
| 158 | who is currently logged on. |
---|
| 159 | </p> |
---|
| 160 | <p>2. If you delete the sessions record for a specific user, eg. |
---|
| 161 | </p> |
---|
| 162 | <pre>delete from sessions where expireref = '$USER'<br></pre> |
---|
| 163 | then the user is logged out. Useful for ejecting someone from a |
---|
| 164 | site. |
---|
| 165 | <p>3. You can scan the sessions table to ensure no user |
---|
| 166 | can be logged in twice. Useful for security reasons. |
---|
| 167 | </p> |
---|
| 168 | <h3>Compression/Encryption Schemes</h3> |
---|
| 169 | Since ADOdb 4.05, thanks to Ross Smith, multiple encryption and |
---|
| 170 | compression schemes are supported. Currently, supported are: |
---|
| 171 | <p> |
---|
| 172 | <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> |
---|
| 173 | <p>These are stackable. E.g. |
---|
| 174 | <p><pre>ADODB_Session::filter(new ADODB_Compress_Bzip2());<br>ADODB_Session::filter(new ADODB_Encrypt_MD5());<br></pre> |
---|
| 175 | will compress and then encrypt the record in the database. |
---|
| 176 | <p>Also see the <a href="docs-adodb.htm">core ADOdb documentation</a>. |
---|
| 177 | </p> |
---|
| 178 | </body> |
---|
| 179 | </html> |
---|