blob: c8e64f8245e13345a2f553cf690b6d1c09557cb8 [file] [log] [blame]
Derek Allard309d63f2007-08-17 11:49:29 +00001<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
Derek Allardafd99ac2008-01-19 19:59:14 +00002<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
Derek Allard309d63f2007-08-17 11:49:29 +00003<head>
4
Derek Allard8039d4c2008-05-31 02:47:56 +00005<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
Derek Jonesfd93d222008-05-06 15:18:50 +00006<title>Session Class : CodeIgniter User Guide</title>
Derek Allard309d63f2007-08-17 11:49:29 +00007
8<style type='text/css' media='all'>@import url('../userguide.css');</style>
9<link rel='stylesheet' type='text/css' media='all' href='../userguide.css' />
10
11<script type="text/javascript" src="../nav/nav.js"></script>
12<script type="text/javascript" src="../nav/prototype.lite.js"></script>
13<script type="text/javascript" src="../nav/moo.fx.js"></script>
Derek Allardb3412372007-10-25 12:15:16 +000014<script type="text/javascript" src="../nav/user_guide_menu.js"></script>
Derek Allard309d63f2007-08-17 11:49:29 +000015
Derek Allard309d63f2007-08-17 11:49:29 +000016<meta http-equiv='expires' content='-1' />
17<meta http-equiv= 'pragma' content='no-cache' />
18<meta name='robots' content='all' />
Derek Allard3d879d52008-01-18 19:41:32 +000019<meta name='author' content='ExpressionEngine Dev Team' />
Derek Allard309d63f2007-08-17 11:49:29 +000020<meta name='description' content='CodeIgniter User Guide' />
21
22</head>
23<body>
24
25<!-- START NAVIGATION -->
26<div id="nav"><div id="nav_inner"><script type="text/javascript">create_menu('../');</script></div></div>
27<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>
28<div id="masthead">
29<table cellpadding="0" cellspacing="0" border="0" style="width:100%">
30<tr>
Derek Jones1ca3fc42008-06-27 00:19:33 +000031<td><h1>CodeIgniter User Guide Version 1.6.3</h1></td>
Derek Allard309d63f2007-08-17 11:49:29 +000032<td id="breadcrumb_right"><a href="../toc.html">Table of Contents Page</a></td>
33</tr>
34</table>
35</div>
36<!-- END NAVIGATION -->
37
38
39<!-- START BREADCRUMB -->
40<table cellpadding="0" cellspacing="0" border="0" style="width:100%">
41<tr>
42<td id="breadcrumb">
Derek Jones7a9193a2008-01-21 18:39:20 +000043<a href="http://codeigniter.com/">CodeIgniter Home</a> &nbsp;&#8250;&nbsp;
Derek Allard309d63f2007-08-17 11:49:29 +000044<a href="../index.html">User Guide Home</a> &nbsp;&#8250;&nbsp;
45Session Class
46</td>
47<td id="searchbox"><form method="get" action="http://www.google.com/search"><input type="hidden" name="as_sitesearch" id="as_sitesearch" value="codeigniter.com/user_guide/" />Search User Guide&nbsp; <input type="text" class="input" style="width:200px;" name="q" id="q" size="31" maxlength="255" value="" />&nbsp;<input type="submit" class="submit" name="sa" value="Go" /></form></td>
48</tr>
49</table>
50<!-- END BREADCRUMB -->
51
52<br clear="all" />
53
54
55<!-- START CONTENT -->
56<div id="content">
57
58
59<h1>Session Class</h1>
60
61<p>The Session class permits you maintain a user's "state" and track their activity while they browse your site.
62The Session class stores session information for each user as serialized (and optionally encrypted) data in a cookie.
Rick Ellis8a5cd932008-08-20 22:26:55 +000063It can additionally store the session data in a database table for added security, as this permits the session ID in the
Derek Allard309d63f2007-08-17 11:49:29 +000064user's cookie to be matched against the stored session ID. By default only the cookie is saved. If you choose to
Rick Ellis8a5cd932008-08-20 22:26:55 +000065use the database option you'll need to create the session table as indicated below.
Derek Allard309d63f2007-08-17 11:49:29 +000066</p>
67
68<p class="important"><strong>Note:</strong> The Session class does <strong>not</strong> utilize native PHP sessions. It
Rick Ellis8a5cd932008-08-20 22:26:55 +000069generates its own session data so you are not dependent on how a particular hosting environment is set up.</p>
Derek Allard309d63f2007-08-17 11:49:29 +000070
71<h2>Initializing a Session</h2>
72
Rick Ellis8a5cd932008-08-20 22:26:55 +000073<p>The Session routines must happen with each page load (and before anything is outputted to the browser), so the session class must either be
Derek Allard309d63f2007-08-17 11:49:29 +000074<a href="../general/libraries.html">initialized</a> in your
75<a href="../general/controllers.html">controller</a> constructors, or it can be
76<a href="../general/autoloader.html">auto-loaded</a> by the system.
Rick Ellis8a5cd932008-08-20 22:26:55 +000077Once initialized, the Session class will run unattended in the background, reading, writing, and updating the session as needed.</p>
Derek Allard309d63f2007-08-17 11:49:29 +000078
79
80<p>To initialize the Session class manually in your controller constructor, use the <dfn>$this->load->library</dfn> function:</p>
81
82<code>$this->load->library('session');</code>
Rick Ellis8a5cd932008-08-20 22:26:55 +000083
84<p>You can access the Session library object using: <dfn>$this->session</dfn></p>
Derek Allard309d63f2007-08-17 11:49:29 +000085
86
87<h2>How do Sessions work?</h2>
88
Rick Ellis8a5cd932008-08-20 22:26:55 +000089<p>When a page is loaded, the Session class will check to see if valid session data exists in the user's session cookie.
Derek Allard309d63f2007-08-17 11:49:29 +000090If sessions data does <strong>not</strong> exist (or if it has expired) a new session will be created and saved in the cookie.
Rick Ellis8a5cd932008-08-20 22:26:55 +000091If a session <strong>does</strong> exist, its information and cookie will be updated automatically. With each update, the session_id will be regenerated for security.</p>
Derek Allard309d63f2007-08-17 11:49:29 +000092
93<p>It's important for you to understand that once initialized, the Session class runs automatically. There is nothing
94you need to do to cause the above behavior to happen. You can, as you'll see below, work with session data or
95even add your own data to a user's session, but the process of reading, writing, and updating a session is automatic.</p>
96
97
98<h2>What is Session Data?</h2>
99
100<p>A <em>session</em>, as far as CodeIgniter is concerned, is simply an array containing the following information:</p>
101
102<ul>
103<li>The user's unique Session ID (this is a statistically random string with very strong entropy, hashed with MD5 for portability, and regenerated (by default) every five minutes)</li>
104<li>The user's IP Address</li>
105<li>The user's User Agent data (the first 50 characters of the browser data string)</li>
Derek Allard58626b32008-02-11 01:38:10 +0000106<li>The "last activity" time stamp.</li>
Derek Allard309d63f2007-08-17 11:49:29 +0000107</ul>
108
109<p>The above data is stored in a cookie as a serialized array with this prototype:</p>
110
111<code>[array]<br />
112(<br />
113&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;'session_id'&nbsp;&nbsp;&nbsp;&nbsp;=> random hash,<br />
114&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;'ip_address'&nbsp;&nbsp;&nbsp;&nbsp;=> 'string - user IP address',<br />
115&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;'user_agent'&nbsp;&nbsp;&nbsp;&nbsp;=> 'string - user agent data',<br />
Derek Allard58626b32008-02-11 01:38:10 +0000116&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;'last_activity' => timestamp<br />
Derek Allard309d63f2007-08-17 11:49:29 +0000117)</code>
118
119<p>If you have the encryption option enabled, the serialized array will be encrypted before being stored in the cookie,
120making the data highly secure and impervious to being read or altered by someone. More info regarding encryption
121can be <a href="encryption.html">found here</a>, although the Session class will take care of initializing
122and encrypting the data automatically.</p>
123
124<p>Note: Session cookies are only updated every five minutes by default to reduce processor load. If you repeatedly reload a page
125you'll notice that the "last activity" time only updates if five minutes or more has passed since the last time
Derek Allard866b8132008-04-21 22:02:37 +0000126the cookie was written. This time is configurable by changing the $config['time_to_update'] line in your system/config/config.php file.</p>
Derek Allard309d63f2007-08-17 11:49:29 +0000127
128<h2>Retrieving Session Data</h2>
129
130<p>Any piece of information from the session array is available using the following function:</p>
131
132<code>$this->session->userdata('<samp>item</samp>');</code>
133
134<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
135will do this:</p>
136
137<code>$session_id = $this->session->userdata('<samp>session_id</samp>');</code>
138
139<p><strong>Note:</strong> The function returns FALSE (boolean) if the item you are trying to access does not exist.</p>
140
141
142<h2>Adding Custom Session Data</h2>
143
Rick Ellis8a5cd932008-08-20 22:26:55 +0000144<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 session array.
Derek Allard309d63f2007-08-17 11:49:29 +0000145Why would you want to do this? Here's one example:</p>
146
147<p>Let's say a particular user logs into your site. Once authenticated,
148you could add their username and email address to the session cookie, making that data globally available to you without
149having to run a database query when you need it.</p>
150
151<p>To add your data to the session array involves passing an array containing your new data to this function:</p>
152
153<code>$this->session->set_userdata(<samp>$array</samp>);</code>
154
155<p>Where <samp>$array</samp> is an associative array containing your new data. Here's an example:</p>
156
157
158<p><code>$newdata = array(<br />
159 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;'username'&nbsp; => 'johndoe',<br />
160 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;'email'&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;=> 'johndoe@some-site.com',<br />
161 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;'logged_in' => TRUE<br />
162 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;);<br />
163 <br />
164 $this->session->set_userdata(<samp>$newdata</samp>);</code></p>
Rick Ellis8a5cd932008-08-20 22:26:55 +0000165
Derek Allard309d63f2007-08-17 11:49:29 +0000166<p>If you want to add userdata one value at a time, set_userdata() also supports this syntax. </p>
167<p><code>$this-&gt;session-&gt;set_userdata('some_name', 'some_value');</code></p>
Rick Ellis8a5cd932008-08-20 22:26:55 +0000168
169
170<p class="important"><strong>Note:</strong> By default, the session class stores your custom data in the session cookie. Cookies, however, can only hold
1714KB of data, so it is easily possible to exceed the capacity, particularly if you use encryption, since it produces a longer data string than the original.
172If you need to store a larger amount of data it is recommended that you store your session data in a database table. You'll find instructions for this below.</p>
Derek Allard309d63f2007-08-17 11:49:29 +0000173
174<h2>Removing Session Data</h2>
175<p>Just as set_userdata() can be used to add information into a session, unset_userdata() can be used to remove it, by passing the session key. For example, if you wanted to remove 'some_name' from your session information: </p>
176<p><code>$this-&gt;session-&gt;unset_userdata('some_name');</code></p>
Derek Jones4f953532007-09-10 16:37:12 +0000177<p>This function can also be passed an associative array of items to unset.</p>
178<p><code>$array_items = array('username' => '', 'email' => '');<br />
Derek Allard309d63f2007-08-17 11:49:29 +0000179<br />
Derek Jones4f953532007-09-10 16:37:12 +0000180$this-&gt;session-&gt;unset_userdata(<samp>$array_items</samp>);</code></p>
Derek Allard309d63f2007-08-17 11:49:29 +0000181<h2>Flashdata</h2>
Derek Allard2db431b2008-01-22 07:45:30 +0000182<p>CodeIgniter supports &quot;flashdata&quot;, or session data that will only be available for the next server request, and are then automatically cleared. These can be very useful, and are typically used for informational or status messages (for example: &quot;record 2 deleted&quot;).</p>
Derek Allard309d63f2007-08-17 11:49:29 +0000183<p>Note: Flash variables are prefaced with &quot;flash_&quot; so avoid this prefix in your own session names.</p>
184<p>To add flashdata:</p>
185<p><code>$this-&gt;session-&gt;set_flashdata('item', 'value');</code></p>
186<p>You can also pass an array to set_flashdata(), in the same manner as set_userdata(). </p>
187<p>To read a flashdata variable:</p>
188<p><code>$this-&gt;session-&gt;flashdata('item');</code></p>
189<p>If you find that you need to preserve a flashdata variable through an additional request, you can do so using the keep_flashdata() function.</p>
190<p><code>$this-&gt;session-&gt;keep_flashdata('item');</code></p>
191<h2>Saving Session Data to a Database</h2>
192<p>While the session data array stored in the user's cookie contains a Session ID,
193unless you store session data in a database there is no way to validate it. For some applications that require little or no
194security, session ID validation may not be needed, but if your application requires security, validation is mandatory.</p>
195
196<p>When session data is available in a database, every time a valid session is found in the user's cookie, a database
Rick Ellis8a5cd932008-08-20 22:26:55 +0000197query is performed to match it. If the session ID does not match, the session is destroyed.</p>
198
199<p>An additional benefit of using a database is that it permits you to store custom data along with the session. Earlier in this page we described how to add
200custom data to your session. When you use the database feature, your custom data will be stored automatically in the database <strong>instead</strong> of in
201the user's cookie.</p>
202
Derek Allard309d63f2007-08-17 11:49:29 +0000203
204<p>In order to store sessions, you must first create a database table for this purpose. Here is the basic
205prototype (for MySQL) required by the session class:</p>
206
207<textarea class="textarea" style="width:100%" cols="50" rows="8">
208CREATE TABLE IF NOT EXISTS `ci_sessions` (
209session_id varchar(40) DEFAULT '0' NOT NULL,
210ip_address varchar(16) DEFAULT '0' NOT NULL,
211user_agent varchar(50) NOT NULL,
212last_activity int(10) unsigned DEFAULT 0 NOT NULL,
Rick Ellis8a5cd932008-08-20 22:26:55 +0000213user_data text NOT NULL,
Derek Allard309d63f2007-08-17 11:49:29 +0000214PRIMARY KEY (session_id)
215);</textarea>
216
Rick Ellis8a5cd932008-08-20 22:26:55 +0000217<p><strong>Note:</strong> By default the table is named <dfn>ci_sessions</dfn>, but you can name it anything you want
218as long as you update the <kbd>application/config/config.php</kbd> file so that it contains the name you have chosen. The Session class, however,
219expects the column names to be identical to the ones indicated above.</p>
220
221<p>Once you have created your database table you can enable the database option in your config.php file as follows:</p>
Derek Allard309d63f2007-08-17 11:49:29 +0000222
223<code>$config['sess_use_database'] = TRUE;</code>
224
225<p>Once enabled, the Session class will store session data in the DB.</p>
226
227<p>Make sure you've specified the table name in your config file as well:</p>
228
229<code>$config['sess_table_name'] = 'ci_sessions";</code>
230
Rick Ellis8a5cd932008-08-20 22:26:55 +0000231<p class="important"><strong>Note:</strong> The Session class has a built-in garbage collection routine which clears out expired sessions periodically so you
Derek Allard309d63f2007-08-17 11:49:29 +0000232do not need to write your own routine to do it.</p>
233
234
235<h2>Destroying a Session </h2>
236<p>To clear the current session: </p>
237<code>$this-&gt;session-&gt;sess_destroy();</code>
Derek Allard112f4a72008-03-19 11:36:07 +0000238<p class="important"><strong>Note:</strong> This function should be the last one called, and even flash variables will no longer be available. If you only want some items destroyed and not all, use <dfn>unset_userdata()</dfn>.</p>
239
240
241
Derek Allard309d63f2007-08-17 11:49:29 +0000242<h2>Session Preferences</h2>
Rick Ellis8a5cd932008-08-20 22:26:55 +0000243<p>Normally you will set the Session preferences in your <kbd>application/config/config.php</kbd> file.</p>
244
245<p>If you prefer to set any of the preferences manually you can do so when you load the session class, by passing an array of values you
246wish to set in the second parameter as follows:</p>
247
248<code>
249$session_vals = array(<br />
250&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;'sess_expiration' = 10800,<br />
251&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;'sess_match_ip' &nbsp;&nbsp;= TRUE<br />
252&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;);<br />
253<br />
254$this->load->library('session', $session_vals);
255</code>
256
257<p>The following table lists the available preferences:</p>
Derek Allard309d63f2007-08-17 11:49:29 +0000258
259
260<table cellpadding="0" cellspacing="1" border="0" style="width:100%" class="tableborder">
261<tr>
Derek Allard5b0a8812008-01-21 14:26:33 +0000262 <th>Preference</th>
263 <th>Default</th>
264 <th>Options</th>
265 <th>Description</th>
266</tr>
267<tr>
268 <td class="td"><strong>sess_cookie_name</strong></td>
269 <td class="td">ci_session</td>
270 <td class="td">None</td>
Derek Allard9b9a18e2008-03-31 19:41:03 +0000271 <td class="td">The name you want the session cookie saved as.</td>
Derek Allard5b0a8812008-01-21 14:26:33 +0000272</tr>
273<tr>
274 <td class="td"><strong>sess_expiration</strong></td>
275 <td class="td">7200</td>
276 <td class="td">None</td>
277 <td class="td">The number of seconds you would like the session to last. The default value is 2 hours (7200 seconds). If you would like a non-expiring session set the value to zero: 0</td>
278</tr>
279<tr>
280 <td class="td"><strong>sess_encrypt_cookie</strong></td>
281 <td class="td">FALSE</td>
282 <td class="td">TRUE/FALSE (boolean)</td>
283 <td class="td">Whether to encrypt the session data.</td>
284</tr>
285<tr>
286 <td class="td"><strong>sess_use_database</strong></td>
287 <td class="td">FALSE</td>
288 <td class="td">TRUE/FALSE (boolean)</td>
289 <td class="td">Whether to save the session data to a database. You must create the table before enabling this option.</td>
290</tr>
291<tr>
292 <td class="td"><strong>sess_table_name</strong></td>
293 <td class="td">ci_sessions</td>
294 <td class="td">Any valid SQL table name</td>
295 <td class="td">The name of the session database table.</td>
296</tr>
297<tr>
298 <td class="td"><strong>sess_time_to_update</strong></td>
299 <td class="td">300</td>
Derek Allard1a6cdd12008-02-07 18:46:17 +0000300 <td class="td">Time in seconds</td>
Derek Allard5b0a8812008-01-21 14:26:33 +0000301 <td class="td">This options controls how often the session class will regenerate itself and create a new session id.</td>
302</tr>
303<tr>
304 <td class="td"><strong>sess_match_ip</strong></td>
305 <td class="td">FALSE</td>
306 <td class="td">TRUE/FALSE (boolean)</td>
307 <td class="td">Whether to match the user's IP address when reading the session data. Note that some ISPs dynamically
308 changes the IP, so if you want a non-expiring session you will likely set this to FALSE.</td>
309</tr>
310<tr>
311 <td class="td"><strong>sess_match_useragent</strong></td>
312 <td class="td">TRUE</td>
313 <td class="td">TRUE/FALSE (boolean)</td>
314 <td class="td">Whether to match the User Agent when reading the session data.</td>
Derek Allard309d63f2007-08-17 11:49:29 +0000315</tr>
Rick Ellis8a5cd932008-08-20 22:26:55 +0000316<tr>
317 <td class="td"><strong>sess_cookie_name</strong></td>
318 <td class="td">ci_session</td>
319 <td class="td">None</td>
320 <td class="td">The name of the session cookie</td>
321</tr>
Derek Allard309d63f2007-08-17 11:49:29 +0000322</table>
323
324
325</div>
326<!-- END CONTENT -->
327
328
329<div id="footer">
330<p>
331Previous Topic:&nbsp;&nbsp;<a href="pagination.html">Pagination Class</a>
332&nbsp;&nbsp;&nbsp;&middot;&nbsp;&nbsp;
333<a href="#top">Top of Page</a>&nbsp;&nbsp;&nbsp;&middot;&nbsp;&nbsp;
334<a href="../index.html">User Guide Home</a>&nbsp;&nbsp;&nbsp;&middot;&nbsp;&nbsp;
335Next Topic:&nbsp;&nbsp;<a href="trackback.html">Trackback Class</a>
336</p>
Derek Jones07870432008-02-13 03:49:26 +0000337<p><a href="http://codeigniter.com">CodeIgniter</a> &nbsp;&middot;&nbsp; Copyright &#169; 2006-2008 &nbsp;&middot;&nbsp; <a href="http://ellislab.com/">Ellislab, Inc.</a></p>
Derek Allard309d63f2007-08-17 11:49:29 +0000338</div>
339
340</body>
adminb0dd10f2006-08-25 17:25:49 +0000341</html>