diff options
Diffstat (limited to 'user_guide_src/source/libraries/sessions.rst')
| -rw-r--r-- | user_guide_src/source/libraries/sessions.rst | 304 |
1 files changed, 260 insertions, 44 deletions
diff --git a/user_guide_src/source/libraries/sessions.rst b/user_guide_src/source/libraries/sessions.rst index 3368a9f5d..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->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:: @@ -198,7 +210,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 +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,7 +264,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 =================== @@ -304,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'); @@ -329,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'); @@ -391,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; @@ -423,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 @@ -431,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 @@ -455,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:: @@ -484,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 |