diff options
Diffstat (limited to 'user_guide_src/source/libraries/sessions.rst')
| -rw-r--r-- | user_guide_src/source/libraries/sessions.rst | 317 |
1 files changed, 317 insertions, 0 deletions
diff --git a/user_guide_src/source/libraries/sessions.rst b/user_guide_src/source/libraries/sessions.rst new file mode 100644 index 000000000..4ae3ea2c8 --- /dev/null +++ b/user_guide_src/source/libraries/sessions.rst @@ -0,0 +1,317 @@ +############# +Session Class +############# + +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. + +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 +: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 +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:: + + $this->load->library('session'); + +Once loaded, the Sessions library object will be available using: +$this->session + +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. + +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 +above behavior to happen. You can, as you'll see below, work with +session data or even add your own data to a user's session, but the +process of reading, writing, and updating a session is automatic. + +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 + 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 + data string) +- 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 ) + +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. + +Retrieving Session Data +======================= + +Any piece of information from the session array is available using the +following function:: + + $this->session->userdata('item'); + +Where item is the array index corresponding to the item you wish to +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 + trying to access does not exist. + +Adding Custom Session Data +========================== + +A useful aspect of the session array is that you can add your own data +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 +that data globally available to you without having to run a database +query when you need it. + +To add your data to the session array involves passing an array +containing your new data to this function:: + + $this->session->set_userdata($array); + +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 ); $this->session->set_userdata($newdata); + + +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'); + + +.. 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. + +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 +===================== + +Just as set_userdata() can be used to add information into a session, +unset_userdata() can be used to remove it, by passing the session key. +For example, if you wanted to remove 'some_name' from your session +information:: + + $this->session->unset_userdata('some_name'); + + +This function can also be passed an associative array of items to unset. + +:: + + $array_items = array('username' => '', 'email' => ''); $this->session->unset_userdata($array_items); + + +Flashdata +========= + +CodeIgniter supports "flashdata", or session data that will only be +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. + +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(). + +To read a flashdata variable:: + + $this->session->flashdata('item'); + + +If you find that you need to preserve a flashdata variable through an +additional request, you can do so using the keep_flashdata() function. + +:: + + $this->session->keep_flashdata('item'); + + +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 +to validate it. For some applications that require little or no +security, session ID validation may not be needed, but if your +application requires security, validation is mandatory. Otherwise, an +old session could be restored by a user modifying their cookies. + +When session data is available in a database, every time a valid session +is found in the user's cookie, a database query is performed to match +it. If the session ID does not match, the session is destroyed. Session +IDs can never be updated, they can only be generated when a new session +is created. + +In order to store sessions, you must first create a database table for +this purpose. Here is the basic prototype (for MySQL) required by the +session class: + +CREATE TABLE IF NOT EXISTS \`ci_sessions\` ( session_id varchar(40) +DEFAULT '0' NOT NULL, ip_address varchar(16) DEFAULT '0' NOT NULL, +user_agent varchar(120) NOT NULL, last_activity int(10) unsigned +DEFAULT 0 NOT NULL, user_data text NOT NULL, PRIMARY KEY (session_id), +KEY \`last_activity_idx\` (\`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:: + + $config['sess_use_database'] = TRUE; + + Once enabled, the Session class will store session data in the DB. + + Make sure you've specified the table name in your config file as well:: + + $config['sess_table_name'] = 'ci_sessions'; + +.. note:: The Session class 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 +==================== + +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_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. |