summaryrefslogtreecommitdiffstats
path: root/user_guide_src/source/libraries/sessions.rst
diff options
context:
space:
mode:
authorBrennan Thompson <brenjt@gmail.com>2014-02-14 20:03:57 +0100
committerBrennan Thompson <brenjt@gmail.com>2014-02-14 20:03:57 +0100
commit6949f95f6e21980f36095490bf38fc8a172dbc0f (patch)
treeb3141f390acd0051396cda6a3da51c1f98384cca /user_guide_src/source/libraries/sessions.rst
parent68a02a01a086bbb1b8128ea2744439de84873d11 (diff)
parent81f036753272391360ba5b64e6dd93c4101a8733 (diff)
Merge remote-tracking branch 'upstream/develop' into develop
Conflicts: system/helpers/form_helper.php
Diffstat (limited to 'user_guide_src/source/libraries/sessions.rst')
-rw-r--r--user_guide_src/source/libraries/sessions.rst311
1 files changed, 264 insertions, 47 deletions
diff --git a/user_guide_src/source/libraries/sessions.rst b/user_guide_src/source/libraries/sessions.rst
index 36c7c1d32..f05f86af1 100644
--- a/user_guide_src/source/libraries/sessions.rst
+++ b/user_guide_src/source/libraries/sessions.rst
@@ -9,6 +9,17 @@ which supports usage of the native PHP Session mechanism. In addition,
you may create your own `Custom Drivers`_ to store session data however
you wish, while still taking advantage of the features of the Session class.
+.. contents::
+ :local:
+
+.. raw:: html
+
+ <div class="custom-index container"></div>
+
+***********************
+Using the Session Class
+***********************
+
Initializing a Session
======================
@@ -21,12 +32,13 @@ 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:
-$this->session
+Once loaded, the Sessions library object will be available using::
+
+ $this->session
How do Sessions work?
=====================
@@ -62,10 +74,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
@@ -91,6 +103,23 @@ fetch. For example, to fetch the session ID you will do this::
.. note:: The function returns NULL if the item you are
trying to access does not exist.
+If you want to retrieve all of the existing userdata, you can simply
+omit the item key parameter::
+
+ $this->session->userdata();
+
+ /**
+ * Produces something similar to:
+ *
+ * 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
+ * )
+ */
+
Adding Custom Session Data
==========================
@@ -112,43 +141,26 @@ 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()``.
::
$this->session->has_userdata('some_name');
-Retrieving All Session Data
-===========================
-
-An array of all userdata can be retrieved as follows::
-
- $this->session->all_userdata()
-
-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
- )
-
Removing Session Data
=====================
@@ -185,8 +197,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::
@@ -194,11 +206,11 @@ To read a flashdata variable::
An array of all flashdata can be retrieved as follows::
- $this->session->all_flashdata();
+ $this->session->flashdata();
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 +218,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 +233,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!');
@@ -232,8 +246,12 @@ To read a tempdata variable::
$this->session->tempdata('item');
+And of course, if you want to retrieve all existing tempdata::
+
+ $this->session->tempdata();
+
If you need to remove a tempdata value before it expires,
-use unset_tempdata()::
+use ``unset_tempdata()``::
$this->session->unset_tempdata('item');
@@ -246,13 +264,13 @@ 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
===================
You'll find the following Session related preferences in your
-application/config/config.php file:
+*application/config/config.php* file:
=========================== =============== =========================== ==========================================================================
Preference Default Options Description
@@ -271,7 +289,8 @@ Preference Default Options Descript
table before enabling this option (Cookie driver only).
**sess_table_name** ci_sessions Any valid SQL table name The name of the session database table (Cookie driver only).
**sess_time_to_update** 300 Time in seconds This options controls how often the session class will regenerate itself
- and create a new session id.
+ and create a new session ID. Setting it to 0 will disable session
+ ID regeneartion.
**sess_match_ip** FALSE TRUE/FALSE (boolean) 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.
@@ -303,7 +322,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 +347,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');
@@ -390,11 +409,24 @@ session class::
KEY `last_activity_idx` (`last_activity`)
);
+Or if you're using PostgreSQL::
+
+ CREATE TABLE ci_sessions (
+ session_id varchar(40) DEFAULT '0' NOT NULL,
+ ip_address varchar(45) DEFAULT '0' NOT NULL,
+ user_agent varchar(120) NOT NULL,
+ last_activity bigint DEFAULT 0 NOT NULL,
+ user_data text NOT NULL,
+ PRIMARY KEY (session_id)
+ );
+
+ CREATE INDEX last_activity_idx ON ci_sessions(last_activity);
+
.. note:: By default the table is called ci_sessions, but you can name
it anything you want as long as you update the
- application/config/config.php 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::
+ *application/config/config.php* 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::
$config['sess_use_database'] = TRUE;
@@ -422,7 +454,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
@@ -430,6 +462,7 @@ deleted data (sess_destroy), a regenerate handler to make a new session ID
Your initial class might look like::
class CI_Session_custom extends CI_Session_driver {
+
protected function initialize()
{
// Read existing session data or create a new one
@@ -454,15 +487,16 @@ Your initial class might look like::
{
// Return a reference to your userdata array
}
+
}
-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 +517,186 @@ 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: Instance of currently loaded session driver
+ :rtype: mixed
+
+ Loads a session storage driver
+
+ .. method:: select_driver($driver)
+
+ :param string $driver: Driver name
+ :rtype: void
+
+ Selects default session storage driver.
+
+ .. method:: sess_destroy()
+
+ :rtype: void
+
+ Destroys current session
+
+ .. note:: This method should be the last one called, and even flash
+ variables will no longer be available after it is used.
+ If you only want some items destroyed and not all, use
+ ``unset_userdata()``.
+
+ .. method:: sess_regenerate([$destroy = FALSE])
+
+ :param bool $destroy: Whether to destroy session data
+ :rtype: void
+
+ Regenerate the current session data.
+
+ .. method:: userdata([$item = NULL])
+
+ :param string $item: Session item name
+ :returns: Item value if found, NULL if not or an array of all userdata if $item parameter is not used
+ :rtype: mixed
+
+ If no parameter is passed, it will return an associative array of all existing userdata.
+
+ Otherwise 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: An array of all userdata
+ :rtype: array
+
+ Returns an array with all of the session userdata items.
+
+ .. note:: This method is DEPRECATED. Use ``userdata()`` with no parameters instead.
+
+ .. method:: &get_userdata()
+
+ :returns: A reference to the userdata array
+ :rtype: &array
+
+ Returns a reference to the userdata array.
+
+ .. method:: set_userdata($newdata[, $newval = ''])
+
+ :param mixed $newdata: Item name or array of items
+ :param mixed $newval: Item value or empty string (not required if $newdata is array)
+ :rtype: 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: Item name or an array containing multiple items
+ :rtype: void
+
+ Unsets previously set 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: Item name
+ :returns: TRUE if item exists, FALSE if not
+ :rtype: bool
+
+ Checks if an item exists in the session.
+
+ .. method:: flashdata([$item = NULL])
+
+ :param string $item: Flashdata item name
+ :returns: Item value if found, NULL if not or an array of all flashdata if $item parameter is not used
+ :rtype: mixed
+
+ If no parameter is passed, it will return an associative array of all existing flashdata.
+
+ Otherwise 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_flashdata($newdata[, $newval = ''])
+
+ :param mixed $newdata: Item name or an array of items
+ :param mixed $newval: Item value or empty string (not required if $newdata is array)
+ :rtype: 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: Item name or an array containing multiple flashdata items
+ :rtype: void
+
+ Keeps items into flashdata for one more request.
+
+ .. method:: tempdata([$item = NULL])
+
+ :param string $item: Tempdata item name
+ :returns: Item value if found, NULL if not or an array of all tempdata if $item parameter is not used
+ :rtype: mixed
+
+ If no parameter is passed, it will return an associative array of all existing tempdata.
+
+ Otherwise 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.
+
+ .. method:: set_tempdata($newdata[, $newval = ''[, $expire = 0]])
+
+ :param mixed $newdata: Item name or array containing multiple items
+ :param string $newval: Item value or empty string (not required if $newdata is array)
+ :param int $expire: Lifetime in seconds (0 for default)
+ :rtype: 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: Item name or an array containing multiple items
+ :rtype: void
+
+ Unsets previously set items from 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. \ No newline at end of file