Gitiles
Code Review Sign In
www.giggi.me / code-igniter-v3-giggi / 691010e72ec7fb4a05740332a10b5f046a82c666 / . / user_guide / libraries / sessions.html
blob: 5a3c4ae213ff84c663e603df52416b61ce61fed1 [file] [log] [blame]
adminb0dd10f2006-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
Derek Allardd2df9bc2007-04-15 17:41:17 +0000[diff] [blame]5<title>CodeIgniter User Guide</title>
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]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
admin17a890d2006-09-27 20:42:42 +0000[diff] [blame]10<script type="text/javascript" src="../nav/nav.js"></script>
admin2296fc32006-09-27 21:07:02 +0000[diff] [blame]11<script type="text/javascript" src="../nav/prototype.lite.js"></script>
admin17a890d2006-09-27 20:42:42 +0000[diff] [blame]12<script type="text/javascript" src="../nav/moo.fx.js"></script>
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]13<script type="text/javascript">
14window.onload = function() {
admine334c472006-10-21 19:44:22 +0000[diff] [blame]15 myHeight = new fx.Height('nav', {duration: 400});
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]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' />
Derek Allardd2df9bc2007-04-15 17:41:17 +0000[diff] [blame]25<meta name='description' content='CodeIgniter User Guide' />
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]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>
Derek Allardd2df9bc2007-04-15 17:41:17 +0000[diff] [blame]36<td><h1>CodeIgniter User Guide Version 1.5.3</h1></td>
adminc0d5d522006-10-30 19:40:35 +0000[diff] [blame]37<td id="breadcrumb_right"><a href="../toc.html">Table of Contents Page</a></td>
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]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">
Derek Allardd2df9bc2007-04-15 17:41:17 +0000[diff] [blame]48<a href="http://www.codeigniter.com/">CodeIgniter Home</a> &nbsp;&#8250;&nbsp;
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]49<a href="../index.html">User Guide Home</a> &nbsp;&#8250;&nbsp;
50Session Class
51</td>
Derek Allardbc030912007-06-24 18:25:29 +0000[diff] [blame]52<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>
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]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
admine334c472006-10-21 19:44:22 +0000[diff] [blame]66<p>The Session class permits you maintain a user's "state" and track their activity while they browse your site.
67The Session class stores session information for each user as serialized (and optionally encrypted) data in a cookie.
68It can also store the session data in a database table for added security, as this permits the session ID in the
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]69user's cookie to be matched against the stored session ID. By default only the cookie is saved. If you choose to
70use 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
74generates its own session data, offering more flexibility for developers.</p>
75
76<h2>Initializing a Session</h2>
77
admine334c472006-10-21 19:44:22 +0000[diff] [blame]78<p>Sessions will typically run globally with each page load, so the session class must either be
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]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.
82For the most part the session class will run unattended in the background, so simply initializing the class
83will 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
admine334c472006-10-21 19:44:22 +0000[diff] [blame]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.
95If sessions data does <strong>not</strong> exist (or if it has expired) a new session will be created and saved in the cookie.
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]96If 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
99you need to do to cause the above behavior to happen. You can, as you'll see below, work with session data or
100even 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
Derek Allardd2df9bc2007-04-15 17:41:17 +0000[diff] [blame]105<p>A <em>session</em>, as far as CodeIgniter is concerned, is simply an array containing the following information:</p>
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]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&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;'session_id'&nbsp;&nbsp;&nbsp;&nbsp;=> random hash,<br />
119&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;'ip_address'&nbsp;&nbsp;&nbsp;&nbsp;=> 'string - user IP address',<br />
120&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;'user_agent'&nbsp;&nbsp;&nbsp;&nbsp;=> 'string - user agent data',<br />
121&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;'last_activity' => timestamp,<br />
122&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;'last_visit'&nbsp;&nbsp;&nbsp;&nbsp;=> 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,
126making the data highly secure and impervious to being read or altered by someone. More info regarding encryption
127can be <a href="encryption.html">found here</a>, although the Session class will take care of initializing
128and 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
131you'll notice that the "last activity" time only updates if five minutes or more has passed since the last time
132the 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
admine334c472006-10-21 19:44:22 +0000[diff] [blame]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
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]141will 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.
151Why 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,
154you could add their username and email address to the session cookie, making that data globally available to you without
155having 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
Derek Allardc1ee65b2007-02-04 16:18:03 +0000[diff] [blame]164<p><code>$newdata = array(<br />
165 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;'username'&nbsp; => 'johndoe',<br />
166 &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 />
167 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;'logged_in' => TRUE<br />
168 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;);<br />
169 <br />
170 $this->session->set_userdata(<samp>$newdata</samp>);</code></p>
171<p>If you want to add userdata one value at a time, set_userdata() also supports this syntax. </p>
172<p><code>$this-&gt;session-&gt;set_userdata('some_name', 'some_value');</code></p>
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]173<p class="important"><strong>Note:</strong> Cookies can only hold 4KB of data, so be careful not to exceed the capacity. The
174encryption process in particular produces a longer data string than the original so keep careful track of how much data you are storing.</p>
175
176<h2>Saving Session Data to a Database</h2>
177
178<p>While the session data array stored in the user's cookie contains a Session ID,
179unless you store session data in a database there is no way to validate it. For some applications that require little or no
admine334c472006-10-21 19:44:22 +0000[diff] [blame]180security, session ID validation may not be needed, but if your application requires security, validation is mandatory.</p>
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]181
182<p>When session data is available in a database, every time a valid session is found in the user's cookie, a database
183query is performed to match it. If the session ID does not match, the session is destroyed. Session IDs can never
184be updated, they can only be generated when a new session is created.</p>
185
admine334c472006-10-21 19:44:22 +0000[diff] [blame]186<p>In order to store sessions, you must first create a database table for this purpose. Here is the basic
admin990e3c62006-09-17 18:47:00 +0000[diff] [blame]187prototype (for MySQL) required by the session class:</p>
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]188
189<textarea class="textarea" style="width:100%" cols="50" rows="8">
190CREATE TABLE IF NOT EXISTS `ci_sessions` (
191session_id varchar(40) DEFAULT '0' NOT NULL,
192ip_address varchar(16) DEFAULT '0' NOT NULL,
193user_agent varchar(50) NOT NULL,
194last_activity int(10) unsigned DEFAULT 0 NOT NULL,
195PRIMARY KEY (session_id)
196);</textarea>
197
198<p><strong>Note:</strong> By default the table is called <dfn>ci_sessions</dfn>, but you can name it anything you want
199as long as you update the <kbd>application/config/config.php</kbd> file so that it contains the name you have chosen.
200Once you have created your database table you can enable the database option in your config.php file as follows:</p>
201
202<code>$config['sess_use_database'] = TRUE;</code>
203
204<p>Once enabled, the Session class will store session data in the DB.</p>
205
admin990e3c62006-09-17 18:47:00 +0000[diff] [blame]206<p>Make sure you've specified the table name in your config file as well:</p>
207
208<code>$config['sess_table_name'] = 'ci_sessions";</code>
209
210<p class="important"><strong>Note:</strong> The Session class has built-in garbage collection which clears out expired sessions so you
211do not need to write your own routine to do it.</p>
212
213
Derek Allarde0135cf2007-02-02 03:47:40 +0000[diff] [blame]214<h2>Destroying a Session </h2>
215<p>To clear the current session: </p>
216<code>$this-&gt;session-&gt;sess_destroy();</code>
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]217<h2>Session Preferences</h2>
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]218<p>You'll find the following Session related preferences in your <kbd>application/config/config.php</kbd> file:</p>
219
220
221<table cellpadding="0" cellspacing="1" border="0" style="width:100%" class="tableborder">
222<tr>
223<th>Preference</th>
224<th>Default</th>
225<th>Options</th>
226<th>Description</th>
227
228</tr><tr>
229<td class="td"><strong>sess_cookie_name</strong></td>
230<td class="td">ci_session</td
231><td class="td">None</td>
232<td class="td">The name you world the session cookie saved as.</td>
233
234</tr><tr>
235<td class="td"><strong>sess_expiration</strong></td>
236<td class="td">7200</td>
237<td class="td">None</td>
admine334c472006-10-21 19:44:22 +0000[diff] [blame]238<td class="td">The number of seconds you would like the session to last. The default value is 2 hours (7200 seconds).
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]239If you would like a non-expiring session set the value to zero: 0</td>
240
241
242</tr><tr>
243<td class="td"><strong>sess_encrypt_cookie</strong></td>
Rick Ellis325197e2006-11-20 17:29:05 +0000[diff] [blame]244<td class="td">FALSE</td>
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]245<td class="td">TRUE/FALSE (boolean)</td>
246<td class="td">Whether to encrypt the session data.</td>
247
248</tr><tr>
249<td class="td"><strong>sess_use_database</strong></td>
250<td class="td">FALSE</td>
251<td class="td">TRUE/FALSE (boolean)</td>
252<td class="td">Whether to save the session data to a database. You must create the table before enabling this option.</td>
253
254</tr><tr>
255<td class="td"><strong>sess_table_name</strong></td>
256<td class="td">ci_sessions</td
257><td class="td">Any valid SQL table name</td>
258<td class="td">The name of the session database table.</td>
259
260</tr><tr>
261<td class="td"><strong>sess_match_ip</strong></td>
262<td class="td">FALSE</td>
263<td class="td">TRUE/FALSE (boolean)</td>
264<td class="td">Whether to match the user's IP address when reading the session data. Note that some ISPs dynamically
265changes the IP, so if you want a non-expiring session you will likely set this to FALSE.</td>
266
267</tr><tr>
268<td class="td"><strong>sess_match_useragent</strong></td>
269<td class="td">TRUE</td>
270<td class="td">TRUE/FALSE (boolean)</td>
271<td class="td">Whether to match the User Agent when reading the session data.</td>
272
273
274</tr>
275</table>
276
277
278</div>
279<!-- END CONTENT -->
280
281
282<div id="footer">
283<p>
284Previous Topic:&nbsp;&nbsp;<a href="pagination.html">Pagination Class</a>
285&nbsp;&nbsp;&nbsp;&middot;&nbsp;&nbsp;
286<a href="#top">Top of Page</a>&nbsp;&nbsp;&nbsp;&middot;&nbsp;&nbsp;
287<a href="../index.html">User Guide Home</a>&nbsp;&nbsp;&nbsp;&middot;&nbsp;&nbsp;
288Next Topic:&nbsp;&nbsp;<a href="trackback.html">Trackback Class</a>
289<p>
Derek Allardd2df9bc2007-04-15 17:41:17 +0000[diff] [blame]290<p><a href="http://www.codeigniter.com">CodeIgniter</a> &nbsp;&middot;&nbsp; Copyright &#169; 2007 &nbsp;&middot;&nbsp; <a href="http://ellislab.com/">Ellislab, Inc.</a></p>
adminb0dd10f2006-08-25 17:25:49 +0000[diff] [blame]291</div>
292
293</body>
294</html>