diff options
Diffstat (limited to 'user_guide_src/source/installation/upgrade_300.rst')
-rw-r--r-- | user_guide_src/source/installation/upgrade_300.rst | 145 |
1 files changed, 115 insertions, 30 deletions
diff --git a/user_guide_src/source/installation/upgrade_300.rst b/user_guide_src/source/installation/upgrade_300.rst index 549adfe6b..3e6db390e 100644 --- a/user_guide_src/source/installation/upgrade_300.rst +++ b/user_guide_src/source/installation/upgrade_300.rst @@ -1,5 +1,5 @@ ############################# -Upgrading from 2.1.4 to 3.0.0 +Upgrading from 2.2.0 to 3.0.0 ############################# .. note:: These upgrade notes are for a version that is yet to be released. @@ -83,37 +83,101 @@ or extensions to work, you need to move them to **application/core/**:: application/libraries/Log.php -> application/core/Log.php application/libraries/MY_Log.php -> application/core/MY_Log.php -********************************************************* -Step 6: Convert your Session usage from library to driver -********************************************************* +***************************************** +Step 6: Update your Session library usage +***************************************** -When you load (or autoload) the Session library, you must now load it as a driver instead of a library. This means -calling ``$this->load->driver('session')`` instead of ``$this->load->library('session')`` and/or listing 'session' -in ``$autoload['drivers']`` instead of ``$autoload['libraries']``. +The :doc:`Session Library </libraries/sessions>` has been completely +re-written in CodeIgniter 3 and now comes with a bunch of new features, +but that also means that there are changes that you should make ... -With the change from a single Session Library to the new Session Driver, two new config items have been added: +Most notably, the library now uses separate storage drivers instead of +always relying on (encrypted) cookies. +In fact, cookies as storage have now been removed and you must always use +some kind of server-side storage engine, with the file-system being the +default option. - - ``$config['sess_driver']`` selects which driver to initially load. Options are: - - 'cookie' (the default) for classic CodeIgniter cookie-based sessions - - 'native' for native PHP Session support - - the name of a custom driver you have provided (see :doc:`Session Driver <../libraries/sessions>` for more info) - - ``$config['sess_valid_drivers']`` provides an array of additional custom drivers to make available for loading +The Session Class now utilizes PHP's own mechanisms for building custom +session handlers, which also means that your session data is now +accessible via the ``$_SESSION`` superglobal (though, we've kept the +possibility to use it as "userdata", like you've done until now). -As the new Session Driver library loads the classic Cookie driver by default and always makes 'cookie' and 'native' -available as valid drivers, neither of these configuration items are required. However, it is recommended that you -add them for clarity and ease of configuration in the future. +A few configuration options have been removed and a few have been added. +You should really read the whole :doc:`Session library manual +</libraries/sessions>` for the details, but here's a short list of changes +that you should make: -If you have written a Session extension, you must move it into a 'Session' sub-directory of 'libraries', following the -standard for Drivers. Also beware that some functions which are not part of the external Session API have moved into -the drivers, so your extension may have to be broken down into separate library and driver class extensions. + - Set your ``$config['sess_driver']`` value + + It will default to 'files', unles you've previously used + ``$config['sess_use_database']``, in which case it will be set to + 'database'. + + - Set a ``$config['sess_save_path']`` value + + For the 'database' driver, a fallback to ``$config['sess_table_name']`` + is in place, but otherwise requires you to read the manual for the + specific driver of your choice. + + - Update your ``ci_sessions`` table ('database' driver only) + + The table structure has changed a bit, and more specifically: + + - ``user_agent`` field is dropped + - ``user_data`` field is renamed to ``data`` and under MySQL is now of type BLOB + - ``last_activity`` field is renamed to ``timestamp`` + + This is accompanied by a slight change in the table indexes too, so + please read the manual about the `Session Database Driver + <../libraries/sessions.html#database-driver>`_ for more information. + + .. important:: Only MySQL and PostgreSQL are officially supported + now. Other databases may still work, but due to lack of advisory + locking features, they are unsafe for concurrent requests and + you should consider using another driver instead. + + - Remove ``$config['sess_match_useragent']`` + + The user-agent string is input supplied by the user's browser, or in + other words: client side input. As such, it is an ineffective feature + and hence why it has been removed. + + - Remove ``$config['sess_encrypt_cookie']`` + + As already noted, the library no longer uses cookies as a storage + mechanism, which renders this option useless. + + - Remove ``$config['sess_expire_on_close']`` + + This option is still usable, but only for backwards compatibility + purposes and it should be otherwise removed. The same effect is + achieved by setting ``$config['sess_expiration']`` to 0. + + - Check "flashdata" for collisions with "userdata" + + Flashdata is now just regular "userdata", only marked for deletion on + the next request. In other words: you can't have both "userdata" and + "flashdata" with the same name, because it's the same thing. + + - Check usage of session metadata + + Previously, you could access the 'session_id', 'ip_address', + 'user_agent' and 'last_activity' metadata items as userdata. + This is no longer possible, and you should read the notes about + `Session Metadata <../libraries/sessions.html#accessing-session-metadata>`_ + if your application relies on those values. + +Finally, if you have written a Session extension, you must now move it to +the *application/libraries/Session/* directory, although chances are that +it will now also have to be re-factored. *************************************** Step 7: Update your config/database.php *************************************** -Due to 3.0.0's renaming of Active Record to Query Builder, inside your `config/database.php`, you will -need to rename the `$active_record` variable to `$query_builder` -:: +Due to 3.0.0's renaming of Active Record to Query Builder, inside your +**config/database.php**, you will need to rename the ``$active_record`` +variable to ``$query_builder``:: $active_group = 'default'; // $active_record = TRUE; @@ -239,8 +303,29 @@ If your application has relied on this feature, you should update it to filter URI segments through ``$this->security->xss_clean()`` whenever you output them. +**************************************************************** +Step 13: Check for usage of the 'xss_clean' Form validation rule +**************************************************************** + +A largely unknown rule about XSS cleaning is that it should *only be +applied to output*, as opposed to input data. + +We've made that mistake ourselves with our automatic and global XSS cleaning +feature (see previous step about XSS above), so now in an effort to discourage that +practice, we're also removing 'xss_clean' from the officially supported +list of :doc:`form validation <../libraries/form_validation>` rules. + +Because the :doc:`Form Validation library <../libraries/form_validation>` +generally validates *input* data, the 'xss_clean' rule simply doesn't +belong in it. + +If you really, really need to apply that rule, you should now also load the +:doc:`Security Helper <../helpers/security_helper>`, which contains +``xss_clean()`` as a regular function and therefore can be also used as +a validation rule. + ******************************************************** -Step 13: Update usage of Input Class's get_post() method +Step 14: Update usage of Input Class's get_post() method ******************************************************** Previously, the :doc:`Input Class <../libraries/input>` method ``get_post()`` @@ -250,15 +335,15 @@ modified so that it searches in GET then in POST, as its name suggests. A method has been added, ``post_get()``, which searches in POST then in GET, as ``get_post()`` was doing before. -*********************************************************************** -Step 14: Update usage of Directory Helper's directory_map() function -*********************************************************************** +******************************************************************** +Step 15: Update usage of Directory Helper's directory_map() function +******************************************************************** In the resulting array, directories now end with a trailing directory separator (i.e. a slash, usually). ************************************************************* -Step 15: Update usage of Database Forge's drop_table() method +Step 16: Update usage of Database Forge's drop_table() method ************************************************************* Up until now, ``drop_table()`` added an IF EXISTS clause by default or it didn't work @@ -280,7 +365,7 @@ If your application relies on IF EXISTS, you'll have to change its usage. all drivers with the exception of ODBC. *********************************************************** -Step 16: Change usage of Email library with multiple emails +Step 17: Change usage of Email library with multiple emails *********************************************************** The :doc:`Email Library <../libraries/email>` will automatically clear the @@ -295,7 +380,7 @@ pass FALSE as the first parameter in the ``send()`` method: } *************************************************** -Step 17: Update your Form_validation language lines +Step 18: Update your Form_validation language lines *************************************************** Two improvements have been made to the :doc:`Form Validation Library @@ -326,7 +411,7 @@ files and error messages format: later. **************************************************************** -Step 18: Remove usage of (previously) deprecated functionalities +Step 19: Remove usage of (previously) deprecated functionalities **************************************************************** In addition to the ``$autoload['core']`` configuration setting, there's a |