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 | V4.94 23 Jan 2007 (c) 2000-2007 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 | <p>Useful ADOdb links: <a href="http://adodb.sourceforge.net/#download">Download</a> |
---|
30 | <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 "<p>\$_SESSION['AVAR']={$_SESSION['AVAR']}</p>";<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->qstr($expireref); |
---|
210 | |
---|
211 | $ADODB_SESS_CONN->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> |
---|