| 36 |
kaklik |
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.80 8 Mar 2006 (c) 2000-2006 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> We store state information specific to a user or web client in
|
|
|
34 |
session variables. These session variables persist throughout a
|
|
|
35 |
session, as the user moves from page to page. </p>
|
|
|
36 |
<p>To use session variables, call session_start() at the beginning of
|
|
|
37 |
your web page, before your HTTP headers are sent. Then for every
|
|
|
38 |
variable you want to keep alive for the duration of the session, call
|
|
|
39 |
session_register($variable_name). By default, the session handler will
|
|
|
40 |
keep track of the session by using a cookie. You can save objects or
|
|
|
41 |
arrays in session variables also.
|
|
|
42 |
</p>
|
|
|
43 |
<p>The default method of storing sessions is to store it in a file.
|
|
|
44 |
However if you have special needs such as you:
|
|
|
45 |
</p>
|
|
|
46 |
<ul>
|
|
|
47 |
<li>Have multiple web servers that need to share session info</li>
|
|
|
48 |
<li>Need to do special processing of each session</li>
|
|
|
49 |
<li>Require notification when a session expires</li>
|
|
|
50 |
</ul>
|
|
|
51 |
<p>The ADOdb session handler provides you with the above
|
|
|
52 |
additional capabilities by storing the session information as records
|
|
|
53 |
in a database table that can be shared across multiple servers. </p>
|
|
|
54 |
<p>These records will be garbage collected based on the php.ini [session] timeout settings.
|
|
|
55 |
You can register a notification function to notify you when the record has expired and
|
|
|
56 |
is about to be freed by the garbage collector.</p>
|
|
|
57 |
<p><b>Important Upgrade Notice:</b> Since ADOdb 4.05, the session files
|
|
|
58 |
have been moved to its own folder, adodb/session. This is a rewrite
|
|
|
59 |
of the session code by Ross Smith. The old session code is in
|
|
|
60 |
adodb/session/old. </p>
|
|
|
61 |
<h4>ADOdb Session Handler Features</h4>
|
|
|
62 |
<ul>
|
|
|
63 |
<li>Ability to define a notification function that is called when a
|
|
|
64 |
session expires. Typically
|
|
|
65 |
used to detect session logout and release global resources. </li>
|
|
|
66 |
<li>Optimization of database writes. We crc32 the session data and
|
|
|
67 |
only perform an update
|
|
|
68 |
to the session data if there is a data change. </li>
|
|
|
69 |
<li>Support for large amounts of session data with CLOBs (see
|
|
|
70 |
adodb-session-clob.php). Useful
|
|
|
71 |
for Oracle. </li>
|
|
|
72 |
<li>Support for encrypted session data, see
|
|
|
73 |
adodb-cryptsession.inc.php. Enabling encryption is simply a matter of
|
|
|
74 |
including adodb-cryptsession.inc.php instead of adodb-session.inc.php. </li>
|
|
|
75 |
</ul>
|
|
|
76 |
<h3>Setup</h3>
|
|
|
77 |
<p>There are 3 session management files that you can use:
|
|
|
78 |
</p>
|
|
|
79 |
<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>
|
|
|
80 |
</pre>
|
|
|
81 |
<p><strong>Examples</strong>
|
|
|
82 |
<p><pre>
|
|
|
83 |
<font
|
|
|
84 |
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>
|
|
|
85 |
|
|
|
86 |
<p>To force non-persistent connections, call adodb_session_open() first before session_start():
|
|
|
87 |
<p>
|
|
|
88 |
<pre>
|
|
|
89 |
<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>
|
|
|
90 |
</pre>
|
|
|
91 |
<p> The 3rd parameter to adodb_sess_open($path, $sessname, $connectMode) sets the connection method. You can pass in the following:</p>
|
|
|
92 |
<table width="50%" border="1">
|
|
|
93 |
<tr>
|
|
|
94 |
<td><b>$connectMode</b></td>
|
|
|
95 |
<td><b>Connection Method</b></td>
|
|
|
96 |
</tr>
|
|
|
97 |
<tr>
|
|
|
98 |
<td>true</td>
|
|
|
99 |
<td><p>PConnect( )</p></td>
|
|
|
100 |
</tr>
|
|
|
101 |
<tr>
|
|
|
102 |
<td>false</td>
|
|
|
103 |
<td>Connect( )</td>
|
|
|
104 |
</tr>
|
|
|
105 |
<tr>
|
|
|
106 |
<td>'N'</td>
|
|
|
107 |
<td>NConnect( )</td>
|
|
|
108 |
</tr>
|
|
|
109 |
<tr>
|
|
|
110 |
<td>'P'</td>
|
|
|
111 |
<td>PConnect( )</td>
|
|
|
112 |
</tr>
|
|
|
113 |
<tr>
|
|
|
114 |
<td>'C'</td>
|
|
|
115 |
<td>Connect( )</td>
|
|
|
116 |
</tr>
|
|
|
117 |
</table>
|
|
|
118 |
<p>To use a encrypted sessions, simply replace the file adodb-session.php:</p>
|
|
|
119 |
<pre> <font
|
|
|
120 |
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>
|
|
|
121 |
</pre>
|
|
|
122 |
<p>And the same technique for adodb-session-clob.php:</p>
|
|
|
123 |
<pre> <font
|
|
|
124 |
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>
|
|
|
125 |
</pre>
|
|
|
126 |
<h4>Installation</h4>
|
|
|
127 |
<p>1. Create this table in your database (syntax might vary depending on your db):
|
|
|
128 |
<p><pre> <a
|
|
|
129 |
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>
|
|
|
130 |
</pre>
|
|
|
131 |
<p>You may want to rename the 'data' field to 'session_data' as
|
|
|
132 |
'data' appears to be a reserved word for one or more of the following:
|
|
|
133 |
<ul>
|
|
|
134 |
<li> ANSI SQL
|
|
|
135 |
<li> IBM DB2
|
|
|
136 |
<li> MS SQL Server
|
|
|
137 |
<li> Postgres
|
|
|
138 |
<li> SAP
|
|
|
139 |
</ul>
|
|
|
140 |
<p>
|
|
|
141 |
If you do, then execute:
|
|
|
142 |
<pre>
|
|
|
143 |
ADODB_Session::dataFieldName('session_data');
|
|
|
144 |
</pre>
|
|
|
145 |
<p> For the adodb-session-clob.php version, create this:
|
|
|
146 |
<p> <pre>
|
|
|
147 |
<font
|
|
|
148 |
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>
|
|
|
149 |
</pre>
|
|
|
150 |
<p>2. Then define the following parameters. You can either modify this file, or define them before this file is included:
|
|
|
151 |
<pre> <font
|
|
|
152 |
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>
|
|
|
153 |
</pre><p>
|
|
|
154 |
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.
|
|
|
155 |
<h3>Notifications</h3>
|
|
|
156 |
<p>You can receive notification when your session is cleaned up by the session garbage collector or
|
|
|
157 |
when you call session_destroy().
|
|
|
158 |
<p>PHP's session extension will automatically run a special garbage collection function based on
|
|
|
159 |
your php.ini session.cookie_lifetime and session.gc_probability settings. This will in turn call
|
|
|
160 |
adodb's garbage collection function, which can be setup to do notification.
|
|
|
161 |
<p>
|
|
|
162 |
<pre>
|
|
|
163 |
PHP Session --> ADOdb Session --> Find all recs --> Send --> Delete queued
|
|
|
164 |
GC Function GC Function to be deleted notification records
|
|
|
165 |
executed at called by for all recs
|
|
|
166 |
random time Session Extension queued for deletion
|
|
|
167 |
</pre>
|
|
|
168 |
<p>When a session is created, we need to store a value in the session record (in the EXPIREREF field), typically
|
|
|
169 |
the userid of the session. Later when the session has expired, just before the record is deleted,
|
|
|
170 |
we reload the EXPIREREF field and call the notification function with the value of EXPIREREF, which
|
|
|
171 |
is the userid of the person being logged off.
|
|
|
172 |
<p>ADOdb use a global variable $ADODB_SESSION_EXPIRE_NOTIFY that you must predefine before session
|
|
|
173 |
start to store the notification configuratioin.
|
|
|
174 |
$ADODB_SESSION_EXPIRE_NOTIFY is an array with 2 elements, the
|
|
|
175 |
first being the name of the session variable you would like to store in
|
|
|
176 |
the EXPIREREF field, and the 2nd is the notification function's name. </p>
|
|
|
177 |
<p>For example, suppose we want to be notified when a user's session has expired,
|
|
|
178 |
based on the userid. When the user logs in, we store the id in the global session variable
|
|
|
179 |
$USERID. The function name is 'NotifyFn'.
|
|
|
180 |
<p>
|
|
|
181 |
So we define (before session_start() is called): </p>
|
|
|
182 |
<pre> <font color="#004040"><br> $ADODB_SESSION_EXPIRE_NOTIFY = array('USERID','NotifyFn');<br> </font></pre>
|
|
|
183 |
And when the NotifyFn is called (when the session expires), the
|
|
|
184 |
$USERID is passed in as the first parameter, eg. NotifyFn($userid, $sesskey). The
|
|
|
185 |
session key (which is the primary key of the record in the sessions
|
|
|
186 |
table) is the 2nd parameter.
|
|
|
187 |
<p> Here is an example of a Notification function that deletes some
|
|
|
188 |
records in the database and temporary files: </p>
|
|
|
189 |
<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>
|
|
|
190 |
<p> NOTE 1: If you have register_globals disabled in php.ini, then you
|
|
|
191 |
will have to manually set the EXPIREREF. E.g. </p>
|
|
|
192 |
<pre> <font color="#004040">
|
|
|
193 |
$GLOBALS['USERID'] = GetUserID();
|
|
|
194 |
$ADODB_SESSION_EXPIRE_NOTIFY = array('USERID','NotifyFn');</font>
|
|
|
195 |
</pre>
|
|
|
196 |
<p> NOTE 2: If you want to change the EXPIREREF after the session
|
|
|
197 |
record has been created, you will need to modify any session variable
|
|
|
198 |
to force a database record update.
|
|
|
199 |
</p>
|
|
|
200 |
<h4>Neat Notification Tricks</h4>
|
|
|
201 |
<p><i>ExpireRef</i> normally holds the user id of the current session.
|
|
|
202 |
</p>
|
|
|
203 |
<p>1. You can then write a session monitor, scanning expireref to see
|
|
|
204 |
who is currently logged on.
|
|
|
205 |
</p>
|
|
|
206 |
<p>2. If you delete the sessions record for a specific user, eg.
|
|
|
207 |
</p>
|
|
|
208 |
<pre>delete from sessions where expireref = '$USER'<br></pre>
|
|
|
209 |
then the user is logged out. Useful for ejecting someone from a
|
|
|
210 |
site.
|
|
|
211 |
<p>3. You can scan the sessions table to ensure no user
|
|
|
212 |
can be logged in twice. Useful for security reasons.
|
|
|
213 |
</p>
|
|
|
214 |
<h3>Compression/Encryption Schemes</h3>
|
|
|
215 |
Since ADOdb 4.05, thanks to Ross Smith, multiple encryption and
|
|
|
216 |
compression schemes are supported. Currently, supported are:
|
|
|
217 |
<p>
|
|
|
218 |
<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>
|
|
|
219 |
<p>These are stackable. E.g.
|
|
|
220 |
<p><pre>ADODB_Session::filter(new ADODB_Compress_Bzip2());<br>ADODB_Session::filter(new ADODB_Encrypt_MD5());<br></pre>
|
|
|
221 |
will compress and then encrypt the record in the database.
|
|
|
222 |
<h3>adodb_session_regenerate_id()</h3>
|
|
|
223 |
<p>Dynamically change the current session id with a newly generated one and update database. Currently only
|
|
|
224 |
works with cookies. Useful to improve security by reducing the risk of session-hijacking.
|
|
|
225 |
See this article on <a href=http://shiflett.org/articles/security-corner-feb2004>Session Fixation</a> for more info
|
|
|
226 |
on the theory behind this feature. Usage:
|
|
|
227 |
<pre>
|
|
|
228 |
$ADODB_SESSION_DRIVER='mysql';
|
|
|
229 |
$ADODB_SESSION_CONNECT='localhost';
|
|
|
230 |
$ADODB_SESSION_USER ='root';
|
|
|
231 |
$ADODB_SESSION_PWD ='abc';
|
|
|
232 |
$ADODB_SESSION_DB ='phplens';
|
|
|
233 |
|
|
|
234 |
include('path/to/adodb/session/adodb-session.php');
|
|
|
235 |
|
|
|
236 |
session_start();
|
|
|
237 |
# Every 10 page loads, reset cookie for safety.
|
|
|
238 |
# This is extremely simplistic example, better
|
|
|
239 |
# to regenerate only when the user logs in or changes
|
|
|
240 |
# user privilege levels.
|
|
|
241 |
if ((rand()%10) == 0) adodb_session_regenerate_id(); </pre>
|
|
|
242 |
<p>This function calls session_regenerate_id() internally or simulates it if the function does not exist.
|
|
|
243 |
<h2>More Info</h2>
|
|
|
244 |
<p>Also see the <a href="docs-adodb.htm">core ADOdb documentation</a>.
|
|
|
245 |
</p>
|
|
|
246 |
</body>
|
|
|
247 |
</html>
|