source: trunk/phpgwapi/inc/adodb/docs/docs-session.htm @ 2

Revision 2, 10.0 KB checked in by niltonneto, 17 years ago (diff)

Removida todas as tags usadas pelo CVS ($Id, $Source).
Primeira versão no CVS externo.
  • Property svn:eol-style set to native
  • Property svn:executable set to *
Line 
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">
8body, td {
9/*font-family: Arial, Helvetica, sans-serif;*/
10font-size: 11pt;
11}
12pre {
13font-size: 9pt;
14background-color: #EEEEEE; padding: .5em; margin: 0px;
15}
16.toplink {
17font-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>
24V4.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
27LGPL. This means you can use it in compiled proprietary and commercial
28products. </font>
29<table border="1">
30  <tbody>
31    <tr>
32      <td><font color="red">Kindly note that the ADOdb home page has
33moved to <a href="http://adodb.sourceforge.net/">http://adodb.sourceforge.net/</a>
34because of the persistent unreliability of http://php.weblogs.com. <b>Please
35change 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&nbsp; <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
47session variables. These session variables persist throughout a
48session, as the user moves from page to page. </p>
49<p>To use session variables, call session_start() at the beginning of
50your web page, before your HTTP headers are sent. Then for every
51variable you want to keep alive for the duration of the session, call
52session_register($variable_name). By default, the session handler will
53keep track of the session by using a cookie. You can save objects or
54arrays in session variables also.
55</p>
56<p>The default method of storing sessions is to store it in a file.
57However 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
65additional capabilities by storing the session information as records
66in 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
68have been moved to its own folder, adodb/session. This is a rewrite
69of the session code by Ross Smith. The old session code is in
70adodb/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
74session expires. Typically
75used to detect session logout and release global resources. </li>
76  <li>Optimization of database writes. We crc32 the session data and
77only perform an update
78to the session data if there is a data change. </li>
79  <li>Support for large amounts of session data with CLOBs (see
80adodb-session-clob.php). Useful
81for Oracle. </li>
82  <li>Support for encrypted session data, see
83adodb-cryptsession.inc.php. Enabling encryption is simply a matter of
84including 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 "&lt;p&gt;\$_SESSION['AVAR']={$_SESSION['AVAR']}&lt;/p&gt;";<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
124the session record with a <a href="#sessiontab">EXPIREREF</a> tag (see
125the definition of the sessions table above). Before any session record
126is deleted, ADOdb will call a notification function, passing in the
127EXPIREREF.
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
131first being the name of the session variable you would like to store in
132the 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,
134based 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>
137And when the NotifyFn is called (when the session expires), we pass the
138$USERID as the first parameter, eg. NotifyFn($userid, $sesskey). The
139session key (which is the primary key of the record in the sessions
140table) is the 2nd parameter.
141<p> Here is an example of a Notification function that deletes some
142records 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-&gt;qstr($expireref);<br>          $ADODB_SESS_CONN-&gt;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
145will have to manually set the EXPIREREF. E.g. </p>
146<pre> <font color="#004040">
147    $GLOBALS['USERID'] =&amp; $_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
151record has been created, you will need to modify any session variable
152to 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
158who 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>
163then the user is logged out. Useful for ejecting someone from a
164site.
165<p>3. You can scan the sessions table to ensure no user
166can be logged in twice. Useful for security reasons.
167</p>
168<h3>Compression/Encryption Schemes</h3>
169Since ADOdb 4.05, thanks to Ross Smith, multiple encryption and
170compression 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>
175will 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>
Note: See TracBrowser for help on using the repository browser.