| admin | b0dd10f | 2006-08-25 17:25:49 +0000 | [diff] [blame] | 1 | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
| 2 | <html>
|
| 3 | <head>
|
| 4 |
|
| 5 | <title>Code Igniter User Guide</title>
|
| 6 |
|
| 7 | <style type='text/css' media='all'>@import url('../userguide.css');</style>
|
| 8 | <link rel='stylesheet' type='text/css' media='all' href='../userguide.css' />
|
| 9 |
|
| 10 | <script type="text/javascript" src="../scripts/nav.js"></script>
|
| 11 | <script type="text/javascript" src="../scripts/prototype.lite.js"></script>
|
| 12 | <script type="text/javascript" src="../scripts/moo.fx.js"></script>
|
| 13 | <script type="text/javascript">
|
| 14 | window.onload = function() {
|
| 15 | myHeight = new fx.Height('nav', {duration: 400});
|
| 16 | myHeight.hide();
|
| 17 | }
|
| 18 | </script>
|
| 19 |
|
| 20 | <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
|
| 21 | <meta http-equiv='expires' content='-1' />
|
| 22 | <meta http-equiv= 'pragma' content='no-cache' />
|
| 23 | <meta name='robots' content='all' />
|
| 24 | <meta name='author' content='Rick Ellis' />
|
| 25 | <meta name='description' content='Code Igniter User Guide' />
|
| 26 |
|
| 27 | </head>
|
| 28 | <body>
|
| 29 |
|
| 30 | <!-- START NAVIGATION -->
|
| 31 | <div id="nav"><div id="nav_inner"><script type="text/javascript">create_menu('../');</script></div></div>
|
| 32 | <div id="nav2"><a name="top"></a><a href="javascript:void(0);" onclick="myHeight.toggle();"><img src="../images/nav_toggle.jpg" width="153" height="44" border="0" title="Toggle Table of Contents" alt="Toggle Table of Contents" /></a></div>
|
| 33 | <div id="masthead">
|
| 34 | <table cellpadding="0" cellspacing="0" border="0" style="width:100%">
|
| 35 | <tr>
|
| 36 | <td><h1>Code Igniter User Guide Version 1.4.0</h1></td>
|
| 37 | <td id="breadcrumb_right"><a href="../toc.html">Full Table of Contents</a></td>
|
| 38 | </tr>
|
| 39 | </table>
|
| 40 | </div>
|
| 41 | <!-- END NAVIGATION -->
|
| 42 |
|
| 43 |
|
| 44 | <!-- START BREADCRUMB -->
|
| 45 | <table cellpadding="0" cellspacing="0" border="0" style="width:100%">
|
| 46 | <tr>
|
| 47 | <td id="breadcrumb">
|
| 48 | <a href="http://www.codeigniter.com/">Code Igniter Home</a> ›
|
| 49 | <a href="../index.html">User Guide Home</a> ›
|
| 50 | Session Class
|
| 51 | </td>
|
| 52 | <td id="searchbox"><form method="get" action="http://www.google.com/search"><input type="hidden" name="as_sitesearch" id="as_sitesearch" value="www.codeigniter.com/user_guide/" />Search User Guide <input type="text" class="input" style="width:200px;" name="q" id="q" size="31" maxlength="255" value="" /> <input type="submit" class="submit" name="sa" value="Go" /></form></td>
|
| 53 | </tr>
|
| 54 | </table>
|
| 55 | <!-- END BREADCRUMB -->
|
| 56 |
|
| 57 | <br clear="all" />
|
| 58 |
|
| 59 |
|
| 60 | <!-- START CONTENT -->
|
| 61 | <div id="content">
|
| 62 |
|
| 63 |
|
| 64 | <h1>Session Class</h1>
|
| 65 |
|
| 66 | <p>The Session class permits you maintain a user's "state" and track their activity while they browse your site.
|
| 67 | The Session class stores session information for each user as serialized (and optionally encrypted) data in a cookie.
|
| 68 | It can also store the session data in a database table for added security, as this permits the session ID in the
|
| 69 | user's cookie to be matched against the stored session ID. By default only the cookie is saved. If you choose to
|
| 70 | use the database option you'll need to create the session table as indicated below.
|
| 71 | </p>
|
| 72 |
|
| 73 | <p class="important"><strong>Note:</strong> The Session class does <strong>not</strong> utilize native PHP sessions. It
|
| 74 | generates its own session data, offering more flexibility for developers.</p>
|
| 75 |
|
| 76 | <h2>Initializing a Session</h2>
|
| 77 |
|
| 78 | <p>Sessions will typically run globally with each page load, so the session class must either be
|
| 79 | <a href="../general/libraries.html">initialized</a> in your
|
| 80 | <a href="../general/controllers.html">controller</a> constructors, or it can be
|
| 81 | <a href="../general/autoloader.html">auto-loaded</a> by the system.
|
| 82 | For the most part the session class will run unattended in the background, so simply initializing the class
|
| 83 | will cause it to read, create, and update sessions.</p>
|
| 84 |
|
| 85 |
|
| 86 | <p>To initialize the Session class manually in your controller constructor, use the <dfn>$this->load->library</dfn> function:</p>
|
| 87 |
|
| 88 | <code>$this->load->library('session');</code>
|
| 89 | <p>Once loaded, the Sessions library object will be available using: <dfn>$this->session</dfn></p>
|
| 90 |
|
| 91 |
|
| 92 | <h2>How do Sessions work?</h2>
|
| 93 |
|
| 94 | <p>When a page is loaded, the session class will check to see if valid session data exists in the user's session cookie.
|
| 95 | If sessions data does <strong>not</strong> exist (or if it has expired) a new session will be created and saved in the cookie.
|
| 96 | If a session does exist, its information will be updated and the cookie will be updated.</p>
|
| 97 |
|
| 98 | <p>It's important for you to understand that once initialized, the Session class runs automatically. There is nothing
|
| 99 | you need to do to cause the above behavior to happen. You can, as you'll see below, work with session data or
|
| 100 | even add your own data to a user's session, but the process of reading, writing, and updating a session is automatic.</p>
|
| 101 |
|
| 102 |
|
| 103 | <h2>What is Session Data?</h2>
|
| 104 |
|
| 105 | <p>A <em>session</em>, as far as Code Igniter is concerned, is simply an array containing the following information:</p>
|
| 106 |
|
| 107 | <ul>
|
| 108 | <li>The user's unique Session ID (this is a statistically random string with very strong entropy, hashed with MD5 for portability)</li>
|
| 109 | <li>The user's IP Address</li>
|
| 110 | <li>The user's User Agent data (the first 50 characters of the browser data string)</li>
|
| 111 | <li>The "last activity" and "last visit" time stamps.</li>
|
| 112 | </ul>
|
| 113 |
|
| 114 | <p>The above data is stored in a cookie as a serialized array with this prototype:</p>
|
| 115 |
|
| 116 | <code>[array]<br />
|
| 117 | (<br />
|
| 118 | 'session_id' => random hash,<br />
|
| 119 | 'ip_address' => 'string - user IP address',<br />
|
| 120 | 'user_agent' => 'string - user agent data',<br />
|
| 121 | 'last_activity' => timestamp,<br />
|
| 122 | 'last_visit' => timestamp<br />
|
| 123 | )</code>
|
| 124 |
|
| 125 | <p>If you have the encryption option enabled, the serialized array will be encrypted before being stored in the cookie,
|
| 126 | making the data highly secure and impervious to being read or altered by someone. More info regarding encryption
|
| 127 | can be <a href="encryption.html">found here</a>, although the Session class will take care of initializing
|
| 128 | and encrypting the data automatically.</p>
|
| 129 |
|
| 130 | <p>Note: Session cookies are only updated every five minutes to reduce processor load. If you repeatedly reload a page
|
| 131 | you'll notice that the "last activity" time only updates if five minutes or more has passed since the last time
|
| 132 | the cookie was written.</p>
|
| 133 |
|
| 134 | <h2>Retrieving Session Data</h2>
|
| 135 |
|
| 136 | <p>Any piece of information from the session array is available using the following function:</p>
|
| 137 |
|
| 138 | <code>$this->session->userdata('<samp>item</samp>');</code>
|
| 139 |
|
| 140 | <p>Where <samp>item</samp> is the array index corresponding to the item you wish to fetch. For example, to fetch the session ID you
|
| 141 | will do this:</p>
|
| 142 |
|
| 143 | <code>$session_id = $this->session->userdata('<samp>session_id</samp>');</code>
|
| 144 |
|
| 145 | <p><strong>Note:</strong> The function returns FALSE (boolean) if the item you are trying to access does not exist.</p>
|
| 146 |
|
| 147 |
|
| 148 | <h2>Adding Custom Session Data</h2>
|
| 149 |
|
| 150 | <p>A useful aspect of the session array is that you can add your own data to it and it will be stored in the user's cookie.
|
| 151 | Why would you want to do this? Here's one example:</p>
|
| 152 |
|
| 153 | <p>Let's say a particular user logs into your site. Once authenticated,
|
| 154 | you could add their username and email address to the session cookie, making that data globally available to you without
|
| 155 | having to run a database query when you need it.</p>
|
| 156 |
|
| 157 | <p>To add your data to the session array involves passing an array containing your new data to this function:</p>
|
| 158 |
|
| 159 | <code>$this->session->set_userdata(<samp>$array</samp>);</code>
|
| 160 |
|
| 161 | <p>Where <samp>$array</samp> is an associative array containing your new data. Here's an example:</p>
|
| 162 |
|
| 163 |
|
| 164 | <code>$newdata = array(<br />
|
| 165 | 'username' => 'johndoe',<br />
|
| 166 | 'email' => 'johndoe@some-site.com',<br />
|
| 167 | 'logged_in' => TRUE<br />
|
| 168 | );<br />
|
| 169 | <br />
|
| 170 | $this->session->set_userdata(<samp>$newdata</samp>);</code>
|
| 171 |
|
| 172 | <p class="important"><strong>Note:</strong> Cookies can only hold 4KB of data, so be careful not to exceed the capacity. The
|
| 173 | encryption process in particular produces a longer data string than the original so keep careful track of how much data you are storing.</p>
|
| 174 |
|
| 175 | <h2>Saving Session Data to a Database</h2>
|
| 176 |
|
| 177 | <p>While the session data array stored in the user's cookie contains a Session ID,
|
| 178 | unless you store session data in a database there is no way to validate it. For some applications that require little or no
|
| 179 | security, session ID validation may not be needed, but if your application requires security, validation is mandatory.</p>
|
| 180 |
|
| 181 | <p>When session data is available in a database, every time a valid session is found in the user's cookie, a database
|
| 182 | query is performed to match it. If the session ID does not match, the session is destroyed. Session IDs can never
|
| 183 | be updated, they can only be generated when a new session is created.</p>
|
| 184 |
|
| 185 | <p>In order to store sessions, you must first create a database table for this purpose. Here is the basic
|
| 186 | prototype required by the session class:</p>
|
| 187 |
|
| 188 | <textarea class="textarea" style="width:100%" cols="50" rows="8">
|
| 189 | CREATE TABLE IF NOT EXISTS `ci_sessions` (
|
| 190 | session_id varchar(40) DEFAULT '0' NOT NULL,
|
| 191 | ip_address varchar(16) DEFAULT '0' NOT NULL,
|
| 192 | user_agent varchar(50) NOT NULL,
|
| 193 | last_activity int(10) unsigned DEFAULT 0 NOT NULL,
|
| 194 | PRIMARY KEY (session_id)
|
| 195 | );</textarea>
|
| 196 |
|
| 197 | <p><strong>Note:</strong> By default the table is called <dfn>ci_sessions</dfn>, but you can name it anything you want
|
| 198 | as long as you update the <kbd>application/config/config.php</kbd> file so that it contains the name you have chosen.
|
| 199 | Once you have created your database table you can enable the database option in your config.php file as follows:</p>
|
| 200 |
|
| 201 | <code>$config['sess_use_database'] = TRUE;</code>
|
| 202 |
|
| 203 | <p>Once enabled, the Session class will store session data in the DB.</p>
|
| 204 |
|
| 205 | <h2>Session Preferences</h2>
|
| 206 |
|
| 207 | <p>You'll find the following Session related preferences in your <kbd>application/config/config.php</kbd> file:</p>
|
| 208 |
|
| 209 |
|
| 210 | <table cellpadding="0" cellspacing="1" border="0" style="width:100%" class="tableborder">
|
| 211 | <tr>
|
| 212 | <th>Preference</th>
|
| 213 | <th>Default</th>
|
| 214 | <th>Options</th>
|
| 215 | <th>Description</th>
|
| 216 |
|
| 217 | </tr><tr>
|
| 218 | <td class="td"><strong>sess_cookie_name</strong></td>
|
| 219 | <td class="td">ci_session</td
|
| 220 | ><td class="td">None</td>
|
| 221 | <td class="td">The name you world the session cookie saved as.</td>
|
| 222 |
|
| 223 | </tr><tr>
|
| 224 | <td class="td"><strong>sess_expiration</strong></td>
|
| 225 | <td class="td">7200</td>
|
| 226 | <td class="td">None</td>
|
| 227 | <td class="td">The number of seconds you would like the session to last. The default value is 2 hours (7200 seconds).
|
| 228 | If you would like a non-expiring session set the value to zero: 0</td>
|
| 229 |
|
| 230 |
|
| 231 | </tr><tr>
|
| 232 | <td class="td"><strong>sess_encrypt_cookie</strong></td>
|
| 233 | <td class="td">TRUE</td>
|
| 234 | <td class="td">TRUE/FALSE (boolean)</td>
|
| 235 | <td class="td">Whether to encrypt the session data.</td>
|
| 236 |
|
| 237 | </tr><tr>
|
| 238 | <td class="td"><strong>sess_use_database</strong></td>
|
| 239 | <td class="td">FALSE</td>
|
| 240 | <td class="td">TRUE/FALSE (boolean)</td>
|
| 241 | <td class="td">Whether to save the session data to a database. You must create the table before enabling this option.</td>
|
| 242 |
|
| 243 | </tr><tr>
|
| 244 | <td class="td"><strong>sess_table_name</strong></td>
|
| 245 | <td class="td">ci_sessions</td
|
| 246 | ><td class="td">Any valid SQL table name</td>
|
| 247 | <td class="td">The name of the session database table.</td>
|
| 248 |
|
| 249 | </tr><tr>
|
| 250 | <td class="td"><strong>sess_match_ip</strong></td>
|
| 251 | <td class="td">FALSE</td>
|
| 252 | <td class="td">TRUE/FALSE (boolean)</td>
|
| 253 | <td class="td">Whether to match the user's IP address when reading the session data. Note that some ISPs dynamically
|
| 254 | changes the IP, so if you want a non-expiring session you will likely set this to FALSE.</td>
|
| 255 |
|
| 256 | </tr><tr>
|
| 257 | <td class="td"><strong>sess_match_useragent</strong></td>
|
| 258 | <td class="td">TRUE</td>
|
| 259 | <td class="td">TRUE/FALSE (boolean)</td>
|
| 260 | <td class="td">Whether to match the User Agent when reading the session data.</td>
|
| 261 |
|
| 262 |
|
| 263 | </tr>
|
| 264 | </table>
|
| 265 |
|
| 266 |
|
| 267 | </div>
|
| 268 | <!-- END CONTENT -->
|
| 269 |
|
| 270 |
|
| 271 | <div id="footer">
|
| 272 | <p>
|
| 273 | Previous Topic: <a href="pagination.html">Pagination Class</a>
|
| 274 | ·
|
| 275 | <a href="#top">Top of Page</a> ·
|
| 276 | <a href="../index.html">User Guide Home</a> ·
|
| 277 | Next Topic: <a href="trackback.html">Trackback Class</a>
|
| 278 | <p>
|
| 279 | <p><a href="http://www.codeigniter.com">Code Igniter</a> · Copyright © 2006 · <a href="http://www.pmachine.com">pMachine, Inc.</a></p>
|
| 280 | </div>
|
| 281 |
|
| 282 | </body>
|
| 283 | </html> |