summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorDerek Allard <derek.allard@ellislab.com>2007-08-17 13:49:29 +0200
committerDerek Allard <derek.allard@ellislab.com>2007-08-17 13:49:29 +0200
commit309d63fa5c011c5cf0fbe0c78ab5f294aaae6752 (patch)
tree4888e33bb89d549073ae16421add32399305c672
parentfc40afda438195ec3d6f2a4c61477f7c09ec5e1a (diff)
Documented unset_userdata in the Session class.
-rw-r--r--user_guide/changelog.html19
-rw-r--r--user_guide/libraries/sessions.html611
2 files changed, 319 insertions, 311 deletions
diff --git a/user_guide/changelog.html b/user_guide/changelog.html
index e11bdc7dd..e96e18ee2 100644
--- a/user_guide/changelog.html
+++ b/user_guide/changelog.html
@@ -65,20 +65,21 @@ Change Log
<h2>Version 1.5.5</h2>
<p>Release Date: -- still in development </p>
<ul>
- <li>Added Flashdata variables, session_id regeneration and configurable session update times to the <a href="./libraries/sessions.html">Session class</a> </li>
+ <li>Added Flashdata variables, session_id regeneration and configurable session update times to the <a href="./libraries/sessions.html">Session class.</a></li>
<li>Added $this->DB->save_queries variable to DB driver, enabling queries to get saved or no. Previously they were always saved.</li>
<li>Added <dfn>$assign_to_controller</dfn> variable in the main <kbd>index.php</kbd> file. Anything that this variable contains will be passed automatically to a controller constructor when initialized.</li>
<li>Reorganized the URI and Routes classes for better clarity.</li>
- <li>Javascript Calendar plugin now uses the months and days from the calendar language file, instead of hard-coded values, internationalizing it </li>
+ <li>Javascript Calendar plugin now uses the months and days from the calendar language file, instead of hard-coded values, internationalizing it.</li>
<li>Removed &quot;rand()&quot; as a listed option from orderby in the <a href="./database/active_record.html">Active Record</a>, as it was MySQL only. </li>
- <li>Added titles to all user manual pages</li>
- <li>Documented the timezones() function in the <a href="./helpers/date_helper.html">Date Helper</a></li>
- <li>Fixed a bug in database driver where num_rows property wasn't getting updated </li>
- <li>Fixed a bug in captcha calling an invalid PHP function</li>
- <li>Fixed a bug in _html_entity_decode_callback() when 'global_xss_filtering' is enabled.</li>
+ <li>Added titles to all user manual pages.</li>
+ <li>Documented the timezones() function in the <a href="./helpers/date_helper.html">Date Helper</a>.</li>
+ <li>Documented unset_userdata in the <a href="./libraries/sessions.html">Session class</a>.</li>
+ <li>Fixed a bug in database driver where num_rows property wasn't getting updated.</li>
+ <li>Fixed a bug in captcha calling an invalid PHP function.</li>
+ <li>Fixed a bug in _html_entity_decode_callback() when 'global_xss_filtering' is enabled.</li>
<li>Fixed a bug in the cookie helper "set_cookie" function. It was not honoring the config settings.</li>
- <li>Fixed an example of comma-separated emails in the email library documentation</li>
- <li>Fixed a typo in the DocBlock comment for unset_userdata() in Session </li>
+ <li>Fixed an example of comma-separated emails in the email library documentation.</li>
+ <li>Fixed a typo in the DocBlock comment for unset_userdata() in Session.</li>
</ul>
diff --git a/user_guide/libraries/sessions.html b/user_guide/libraries/sessions.html
index a6ade694e..22d46e665 100644
--- a/user_guide/libraries/sessions.html
+++ b/user_guide/libraries/sessions.html
@@ -1,303 +1,310 @@
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
-<html>
-<head>
-
-<title>CodeIgniter User Guide</title>
-
-<style type='text/css' media='all'>@import url('../userguide.css');</style>
-<link rel='stylesheet' type='text/css' media='all' href='../userguide.css' />
-
-<script type="text/javascript" src="../nav/nav.js"></script>
-<script type="text/javascript" src="../nav/prototype.lite.js"></script>
-<script type="text/javascript" src="../nav/moo.fx.js"></script>
-<script type="text/javascript">
-window.onload = function() {
- myHeight = new fx.Height('nav', {duration: 400});
- myHeight.hide();
-}
-</script>
-
-<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
-<meta http-equiv='expires' content='-1' />
-<meta http-equiv= 'pragma' content='no-cache' />
-<meta name='robots' content='all' />
-<meta name='author' content='Rick Ellis' />
-<meta name='description' content='CodeIgniter User Guide' />
-
-</head>
-<body>
-
-<!-- START NAVIGATION -->
-<div id="nav"><div id="nav_inner"><script type="text/javascript">create_menu('../');</script></div></div>
-<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>
-<div id="masthead">
-<table cellpadding="0" cellspacing="0" border="0" style="width:100%">
-<tr>
-<td><h1>CodeIgniter User Guide Version 1.5.3</h1></td>
-<td id="breadcrumb_right"><a href="../toc.html">Table of Contents Page</a></td>
-</tr>
-</table>
-</div>
-<!-- END NAVIGATION -->
-
-
-<!-- START BREADCRUMB -->
-<table cellpadding="0" cellspacing="0" border="0" style="width:100%">
-<tr>
-<td id="breadcrumb">
-<a href="http://www.codeigniter.com/">CodeIgniter Home</a> &nbsp;&#8250;&nbsp;
-<a href="../index.html">User Guide Home</a> &nbsp;&#8250;&nbsp;
-Session Class
-</td>
-<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>
-</tr>
-</table>
-<!-- END BREADCRUMB -->
-
-<br clear="all" />
-
-
-<!-- START CONTENT -->
-<div id="content">
-
-
-<h1>Session Class</h1>
-
-<p>The Session class permits you maintain a user's "state" and track their activity while they browse your site.
-The Session class stores session information for each user as serialized (and optionally encrypted) data in a cookie.
-It can also store the session data in a database table for added security, as this permits the session ID in the
-user's cookie to be matched against the stored session ID. By default only the cookie is saved. If you choose to
-use the database option you'll need to create the session table as indicated below.
-</p>
-
-<p class="important"><strong>Note:</strong> The Session class does <strong>not</strong> utilize native PHP sessions. It
-generates its own session data, offering more flexibility for developers.</p>
-
-<h2>Initializing a Session</h2>
-
-<p>Sessions will typically run globally with each page load, so the session class must either be
-<a href="../general/libraries.html">initialized</a> in your
-<a href="../general/controllers.html">controller</a> constructors, or it can be
-<a href="../general/autoloader.html">auto-loaded</a> by the system.
-For the most part the session class will run unattended in the background, so simply initializing the class
-will cause it to read, create, and update sessions.</p>
-
-
-<p>To initialize the Session class manually in your controller constructor, use the <dfn>$this->load->library</dfn> function:</p>
-
-<code>$this->load->library('session');</code>
-<p>Once loaded, the Sessions library object will be available using: <dfn>$this->session</dfn></p>
-
-
-<h2>How do Sessions work?</h2>
-
-<p>When a page is loaded, the session class will check to see if valid session data exists in the user's session cookie.
-If sessions data does <strong>not</strong> exist (or if it has expired) a new session will be created and saved in the cookie.
-If a session does exist, its information will be updated and the cookie will be updated. With each update, the session_id will be regenerated.</p>
-
-<p>It's important for you to understand that once initialized, the Session class runs automatically. There is nothing
-you need to do to cause the above behavior to happen. You can, as you'll see below, work with session data or
-even add your own data to a user's session, but the process of reading, writing, and updating a session is automatic.</p>
-
-
-<h2>What is Session Data?</h2>
-
-<p>A <em>session</em>, as far as CodeIgniter is concerned, is simply an array containing the following information:</p>
-
-<ul>
-<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>
-<li>The user's IP Address</li>
-<li>The user's User Agent data (the first 50 characters of the browser data string)</li>
-<li>The "last activity" and "last visit" time stamps.</li>
-</ul>
-
-<p>The above data is stored in a cookie as a serialized array with this prototype:</p>
-
-<code>[array]<br />
-(<br />
-&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;'session_id'&nbsp;&nbsp;&nbsp;&nbsp;=> random hash,<br />
-&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;'ip_address'&nbsp;&nbsp;&nbsp;&nbsp;=> 'string - user IP address',<br />
-&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;'user_agent'&nbsp;&nbsp;&nbsp;&nbsp;=> 'string - user agent data',<br />
-&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;'last_activity' => timestamp,<br />
-&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;'last_visit'&nbsp;&nbsp;&nbsp;&nbsp;=> timestamp<br />
-)</code>
-
-<p>If you have the encryption option enabled, the serialized array will be encrypted before being stored in the cookie,
-making the data highly secure and impervious to being read or altered by someone. More info regarding encryption
-can be <a href="encryption.html">found here</a>, although the Session class will take care of initializing
-and encrypting the data automatically.</p>
-
-<p>Note: Session cookies are only updated every five minutes by default to reduce processor load. If you repeatedly reload a page
-you'll notice that the "last activity" time only updates if five minutes or more has passed since the last time
-the cookie was written. This time is configurable my changing the $config['time_to_update'] line in your system/config/config.php file.</p>
-
-<h2>Retrieving Session Data</h2>
-
-<p>Any piece of information from the session array is available using the following function:</p>
-
-<code>$this->session->userdata('<samp>item</samp>');</code>
-
-<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
-will do this:</p>
-
-<code>$session_id = $this->session->userdata('<samp>session_id</samp>');</code>
-
-<p><strong>Note:</strong> The function returns FALSE (boolean) if the item you are trying to access does not exist.</p>
-
-
-<h2>Adding Custom Session Data</h2>
-
-<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.
-Why would you want to do this? Here's one example:</p>
-
-<p>Let's say a particular user logs into your site. Once authenticated,
-you could add their username and email address to the session cookie, making that data globally available to you without
-having to run a database query when you need it.</p>
-
-<p>To add your data to the session array involves passing an array containing your new data to this function:</p>
-
-<code>$this->session->set_userdata(<samp>$array</samp>);</code>
-
-<p>Where <samp>$array</samp> is an associative array containing your new data. Here's an example:</p>
-
-
-<p><code>$newdata = array(<br />
- &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;'username'&nbsp; => 'johndoe',<br />
- &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 />
- &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;'logged_in' => TRUE<br />
- &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;);<br />
- <br />
- $this->session->set_userdata(<samp>$newdata</samp>);</code></p>
-<p>If you want to add userdata one value at a time, set_userdata() also supports this syntax. </p>
-<p><code>$this-&gt;session-&gt;set_userdata('some_name', 'some_value');</code></p>
-<p class="important"><strong>Note:</strong> Cookies can only hold 4KB of data, so be careful not to exceed the capacity. The
-encryption process in particular produces a longer data string than the original so keep careful track of how much data you are storing.</p>
-
-<h2>Flashdata</h2>
-<p>CodeIgniter supports &quot;flashdata&quot;, or session data that will only ba 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>
-<p>Note: Flash variables are prefaced with &quot;flash_&quot; so avoid this prefix in your own session names.</p>
-<p>To add flashdata:</p>
-<p><code>$this-&gt;session-&gt;set_flashdata('item', 'value');</code></p>
-<p>You can also pass an array to set_flashdata(), in the same manner as set_userdata(). </p>
-<p>To read a flashdata variable:</p>
-<p><code>$this-&gt;session-&gt;flashdata('item');</code></p>
-<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>
-<p><code>$this-&gt;session-&gt;keep_flashdata('item');</code></p>
-<h2>Saving Session Data to a Database</h2>
-<p>While the session data array stored in the user's cookie contains a Session ID,
-unless you store session data in a database there is no way to validate it. For some applications that require little or no
-security, session ID validation may not be needed, but if your application requires security, validation is mandatory.</p>
-
-<p>When session data is available in a database, every time a valid session is found in the user's cookie, a database
-query is performed to match it. If the session ID does not match, the session is destroyed. Session IDs can never
-be updated, they can only be generated when a new session is created.</p>
-
-<p>In order to store sessions, you must first create a database table for this purpose. Here is the basic
-prototype (for MySQL) required by the session class:</p>
-
-<textarea class="textarea" style="width:100%" cols="50" rows="8">
-CREATE TABLE IF NOT EXISTS `ci_sessions` (
-session_id varchar(40) DEFAULT '0' NOT NULL,
-ip_address varchar(16) DEFAULT '0' NOT NULL,
-user_agent varchar(50) NOT NULL,
-last_activity int(10) unsigned DEFAULT 0 NOT NULL,
-PRIMARY KEY (session_id)
-);</textarea>
-
-<p><strong>Note:</strong> By default the table is called <dfn>ci_sessions</dfn>, but you can name it anything you want
-as long as you update the <kbd>application/config/config.php</kbd> file so that it contains the name you have chosen.
-Once you have created your database table you can enable the database option in your config.php file as follows:</p>
-
-<code>$config['sess_use_database'] = TRUE;</code>
-
-<p>Once enabled, the Session class will store session data in the DB.</p>
-
-<p>Make sure you've specified the table name in your config file as well:</p>
-
-<code>$config['sess_table_name'] = 'ci_sessions";</code>
-
-<p class="important"><strong>Note:</strong> The Session class has built-in garbage collection which clears out expired sessions so you
-do not need to write your own routine to do it.</p>
-
-
-<h2>Destroying a Session </h2>
-<p>To clear the current session: </p>
-<code>$this-&gt;session-&gt;sess_destroy();</code>
-<h2>Session Preferences</h2>
-<p>You'll find the following Session related preferences in your <kbd>application/config/config.php</kbd> file:</p>
-
-
-<table cellpadding="0" cellspacing="1" border="0" style="width:100%" class="tableborder">
-<tr>
-<th>Preference</th>
-<th>Default</th>
-<th>Options</th>
-<th>Description</th>
-
-</tr><tr>
-<td class="td"><strong>sess_cookie_name</strong></td>
-<td class="td">ci_session</td
-><td class="td">None</td>
-<td class="td">The name you world the session cookie saved as.</td>
-
-</tr><tr>
-<td class="td"><strong>sess_expiration</strong></td>
-<td class="td">7200</td>
-<td class="td">None</td>
-<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>
-
-
-</tr><tr>
-<td class="td"><strong>sess_encrypt_cookie</strong></td>
-<td class="td">FALSE</td>
-<td class="td">TRUE/FALSE (boolean)</td>
-<td class="td">Whether to encrypt the session data.</td>
-
-</tr><tr>
-<td class="td"><strong>sess_use_database</strong></td>
-<td class="td">FALSE</td>
-<td class="td">TRUE/FALSE (boolean)</td>
-<td class="td">Whether to save the session data to a database. You must create the table before enabling this option.</td>
-
-</tr><tr>
-<td class="td"><strong>sess_table_name</strong></td>
-<td class="td">ci_sessions</td
-><td class="td">Any valid SQL table name</td>
-<td class="td">The name of the session database table.</td>
-
-</tr><tr>
-<td class="td"><strong>sess_match_ip</strong></td>
-<td class="td">FALSE</td>
-<td class="td">TRUE/FALSE (boolean)</td>
-<td class="td">Whether to match the user's IP address when reading the session data. Note that some ISPs dynamically
-changes the IP, so if you want a non-expiring session you will likely set this to FALSE.</td>
-
-</tr><tr>
-<td class="td"><strong>sess_match_useragent</strong></td>
-<td class="td">TRUE</td>
-<td class="td">TRUE/FALSE (boolean)</td>
-<td class="td">Whether to match the User Agent when reading the session data.</td>
-
-
-</tr>
-</table>
-
-
-</div>
-<!-- END CONTENT -->
-
-
-<div id="footer">
-<p>
-Previous Topic:&nbsp;&nbsp;<a href="pagination.html">Pagination Class</a>
-&nbsp;&nbsp;&nbsp;&middot;&nbsp;&nbsp;
-<a href="#top">Top of Page</a>&nbsp;&nbsp;&nbsp;&middot;&nbsp;&nbsp;
-<a href="../index.html">User Guide Home</a>&nbsp;&nbsp;&nbsp;&middot;&nbsp;&nbsp;
-Next Topic:&nbsp;&nbsp;<a href="trackback.html">Trackback Class</a>
-</p>
-<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>
-</div>
-
-</body>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html>
+<head>
+
+<title>CodeIgniter User Guide</title>
+
+<style type='text/css' media='all'>@import url('../userguide.css');</style>
+<link rel='stylesheet' type='text/css' media='all' href='../userguide.css' />
+
+<script type="text/javascript" src="../nav/nav.js"></script>
+<script type="text/javascript" src="../nav/prototype.lite.js"></script>
+<script type="text/javascript" src="../nav/moo.fx.js"></script>
+<script type="text/javascript">
+window.onload = function() {
+ myHeight = new fx.Height('nav', {duration: 400});
+ myHeight.hide();
+}
+</script>
+
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+<meta http-equiv='expires' content='-1' />
+<meta http-equiv= 'pragma' content='no-cache' />
+<meta name='robots' content='all' />
+<meta name='author' content='Rick Ellis' />
+<meta name='description' content='CodeIgniter User Guide' />
+
+</head>
+<body>
+
+<!-- START NAVIGATION -->
+<div id="nav"><div id="nav_inner"><script type="text/javascript">create_menu('../');</script></div></div>
+<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>
+<div id="masthead">
+<table cellpadding="0" cellspacing="0" border="0" style="width:100%">
+<tr>
+<td><h1>CodeIgniter User Guide Version 1.5.3</h1></td>
+<td id="breadcrumb_right"><a href="../toc.html">Table of Contents Page</a></td>
+</tr>
+</table>
+</div>
+<!-- END NAVIGATION -->
+
+
+<!-- START BREADCRUMB -->
+<table cellpadding="0" cellspacing="0" border="0" style="width:100%">
+<tr>
+<td id="breadcrumb">
+<a href="http://www.codeigniter.com/">CodeIgniter Home</a> &nbsp;&#8250;&nbsp;
+<a href="../index.html">User Guide Home</a> &nbsp;&#8250;&nbsp;
+Session Class
+</td>
+<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>
+</tr>
+</table>
+<!-- END BREADCRUMB -->
+
+<br clear="all" />
+
+
+<!-- START CONTENT -->
+<div id="content">
+
+
+<h1>Session Class</h1>
+
+<p>The Session class permits you maintain a user's "state" and track their activity while they browse your site.
+The Session class stores session information for each user as serialized (and optionally encrypted) data in a cookie.
+It can also store the session data in a database table for added security, as this permits the session ID in the
+user's cookie to be matched against the stored session ID. By default only the cookie is saved. If you choose to
+use the database option you'll need to create the session table as indicated below.
+</p>
+
+<p class="important"><strong>Note:</strong> The Session class does <strong>not</strong> utilize native PHP sessions. It
+generates its own session data, offering more flexibility for developers.</p>
+
+<h2>Initializing a Session</h2>
+
+<p>Sessions will typically run globally with each page load, so the session class must either be
+<a href="../general/libraries.html">initialized</a> in your
+<a href="../general/controllers.html">controller</a> constructors, or it can be
+<a href="../general/autoloader.html">auto-loaded</a> by the system.
+For the most part the session class will run unattended in the background, so simply initializing the class
+will cause it to read, create, and update sessions.</p>
+
+
+<p>To initialize the Session class manually in your controller constructor, use the <dfn>$this->load->library</dfn> function:</p>
+
+<code>$this->load->library('session');</code>
+<p>Once loaded, the Sessions library object will be available using: <dfn>$this->session</dfn></p>
+
+
+<h2>How do Sessions work?</h2>
+
+<p>When a page is loaded, the session class will check to see if valid session data exists in the user's session cookie.
+If sessions data does <strong>not</strong> exist (or if it has expired) a new session will be created and saved in the cookie.
+If a session does exist, its information will be updated and the cookie will be updated. With each update, the session_id will be regenerated.</p>
+
+<p>It's important for you to understand that once initialized, the Session class runs automatically. There is nothing
+you need to do to cause the above behavior to happen. You can, as you'll see below, work with session data or
+even add your own data to a user's session, but the process of reading, writing, and updating a session is automatic.</p>
+
+
+<h2>What is Session Data?</h2>
+
+<p>A <em>session</em>, as far as CodeIgniter is concerned, is simply an array containing the following information:</p>
+
+<ul>
+<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>
+<li>The user's IP Address</li>
+<li>The user's User Agent data (the first 50 characters of the browser data string)</li>
+<li>The "last activity" and "last visit" time stamps.</li>
+</ul>
+
+<p>The above data is stored in a cookie as a serialized array with this prototype:</p>
+
+<code>[array]<br />
+(<br />
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;'session_id'&nbsp;&nbsp;&nbsp;&nbsp;=> random hash,<br />
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;'ip_address'&nbsp;&nbsp;&nbsp;&nbsp;=> 'string - user IP address',<br />
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;'user_agent'&nbsp;&nbsp;&nbsp;&nbsp;=> 'string - user agent data',<br />
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;'last_activity' => timestamp,<br />
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;'last_visit'&nbsp;&nbsp;&nbsp;&nbsp;=> timestamp<br />
+)</code>
+
+<p>If you have the encryption option enabled, the serialized array will be encrypted before being stored in the cookie,
+making the data highly secure and impervious to being read or altered by someone. More info regarding encryption
+can be <a href="encryption.html">found here</a>, although the Session class will take care of initializing
+and encrypting the data automatically.</p>
+
+<p>Note: Session cookies are only updated every five minutes by default to reduce processor load. If you repeatedly reload a page
+you'll notice that the "last activity" time only updates if five minutes or more has passed since the last time
+the cookie was written. This time is configurable my changing the $config['time_to_update'] line in your system/config/config.php file.</p>
+
+<h2>Retrieving Session Data</h2>
+
+<p>Any piece of information from the session array is available using the following function:</p>
+
+<code>$this->session->userdata('<samp>item</samp>');</code>
+
+<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
+will do this:</p>
+
+<code>$session_id = $this->session->userdata('<samp>session_id</samp>');</code>
+
+<p><strong>Note:</strong> The function returns FALSE (boolean) if the item you are trying to access does not exist.</p>
+
+
+<h2>Adding Custom Session Data</h2>
+
+<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.
+Why would you want to do this? Here's one example:</p>
+
+<p>Let's say a particular user logs into your site. Once authenticated,
+you could add their username and email address to the session cookie, making that data globally available to you without
+having to run a database query when you need it.</p>
+
+<p>To add your data to the session array involves passing an array containing your new data to this function:</p>
+
+<code>$this->session->set_userdata(<samp>$array</samp>);</code>
+
+<p>Where <samp>$array</samp> is an associative array containing your new data. Here's an example:</p>
+
+
+<p><code>$newdata = array(<br />
+ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;'username'&nbsp; => 'johndoe',<br />
+ &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 />
+ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;'logged_in' => TRUE<br />
+ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;);<br />
+ <br />
+ $this->session->set_userdata(<samp>$newdata</samp>);</code></p>
+<p>If you want to add userdata one value at a time, set_userdata() also supports this syntax. </p>
+<p><code>$this-&gt;session-&gt;set_userdata('some_name', 'some_value');</code></p>
+<p class="important"><strong>Note:</strong> Cookies can only hold 4KB of data, so be careful not to exceed the capacity. The
+encryption process in particular produces a longer data string than the original so keep careful track of how much data you are storing.</p>
+
+<h2>Removing Session Data</h2>
+<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>
+<p><code>$this-&gt;session-&gt;unset_userdata('some_name');</code></p>
+<p>This function can also be passed an array of items to unset.</p>
+<p><code>$array_items = array('username', 'email');<br />
+<br />
+$this-&gt;session-&gt;set_userdata(<samp>$array_items</samp>);</code></p>
+<h2>Flashdata</h2>
+<p>CodeIgniter supports &quot;flashdata&quot;, or session data that will only ba 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>
+<p>Note: Flash variables are prefaced with &quot;flash_&quot; so avoid this prefix in your own session names.</p>
+<p>To add flashdata:</p>
+<p><code>$this-&gt;session-&gt;set_flashdata('item', 'value');</code></p>
+<p>You can also pass an array to set_flashdata(), in the same manner as set_userdata(). </p>
+<p>To read a flashdata variable:</p>
+<p><code>$this-&gt;session-&gt;flashdata('item');</code></p>
+<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>
+<p><code>$this-&gt;session-&gt;keep_flashdata('item');</code></p>
+<h2>Saving Session Data to a Database</h2>
+<p>While the session data array stored in the user's cookie contains a Session ID,
+unless you store session data in a database there is no way to validate it. For some applications that require little or no
+security, session ID validation may not be needed, but if your application requires security, validation is mandatory.</p>
+
+<p>When session data is available in a database, every time a valid session is found in the user's cookie, a database
+query is performed to match it. If the session ID does not match, the session is destroyed. Session IDs can never
+be updated, they can only be generated when a new session is created.</p>
+
+<p>In order to store sessions, you must first create a database table for this purpose. Here is the basic
+prototype (for MySQL) required by the session class:</p>
+
+<textarea class="textarea" style="width:100%" cols="50" rows="8">
+CREATE TABLE IF NOT EXISTS `ci_sessions` (
+session_id varchar(40) DEFAULT '0' NOT NULL,
+ip_address varchar(16) DEFAULT '0' NOT NULL,
+user_agent varchar(50) NOT NULL,
+last_activity int(10) unsigned DEFAULT 0 NOT NULL,
+PRIMARY KEY (session_id)
+);</textarea>
+
+<p><strong>Note:</strong> By default the table is called <dfn>ci_sessions</dfn>, but you can name it anything you want
+as long as you update the <kbd>application/config/config.php</kbd> file so that it contains the name you have chosen.
+Once you have created your database table you can enable the database option in your config.php file as follows:</p>
+
+<code>$config['sess_use_database'] = TRUE;</code>
+
+<p>Once enabled, the Session class will store session data in the DB.</p>
+
+<p>Make sure you've specified the table name in your config file as well:</p>
+
+<code>$config['sess_table_name'] = 'ci_sessions";</code>
+
+<p class="important"><strong>Note:</strong> The Session class has built-in garbage collection which clears out expired sessions so you
+do not need to write your own routine to do it.</p>
+
+
+<h2>Destroying a Session </h2>
+<p>To clear the current session: </p>
+<code>$this-&gt;session-&gt;sess_destroy();</code>
+<h2>Session Preferences</h2>
+<p>You'll find the following Session related preferences in your <kbd>application/config/config.php</kbd> file:</p>
+
+
+<table cellpadding="0" cellspacing="1" border="0" style="width:100%" class="tableborder">
+<tr>
+<th>Preference</th>
+<th>Default</th>
+<th>Options</th>
+<th>Description</th>
+
+</tr><tr>
+<td class="td"><strong>sess_cookie_name</strong></td>
+<td class="td">ci_session</td
+><td class="td">None</td>
+<td class="td">The name you world the session cookie saved as.</td>
+
+</tr><tr>
+<td class="td"><strong>sess_expiration</strong></td>
+<td class="td">7200</td>
+<td class="td">None</td>
+<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>
+
+
+</tr><tr>
+<td class="td"><strong>sess_encrypt_cookie</strong></td>
+<td class="td">FALSE</td>
+<td class="td">TRUE/FALSE (boolean)</td>
+<td class="td">Whether to encrypt the session data.</td>
+
+</tr><tr>
+<td class="td"><strong>sess_use_database</strong></td>
+<td class="td">FALSE</td>
+<td class="td">TRUE/FALSE (boolean)</td>
+<td class="td">Whether to save the session data to a database. You must create the table before enabling this option.</td>
+
+</tr><tr>
+<td class="td"><strong>sess_table_name</strong></td>
+<td class="td">ci_sessions</td
+><td class="td">Any valid SQL table name</td>
+<td class="td">The name of the session database table.</td>
+
+</tr><tr>
+<td class="td"><strong>sess_match_ip</strong></td>
+<td class="td">FALSE</td>
+<td class="td">TRUE/FALSE (boolean)</td>
+<td class="td">Whether to match the user's IP address when reading the session data. Note that some ISPs dynamically
+changes the IP, so if you want a non-expiring session you will likely set this to FALSE.</td>
+
+</tr><tr>
+<td class="td"><strong>sess_match_useragent</strong></td>
+<td class="td">TRUE</td>
+<td class="td">TRUE/FALSE (boolean)</td>
+<td class="td">Whether to match the User Agent when reading the session data.</td>
+
+
+</tr>
+</table>
+
+
+</div>
+<!-- END CONTENT -->
+
+
+<div id="footer">
+<p>
+Previous Topic:&nbsp;&nbsp;<a href="pagination.html">Pagination Class</a>
+&nbsp;&nbsp;&nbsp;&middot;&nbsp;&nbsp;
+<a href="#top">Top of Page</a>&nbsp;&nbsp;&nbsp;&middot;&nbsp;&nbsp;
+<a href="../index.html">User Guide Home</a>&nbsp;&nbsp;&nbsp;&middot;&nbsp;&nbsp;
+Next Topic:&nbsp;&nbsp;<a href="trackback.html">Trackback Class</a>
+</p>
+<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>
+</div>
+
+</body>
</html> \ No newline at end of file