summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorAndrey Andreev <narf@devilix.net>2013-10-20 14:06:04 +0200
committerAndrey Andreev <narf@devilix.net>2013-10-20 14:06:04 +0200
commitb7b84ec703a56219c828211c68d5759dd708ab8f (patch)
treed0285cd7921214bdf578605c8f6ef4bdb1b1194f
parent0ee2a6333a8b987fd85c6bd6018fdd95906277ac (diff)
parente0a631c3353ea26483e3958306fb2b53d7558a21 (diff)
Merge pull request #2666 from xxaxxo/feature/user-guide-cleanup
Update the Session library docs
-rw-r--r--user_guide_src/source/libraries/sessions.rst219
1 files changed, 192 insertions, 27 deletions
diff --git a/user_guide_src/source/libraries/sessions.rst b/user_guide_src/source/libraries/sessions.rst
index 36c7c1d32..cab7669ae 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?
@@ -62,10 +63,10 @@ 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::
@@ -483,3 +486,165 @@ without making it the initially loaded driver, set 'sess_valid_drivers' in
your config.php file to an array including your driver name::
$config['sess_valid_drivers'] = array('sess_driver');
+
+
+
+***************
+Class Reference
+***************
+
+.. class:: CI_Session
+
+ .. method:: load_driver($driver)
+
+ :param string $driver: Driver name
+ :returns: object Loaded driver object
+
+ Loads a session storage driver
+
+ .. method:: select_driver($driver)
+
+ :param string $driver: Driver name
+ :returns: void
+
+ Selects default session storage driver.
+
+ .. method:: sess_destroy()
+
+ Destroys 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()``.
+
+ .. method:: sess_regenerate($destroy)
+
+ :param bool $destroy: Destroy session data flag (default: false)
+ :returns: void
+
+ Regenerate the current session data
+
+ .. method:: userdata($item)
+
+ :param string $item: name of session item
+ :returns: string
+
+ Returns a string containing the value of the passed item or NULL if the item is not found. Example::
+
+ $this->session->userdata('user');
+ //returns example@example.com considering the set_userdata example.
+
+ .. method:: all_userdata()
+
+ :returns: array
+
+ Retruns array of userdata session items
+
+ .. method:: all_flashdata()
+
+ :returns: array
+
+ Retruns array of flashdata session items
+
+ .. method:: set_userdata($newdata = array(), $newval)
+
+ :param mixed $newdata: Item name or array of items
+ :param mixed $newval: Item value or empty string (not required if $newdata is array)
+ :returns: void
+
+ Sets items into session example usages::
+
+ $this->session->set_userdata('user', 'example@example.com');
+ // adds item user with value example@example.com to the session
+
+ $this->session->set_userdata(array('user'=>'example@example.com'));
+ // does the same as the above example - adds item user with value example@example.com to the session
+
+ .. method:: unset_userdata($item)
+
+ :param mixed $item: name of item or array of items
+ :returns: void
+
+ Unsets previously setted items from the session. Example::
+
+ $this->session->unset_userdata('user');
+ //unsets 'user' from session data.
+
+ $this->session->unset_userdata(array('user', 'useremail'));
+ //unsets both 'user' and 'useremail' from the session data.
+
+ .. method:: has_userdata($item)
+
+ :param string $item: name of item
+ :returns: bool
+
+ Checks if an item exists in the session.
+
+ .. method:: set_flashdata($newdata = array(), $newval)
+
+ :param mixed $newdata: Item name or array of items
+ :param mixed $newval: Item value or empty string (not required if $newdata is array)
+ :returns: void
+
+ Sets items into session flashdata example usages::
+
+ $this->session->set_flashdata('message', 'Test message.');
+ // adds item 'message' with value 'Test message.' to the session flashdata
+
+ $this->session->set_flashdata(array('message'=>'Test message.'));
+ // does the same as the above example - adds item 'message' with value 'Test message.'
+ to the session flashdata
+
+ .. method:: keep_flashdata($item)
+
+ :param mixed $item: name of item or array of flashdata items
+ :returns: void
+
+ Keeps items into flashdata for one more request
+
+ .. method:: flashdata($item)
+
+ :param string $item: name of session item
+ :returns: string
+
+ Returns a string containing the value of the passed item or NULL if the item is not found. Example::
+
+ $this->session->flashdata('message');
+ //returns 'Test message.' considering the set_flashdata example.
+
+ .. method:: set_tempdata($newdata = array(), $newval, $expires)
+
+ :param mixed $newdata: Item name or array of items
+ :param string $newval: Item value or empty string (not required if $newdata is array)
+ :param int $expires: lifetime in seconds (0 for default)
+ :returns: void
+
+ Sets items into session tempdata example::
+
+ $this->session->set_tempdata('message', 'Test message.', '60');
+ // adds item 'message' with value 'Test message.' to the session tempdata for 60 seconds
+
+ $this->session->set_tempdata(array('message'=>'Test message.'));
+ // does the same as the above example - adds item 'message' with value 'Test message.'
+ to the session tempdata for the default value of
+
+ .. method:: unset_tempdata($item)
+
+ :param mixed $item: name of item or array of items
+ :returns: void
+
+ Unsets previously setted items from the tempdata. Example::
+
+ $this->session->unset_tempdata('user');
+ //unsets 'user' from tempdata.
+
+ $this->session->unset_tempdata(array('user', 'useremail'));
+ //unsets both 'user' and 'useremail' from the tempdata.
+
+ .. method:: tempdata($item)
+
+ :param string $item: name of tempdata item
+ :returns: string
+
+ Returns a string containing the value of the passed item or NULL if the item is not found. Example::
+
+ $this->session->tempdata('message');
+ //returns 'Test message.' considering the set_tempdata example.