diff options
| -rw-r--r-- | user_guide_src/source/libraries/sessions.rst | 65 |
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:: |