summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorMichael <michael@webstart.bg>2013-09-30 11:22:29 +0200
committerMichael <michael@webstart.bg>2013-09-30 11:24:31 +0200
commit5d4131b2d8a156e0793a185987292c35a898e332 (patch)
tree5a0921b2e33abe27843bdf357309ed969153525a
parent0ee2a6333a8b987fd85c6bd6018fdd95906277ac (diff)
Update the Session library docs
Signed-off-by: Michael <michael@webstart.bg>
-rw-r--r--user_guide_src/source/libraries/sessions.rst65
1 files changed, 34 insertions, 31 deletions
diff --git a/user_guide_src/source/libraries/sessions.rst b/user_guide_src/source/libraries/sessions.rst
index 36c7c1d32..51bcc8022 100644
--- a/user_guide_src/source/libraries/sessions.rst
+++ b/user_guide_src/source/libraries/sessions.rst
@@ -21,11 +21,12 @@ initializing the class will cause it to read, create, and update
sessions.
To initialize the Session class manually in your controller constructor,
-use the $this->load->driver function::
+use the ``$this->load->driver`` function::
$this->load->driver('session');
-Once loaded, the Sessions library object will be available using:
+Once loaded, the Sessions library object will be available using::
+
$this->session
How do Sessions work?
@@ -49,23 +50,23 @@ What is Session Data?
A *session*, as far as CodeIgniter is concerned, is simply an array
containing the following information:
-- The user's unique Session ID (this is a statistically random string
+* 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)
-- The user's IP Address
-- The user's User Agent data (the first 120 characters of the browser
+* The user's IP Address
+* The user's User Agent data (the first 120 characters of the browser
data string)
-- The "last activity" time stamp.
+* The "last activity" time stamp.
The above data is stored in a cookie as a serialized array with this
prototype::
[array]
(
- 'session_id' => random hash,
- 'ip_address' => 'string - user IP address',
- 'user_agent' => 'string - user agent data',
- 'last_activity' => timestamp
+ 'session_id' => random hash,
+ 'ip_address' => 'string - user IP address',
+ 'user_agent' => 'string - user agent data',
+ 'last_activity' => timestamp
)
.. note:: Sessions are only updated every five minutes by default to
@@ -112,21 +113,21 @@ Where $array is an associative array containing your new data. Here's an
example::
$newdata = array(
- 'username' => 'johndoe',
- 'email' => 'johndoe@some-site.com',
- 'logged_in' => TRUE
- );
+ 'username' => 'johndoe',
+ 'email' => 'johndoe@some-site.com',
+ 'logged_in' => TRUE
+ );
$this->session->set_userdata($newdata);
-If you want to add userdata one value at a time, set_userdata() also
+If you want to add userdata one value at a time, ``set_userdata()`` also
supports this syntax.
::
$this->session->set_userdata('some_name', 'some_value');
-If you want to verify that a userdata value exists, call has_userdata().
+If you want to verify that a userdata value exists, call ``has_userdata()``.
::
@@ -143,10 +144,10 @@ And returns an associative array like the following::
Array
(
- [session_id] => 4a5a5dca22728fb0a84364eeb405b601
- [ip_address] => 127.0.0.1
- [user_agent] => Mozilla/5.0 (Macintosh; U; Intel Mac OS X 10_6_7;
- [last_activity] => 1303142623
+ [session_id] => 4a5a5dca22728fb0a84364eeb405b601
+ [ip_address] => 127.0.0.1
+ [user_agent] => Mozilla/5.0 (Macintosh; U; Intel Mac OS X 10_6_7;
+ [last_activity] => 1303142623
)
Removing Session Data
@@ -185,8 +186,8 @@ To add flashdata::
$this->session->set_flashdata('item', 'value');
-You can also pass an array to set_flashdata(), in the same manner as
-set_userdata().
+You can also pass an array to ``set_flashdata()``, in the same manner as
+``set_userdata()``.
To read a flashdata variable::
@@ -198,7 +199,7 @@ An array of all flashdata can be retrieved as follows::
If you find that you need to preserve a flashdata variable through an
-additional request, you can do so using the keep_flashdata() function.
+additional request, you can do so using the ``keep_flashdata()`` function.
You can either pass a single item or an array of flashdata items to keep.
::
@@ -206,6 +207,8 @@ You can either pass a single item or an array of flashdata items to keep.
$this->session->keep_flashdata('item');
$this->session->keep_flashdata(array('item1', 'item2', 'item3'));
+.. note:: The function will return NULL if the item cannot be found.
+
Tempdata
========
@@ -219,7 +222,7 @@ To add tempdata::
$this->session->set_tempdata('item', 'value', $expire);
-You can also pass an array to set_tempdata()::
+You can also pass an array to ``set_tempdata()``::
$tempdata = array('newuser' => TRUE, 'message' => 'Thanks for joining!');
@@ -233,7 +236,7 @@ To read a tempdata variable::
$this->session->tempdata('item');
If you need to remove a tempdata value before it expires,
-use unset_tempdata()::
+use ``unset_tempdata()``::
$this->session->unset_tempdata('item');
@@ -246,7 +249,7 @@ To clear the current session::
.. note:: 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 unset_userdata().
+ destroyed and not all, use ``unset_userdata()``.
Session Preferences
===================
@@ -303,7 +306,7 @@ installed, and `Custom Drivers`_ may also be installed by the user.
Typically, only one driver will be used at a time, but CodeIgniter does
support loading multiple drivers. If a specific valid driver is called, it
will be automatically loaded. Or, an additional driver may be explicitly
-loaded by calling load_driver()::
+loaded by ``calling load_driver()``::
$this->session->load_driver('native');
@@ -328,7 +331,7 @@ the call to unset the *native* 'foo' value. The drivers maintain independent
sets of values, regardless of key names.
A specific driver may also be explicitly selected for use by pursuant
-methods with the select_driver() call::
+methods with the ``select_driver()`` call::
$this->session->select_driver('native');
@@ -422,7 +425,7 @@ You may also :doc:`create your own <../general/creating_drivers>` custom
session drivers. A session driver basically manages an array of name/value
pairs with some sort of storage mechanism.
-To make a new driver, extend CI_Session_driver. Overload the initialize()
+To make a new driver, extend CI_Session_driver. Overload the ``initialize()``
method and read or create session data. Then implement a save handler to
write changed data to storage (sess_save), a destroy handler to remove
deleted data (sess_destroy), a regenerate handler to make a new session ID
@@ -456,13 +459,13 @@ Your initial class might look like::
}
}
-Notice that get_userdata() returns a reference so the parent library is
+Notice that ``get_userdata()`` returns a reference so the parent library is
accessing the same array the driver object is using. This saves memory
and avoids synchronization issues during usage.
Put your driver in the libraries/Session/drivers folder anywhere in your
package paths. This includes the application directory, the system directory,
-or any path you add with $CI->load->add_package_path(). Your driver must be
+or any path you add with ``$CI->load->add_package_path()``. Your driver must be
named CI_Session_<name>, and your filename must be Session_<name>.php,
preferably also capitalized, such as::