diff options
| author | Derek Allard <derek.allard@ellislab.com> | 2008-08-21 14:46:58 +0200 |
|---|---|---|
| committer | Derek Allard <derek.allard@ellislab.com> | 2008-08-21 14:46:58 +0200 |
| commit | 928c55cbc5f3f162c10077f46d75d0bc0b1cbe53 (patch) | |
| tree | 22b9ca71872be54736e400de93cb7223cbe5ca1d /user_guide/libraries/sessions.html | |
| parent | 993925b47a0bfb08e79961c47bcc3d247a03a5dd (diff) | |
further whitespace fixes
Diffstat (limited to 'user_guide/libraries/sessions.html')
| -rw-r--r-- | user_guide/libraries/sessions.html | 155 |
1 files changed, 62 insertions, 93 deletions
diff --git a/user_guide/libraries/sessions.html b/user_guide/libraries/sessions.html index c8e64f824..7158ca764 100644 --- a/user_guide/libraries/sessions.html +++ b/user_guide/libraries/sessions.html @@ -60,35 +60,35 @@ Session Class <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 additionally store the session data in a database table for added security, as this permits the session ID in the
+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.
+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 so you are not dependent on how a particular hosting environment is set up.</p>
+generates its own session data, offering more flexibility for developers.</p>
<h2>Initializing a Session</h2>
-<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
+<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.
-Once initialized, the Session class will run unattended in the background, reading, writing, and updating the session as needed.</p>
+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>You can access the Session library object using: <dfn>$this->session</dfn></p>
+<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.
+<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 <strong>does</strong> exist, its information and cookie will be updated automatically. With each update, the session_id will be regenerated for security.</p>
+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
@@ -141,7 +141,7 @@ will do this:</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 session array.
+<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,
@@ -156,20 +156,16 @@ having to run a database query when you need it.</p> <p><code>$newdata = array(<br />
- 'username' => 'johndoe',<br />
- 'email' => 'johndoe@some-site.com',<br />
- 'logged_in' => TRUE<br />
- );<br />
- <br />
- $this->session->set_userdata(<samp>$newdata</samp>);</code></p>
-
+ 'username' => 'johndoe',<br />
+ 'email' => 'johndoe@some-site.com',<br />
+ 'logged_in' => TRUE<br />
+ );<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->session->set_userdata('some_name', 'some_value');</code></p>
-
-
-<p class="important"><strong>Note:</strong> By default, the session class stores your custom data in the session cookie. Cookies, however, can only hold
-4KB 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.
-If 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>
+<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>
@@ -194,12 +190,8 @@ unless you store session data in a database there is no way to validate it. For 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.</p>
-
-<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
-custom 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
-the user's cookie.</p>
-
+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>
@@ -210,15 +202,12 @@ 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,
-user_data text NOT NULL,
PRIMARY KEY (session_id)
);</textarea>
-<p><strong>Note:</strong> By default the table is named <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. The Session class, however,
-expects the column names to be identical to the ones indicated above.</p>
-
-<p>Once you have created your database table you can enable the database option in your config.php file as follows:</p>
+<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>
@@ -228,7 +217,7 @@ expects the column names to be identical to the ones indicated above.</p> <code>$config['sess_table_name'] = 'ci_sessions";</code>
-<p class="important"><strong>Note:</strong> The Session class has a built-in garbage collection routine which clears out expired sessions periodically so you
+<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>
@@ -240,84 +229,64 @@ do not need to write your own routine to do it.</p> <h2>Session Preferences</h2>
-<p>Normally you will set the Session preferences in your <kbd>application/config/config.php</kbd> file.</p>
-
-<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
-wish to set in the second parameter as follows:</p>
-
-<code>
-$session_vals = array(<br />
- 'sess_expiration' = 10800,<br />
- 'sess_match_ip' = TRUE<br />
- );<br />
-<br />
-$this->load->library('session', $session_vals);
-</code>
-
-<p>The following table lists the available preferences:</p>
+<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 want the session cookie saved as.</td>
+ <th>Preference</th>
+ <th>Default</th>
+ <th>Options</th>
+ <th>Description</th>
</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>
+ <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 want the session cookie saved as.</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>
+ <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_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>
+ <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_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>
+ <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_time_to_update</strong></td>
- <td class="td">300</td>
- <td class="td">Time in seconds</td>
- <td class="td">This options controls how often the session class will regenerate itself and create a new session id.</td>
+ <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>
+ <td class="td"><strong>sess_time_to_update</strong></td>
+ <td class="td">300</td>
+ <td class="td">Time in seconds</td>
+ <td class="td">This options controls how often the session class will regenerate itself and create a new session id.</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>
+ <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_cookie_name</strong></td>
- <td class="td">ci_session</td>
- <td class="td">None</td>
- <td class="td">The name of the session cookie</td>
+ <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>
|