Merge branch 'develop' into 'feature/encryption'

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