From 5b27a44084ca1b3d620cbe5c465db14180b896c6 Mon Sep 17 00:00:00 2001 From: HaoLiang Date: Mon, 22 Oct 2018 13:25:18 +0800 Subject: [PATCH] Error in user guide for session config. issues #1330 --- user_guide_src/source/libraries/sessions.rst | 77 ++++++++++---------- 1 file changed, 40 insertions(+), 37 deletions(-) diff --git a/user_guide_src/source/libraries/sessions.rst b/user_guide_src/source/libraries/sessions.rst index 3f8d23edcdc6..2bf224c21fff 100644 --- a/user_guide_src/source/libraries/sessions.rst +++ b/user_guide_src/source/libraries/sessions.rst @@ -7,10 +7,10 @@ activity while they browse your site. CodeIgniter comes with a few session storage drivers: - - files (default; file-system based) - - database - - redis - - memcached + - CodeIgniter\Session\Handlers\FileHandler (default; file-system based) + - CodeIgniter\Session\Handlers\DatabaseHandler + - CodeIgniter\Session\Handlers\MemcachedHandler + - CodeIgniter\Session\Handlers\RedisHandler .. contents:: :local: @@ -439,21 +439,24 @@ all of the options and their effects. You'll find the following Session related preferences in your **application/Config/App.php** file: -============================== =============== ======================================== ============================================================================================ -Preference Default Options Description -============================== =============== ======================================== ============================================================================================ -**sessionDriver** files files/database/redis/memcached/*custom* The session storage driver to use. -**sessionCookieName** ci_session [A-Za-z\_-] characters only The name used for the session cookie. -**sessionExpiration** 7200 (2 hours) Time in seconds (integer) The number of seconds you would like the session to last. - If you would like a non-expiring session (until browser is closed) set the value to zero: 0 -**sessionSavePath** NULL None Specifies the storage location, depends on the driver being used. -**sessionMatchIP** FALSE TRUE/FALSE (boolean) Whether to validate the user's IP address when reading the session cookie. - Note that some ISPs dynamically changes the IP, so if you want a non-expiring session you - will likely set this to FALSE. -**sessionTimeToUpdate** 300 Time in seconds (integer) This option controls how often the session class will regenerate itself and create a new - session ID. Setting it to 0 will disable session ID regeneration. -**sessionRegenerateDestroy** FALSE TRUE/FALSE (boolean) Whether to destroy session data associated with the old session ID when auto-regenerating - the session ID. When set to FALSE, the data will be later deleted by the garbage collector. +============================== ========================================= ============================================== ============================================================================================ +Preference Default Options Description +============================== ========================================= ============================================== ============================================================================================ +**sessionDriver** CodeIgniter\Session\Handlers\FileHandler CodeIgniter\Session\Handlers\FileHandler The session storage driver to use. + CodeIgniter\Session\Handlers\DatabaseHandler + CodeIgniter\Session\Handlers\MemcachedHandler + CodeIgniter\Session\Handlers\RedisHandler +**sessionCookieName** ci_session [A-Za-z\_-] characters only The name used for the session cookie. +**sessionExpiration** 7200 (2 hours) Time in seconds (integer) The number of seconds you would like the session to last. + If you would like a non-expiring session (until browser is closed) set the value to zero: 0 +**sessionSavePath** NULL None Specifies the storage location, depends on the driver being used. +**sessionMatchIP** FALSE TRUE/FALSE (boolean) Whether to validate the user's IP address when reading the session cookie. + Note that some ISPs dynamically changes the IP, so if you want a non-expiring session you + will likely set this to FALSE. +**sessionTimeToUpdate** 300 Time in seconds (integer) This option controls how often the session class will regenerate itself and create a new + session ID. Setting it to 0 will disable session ID regeneration. +**sessionRegenerateDestroy** FALSE TRUE/FALSE (boolean) Whether to destroy session data associated with the old session ID when auto-regenerating + the session ID. When set to FALSE, the data will be later deleted by the garbage collector. ============================== =============== ======================================== ============================================================================================ .. note:: As a last resort, the Session library will try to fetch PHP's @@ -486,12 +489,12 @@ Session Drivers As already mentioned, the Session library comes with 4 handlers, or storage engines, that you can use: - - files - - database - - redis - - memcached + - CodeIgniter\Session\Handlers\FileHandler + - CodeIgniter\Session\Handlers\DatabaseHandler + - CodeIgniter\Session\Handlers\MemcachedHandler + - CodeIgniter\Session\Handlers\RedisHandler -By default, the `Files Driver`_ will be used when a session is initialized, +By default, the `FileHandler Driver`_ will be used when a session is initialized, because it is the most safe choice and is expected to work everywhere (virtually every environment has a file system). @@ -500,10 +503,10 @@ line in your **application/Config/App.php** file, if you chose to do so. Have it in mind though, every driver has different caveats, so be sure to get yourself familiar with them (below) before you make that choice. -Files Driver +FileHandler Driver ------------ -The 'files' driver uses your file system for storing session data. +The 'FileHandler' driver uses your file system for storing session data. It can safely be said that it works exactly like PHP's own default session implementation, but in case this is an important detail for you, have it @@ -553,10 +556,10 @@ In addition, if performance is your only concern, you may want to look into using `tmpfs `_, (warning: external resource), which can make your sessions blazing fast. -Database Driver +DatabaseHandler Driver --------------- -The 'database' driver uses a relational database such as MySQL or +The 'DatabaseHandler' driver uses a relational database such as MySQL or PostgreSQL to store sessions. This is a popular choice among many users, because it allows the developer easy access to the session data within an application - it is just another table in your database. @@ -566,13 +569,13 @@ However, there are some conditions that must be met: - You can NOT use a persistent connection. - You can NOT use a connection with the *cacheOn* setting enabled. -In order to use the 'database' session driver, you must also create this +In order to use the 'DatabaseHandler' session driver, you must also create this table that we already mentioned and then set it as your ``$sessionSavePath`` value. For example, if you would like to use 'ci_sessions' as your table name, you would do this:: - public $sessionDriver = 'database'; + public $sessionDriver = 'CodeIgniter\Session\Handlers\DatabaseHandler'; public $sessionSavePath = 'ci_sessions'; And then of course, create the database table ... @@ -632,7 +635,7 @@ when it generates the code. done processing session data if you're having performance issues. -Redis Driver +RedisHandler Driver ------------ .. note:: Since Redis doesn't have a locking mechanism exposed, locks for @@ -647,10 +650,10 @@ The downside is that it is not as ubiquitous as relational databases and requires the `phpredis `_ PHP extension to be installed on your system, and that one doesn't come bundled with PHP. -Chances are, you're only be using the Redis driver only if you're already +Chances are, you're only be using the RedisHandler driver only if you're already both familiar with Redis and using it for other purposes. -Just as with the 'files' and 'database' drivers, you must also configure +Just as with the 'FileHandler' and 'DatabaseHandler' drivers, you must also configure the storage location for your sessions via the ``$sessionSavePath`` setting. The format here is a bit different and complicated at the same time. It is @@ -666,17 +669,17 @@ link you to it: For the most common case however, a simple ``host:port`` pair should be sufficient:: - public $sessionDiver = 'redis'; + public $sessionDiver = 'CodeIgniter\Session\Handlers\RedisHandler'; public $sessionSavePath = 'tcp://localhost:6379'; -Memcached Driver +MemcachedHandler Driver ---------------- .. note:: Since Memcached doesn't have a locking mechanism exposed, locks for this driver are emulated by a separate value that is kept for up to 300 seconds. -The 'MemcachedHandler' driver is very similar to the 'redis' one in all of its +The 'MemcachedHandler' driver is very similar to the 'RedisHandler' one in all of its properties, except perhaps for availability, because PHP's `Memcached `_ extension is distributed via PECL and some Linux distributions make it available as an easy to install package. @@ -694,7 +697,7 @@ considered as it may result in loss of sessions. The ``$sessionSavePath`` format is fairly straightforward here, being just a ``host:port`` pair:: - public $sessionDriver = 'memcached'; + public $sessionDriver = 'CodeIgniter\Session\Handlers\MemcachedHandler'; public $sessionSavePath = 'localhost:11211'; Bonus Tip