Updated Loader and Session documentation

1 files changed, 258 insertions, 80 deletions

diff --git a/user_guide_src/source/libraries/sessions.rst b/user_guide_src/source/libraries/sessions.rst
index 5400524a9..7a27a8f34 100644
--- a/user_guide_src/source/libraries/sessions.rst
+++ b/user_guide_src/source/libraries/sessions.rst
@@ -1,29 +1,19 @@
-#############
-Session Class
-#############
+##############
+Session Driver
+##############
 
 The Session class permits you maintain a user's "state" and track their
-activity while they browse your site. The Session class stores session
-information for each user as serialized (and optionally encrypted) data
-in a cookie. It can also store the session data in a database table for
-added security, as this permits the session ID in the user's cookie to
-be matched against the stored session ID. By default only the cookie is
-saved. If you choose to use the database option you'll need to create
-the session table as indicated below.
-
-.. note:: The Session class does **not** utilize native PHP sessions. It
-	generates its own session data, offering more flexibility for
-	developers.
-
-.. note:: Even if you are not using encrypted sessions, you must set
-	an :doc:`encryption key <./encryption>` in your config file which is used
-	to aid in preventing session data manipulation.
+activity while they browse your site. CodeIgniter offers two default
+session drivers: the classic `Cookie Driver`_, and the `Native Driver`_,
+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.
 
 Initializing a Session
 ======================
 
 Sessions will typically run globally with each page load, so the session
-class must either be :doc:`initialized <../general/libraries>` in your
+class must either be :doc:`initialized <../general/drivers>` in your
 :doc:`controller <../general/controllers>` constructors, or it can be
 :doc:`auto-loaded <../general/autoloader>` by the system. For the most
 part the session class will run unattended in the background, so simply
@@ -31,22 +21,25 @@ 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->library function::
+use the $this->load->driver function::
 
-	$this->load->library('session');
+	$this->load->driver('session');
 
 Once loaded, the Sessions library object will be available using:
 $this->session
 
+.. note:: For backward compatibility, the Session class may stil be loaded
+	using the $this->load->library function, but converting your applications
+	to use $this->load->driver is strongly recommended.
+
 How do Sessions work?
 =====================
 
 When a page is loaded, the session class will check to see if valid
-session data exists in the user's session cookie. If sessions data does
-**not** exist (or if it has expired) a new session will be created and
-saved in the cookie. If a session does exist, its information will be
-updated and the cookie will be updated. With each update, the
-session_id will be regenerated.
+session data exists in the user's session. If sessions data does **not**
+exist (or if it has expired) a new session will be created and saved.
+If a session does exist, its information will be updated. With each update,
+the session_id will be regenerated.
 
 It's important for you to understand that once initialized, the Session
 class runs automatically. There is nothing you need to do to cause the
@@ -79,19 +72,12 @@ prototype::
 	     'last_activity' => timestamp
 	)
 
-If you have the encryption option enabled, the serialized array will be
-encrypted before being stored in the cookie, making the data highly
-secure and impervious to being read or altered by someone. More info
-regarding encryption can be :doc:`found here <encryption>`, although
-the Session class will take care of initializing and encrypting the data
-automatically.
-
-Note: Session cookies are only updated every five minutes by default to
-reduce processor load. If you repeatedly reload a page you'll notice
-that the "last activity" time only updates if five minutes or more has
-passed since the last time the cookie was written. This time is
-configurable by changing the $config['sess_time_to_update'] line in
-your system/config/config.php file.
+.. note:: Sessions are only updated every five minutes by default to
+	reduce processor load. If you repeatedly reload a page you'll notice
+	that the "last activity" time only updates if five minutes or more has
+	passed since the last time the cookie was written. This time is
+	configurable by changing the $config['sess_time_to_update'] line in
+	your system/config/config.php file.
 
 Retrieving Session Data
 =======================
@@ -106,7 +92,7 @@ fetch. For example, to fetch the session ID you will do this::
 
 	$session_id = $this->session->userdata('session_id');
 
-.. note:: The function returns FALSE (boolean) if the item you are
+.. note:: The function returns NULL if the item you are
 	trying to access does not exist.
 
 Adding Custom Session Data
@@ -117,7 +103,7 @@ to it and it will be stored in the user's cookie. Why would you want to
 do this? Here's one example:
 
 Let's say a particular user logs into your site. Once authenticated, you
-could add their username and email address to the session cookie, making
+could add their username and email address to the session, making
 that data globally available to you without having to run a database
 query when you need it.
 
@@ -144,11 +130,11 @@ supports this syntax.
 
 	$this->session->set_userdata('some_name', 'some_value');
 
+If you want to verify that a userdata value exists, call has_userdata().
 
-.. note:: Cookies can only hold 4KB of data, so be careful not to exceed
-	the capacity. The encryption process in particular produces a longer
-	data string than the original so keep careful track of how much data you
-	are storing.
+::
+
+	$this->session->has_userdata('some_name');
 
 Retrieving All Session Data
 ===========================
@@ -195,8 +181,8 @@ available for the next server request, and are then automatically
 cleared. These can be very useful, and are typically used for
 informational or status messages (for example: "record 2 deleted").
 
-Note: Flash variables are prefaced with "flash\_" so avoid this prefix
-in your own session names.
+.. note:: Flash variables are prefaced with "flash\_" so avoid this prefix
+	in your own session names.
 
 To add flashdata::
 
@@ -222,9 +208,162 @@ additional request, you can do so using the keep_flashdata() function.
 
 	$this->session->keep_flashdata('item');
 
+Tempdata
+========
+
+CodeIgniter also supports "tempdata", or session data with a specific
+expiration time. After the value expires, or the session expires or is
+deleted, the value is automatically removed.
+
+To add tempdata::
+
+	$expire = 300;	// Expire in 5 minutes
+
+	$this->session->set_tempdata('item', 'value', $expire);
+
+You can also pass an array to set_tempdata()::
+
+	$tempdata = array('newuser' => TRUE, 'message' => 'Thanks for joining!');
+
+	$this->session->set_tempdata($tempdata, '', $expire);
+
+.. note:: If the expiration is omitted or set to 0, the default expiration of
+	5 minutes will be used.
+
+To read a tempdata variable::
+
+	$this->session->tempdata('item');
+
+If you need to remove a tempdata value before it expires,
+use unset_tempdata()::
+
+	$this->session->unset_tempdata('item');
+
+Destroying a Session
+====================
+
+To clear the current session::
+
+	$this->session->sess_destroy();
+
+.. 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().
+
+Session Preferences
+===================
+
+You'll find the following Session related preferences in your
+application/config/config.php file:
+
+=========================== =============== =========================== ==========================================================================
+Preference                  Default         Options                     Description
+=========================== =============== =========================== ==========================================================================
+**sess_driver**             cookie          cookie/native/*custom*      The initial session driver to load.
+**sess_valid_drivers**      cookie, native  None                        Additional valid drivers which may be loaded.
+**sess_cookie_name**        ci_session      None                        The name you want the session cookie saved as (data for Cookie driver or
+                                                                        session ID for Native driver).
+**sess_expiration**         7200            None                        The number of seconds you would like the session to last. The default
+                                                                        value is 2 hours (7200 seconds). If you would like a non-expiring
+                                                                        session set the value to zero: 0
+**sess_expire_on_close**    FALSE           TRUE/FALSE (boolean)        Whether to cause the session to expire automatically when the browser
+                                                                        window is closed.
+**sess_encrypt_cookie**     FALSE           TRUE/FALSE (boolean)        Whether to encrypt the session data (Cookie driver only).
+**sess_use_database**       FALSE           TRUE/FALSE (boolean)        Whether to save the session data to a database. You must create the
+                                                                        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.
+**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.
+**sess_match_useragent**    TRUE            TRUE/FALSE (boolean)        Whether to match the User Agent when reading the session data.
+=========================== =============== =========================== ==========================================================================
+
+In addition to the values above, the cookie and native drivers apply the
+following configuration values shared by the :doc:`Input <input>` and
+:doc:`Security <security>` classes:
+
+=========================== =============== ==========================================================================
+Preference                  Default         Description
+=========================== =============== ==========================================================================
+**cookie_prefix**           ''              Set a cookie name prefix in order to avoid name collisions
+**cookie_domain**           ''              The domain for which the session is applicable
+**cookie_path**             /               The path to which the session is applicable
+=========================== =============== ==========================================================================
+
+Session Drivers
+===============
+
+By default, the `Cookie Driver`_ is loaded when a session is initialized.
+However, any valid driver may be selected with the $config['sess_driver']
+line in your config.php file.
+
+The session driver library comes with the cookie and native drivers
+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()::
+
+	$this->session->load_driver('native');
+
+The Session library keeps track of the most recently selected driver to call
+for driver methods. Normally, session class methods are called directly on
+the parent class, as illustrated above. However, any methods called through
+a specific driver will select that driver before invoking the parent method.
+
+So, alternation between multiple drivers can be achieved by specifying which
+driver to use for each call::
+
+	$this->session->native->set_userdata('foo', 'bar');
+
+	$this->session->cookie->userdata('foo');
+
+	$this->session->native->unset_userdata('foo');
+
+Notice in the previous example that the *native* userdata value 'foo'
+would be set to 'bar', which would NOT be returned by the call for
+the *cookie* userdata 'foo', nor would the *cookie* value be unset by
+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::
+
+	$this->session->select_driver('native');
+
+	$this->session->userdata('item');	// Uses the native driver
+
+Cookie Driver
+-------------
+
+The Cookie driver stores session information for each user as serialized
+(and optionally encrypted) data in a cookie. It can also store the session
+data in a database table for added security, as this permits the session ID
+in the user's cookie to be matched against the stored session ID. By default
+only the cookie is saved. If you choose to use the database option you'll
+need to create the session table as indicated below.
+
+If you have the encryption option enabled, the serialized array will be
+encrypted before being stored in the cookie, making the data highly
+secure and impervious to being read or altered by someone. More info
+regarding encryption can be :doc:`found here <encryption>`, although
+the Session class will take care of initializing and encrypting the data
+automatically.
+
+.. note:: Even if you are not using encrypted sessions, you must set
+	an :doc:`encryption key <./encryption>` in your config file which is used
+	to aid in preventing session data manipulation.
+
+.. note:: Cookies can only hold 4KB of data, so be careful not to exceed
+	the capacity. The encryption process in particular produces a longer
+	data string than the original so keep careful track of how much data you
+	are storing.
 
 Saving Session Data to a Database
-=================================
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 While the session data array stored in the user's cookie contains a
 Session ID, unless you store session data in a database there is no way
@@ -267,44 +406,83 @@ session class::
 
 		$config['sess_table_name'] = 'ci_sessions';
 
-.. note:: The Session class has built-in garbage collection which clears
+.. note:: The Cookie driver has built-in garbage collection which clears
 	out expired sessions so you do not need to write your own routine to do
 	it.
 
-Destroying a Session
-====================
+Native Driver
+-------------
 
-To clear the current session::
+The Native driver relies on native PHP sessions to store data in the
+$_SESSION superglobal array. All stored values continue to be available
+through $_SESSION, but flash- and temp- data items carry special prefixes.
 
-	$this->session->sess_destroy();
+Custom Drivers
+--------------
 
-.. 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().
+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.
 
-Session Preferences
-===================
+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,
+and an access handler to expose the data (get_userdata). Your initial class
+might look like::
 
-You'll find the following Session related preferences in your
-application/config/config.php file:
+	class CI_Session_custom extends CI_Session_driver {
+		protected function initialize()
+		{
+			// Read existing session data or create a new one
+		}
+
+		public function sess_save()
+		{
+			// Save current data to storage
+		}
+
+		public function sess_destroy()
+		{
+			// Destroy the current session and clean up storage
+		}
+
+		public function sess_regenerate()
+		{
+			// Create new session ID
+		}
+
+		public function &get_userdata()
+		{
+			// Return a reference to your userdata array
+		}
+	}
+
+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
+named CI_Session_<name>, and your filename must be Session_<name>.php,
+preferably also capitalized, such as::
+
+	CI_Session_foo in libraries/Session/drivers/Session_foo.php
+
+Then specify the driver by setting 'sess_driver' in your config.php file or as a
+parameter when loading the CI_Session object::
+
+	$config['sess_driver'] = 'foo';
+
+OR::
+
+	$CI->load->driver('session', array('sess_driver' => 'foo'));
+
+The driver specified by 'sess_driver' is automatically included as a valid
+driver. However, if you want to make a custom driver available as an option
+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');
 
-=========================== =============== =========================== ==========================================================================
-Preference                  Default         Options                     Description
-=========================== =============== =========================== ==========================================================================
-**sess_cookie_name**        ci_session      None                        The name you want the session cookie saved as.
-**sess_expiration**         7200            None                        The number of seconds you would like the session to last. The default
-                                                                        value is 2 hours (7200 seconds). If you would like a non-expiring
-                                                                        session set the value to zero: 0
-**sess_expire_on_close**    FALSE           TRUE/FALSE (boolean)        Whether to cause the session to expire automatically when the browser
-                                                                        window is closed.
-**sess_encrypt_cookie**     FALSE           TRUE/FALSE (boolean)        Whether to encrypt the session data.
-**sess_use_database**       FALSE           TRUE/FALSE (boolean)        Whether to save the session data to a database. You must create the
-                                                                        table before enabling this option.
-**sess_table_name**         ci_sessions     Any valid SQL table name    The name of the session database table.
-**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.
-**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.
-**sess_match_useragent**    TRUE            TRUE/FALSE (boolean)        Whether to match the User Agent when reading the session data.
-=========================== =============== =========================== ==========================================================================
\ No newline at end of file