diff options
Diffstat (limited to 'user_guide_src/source/installation/upgrade_300.rst')
| -rw-r--r-- | user_guide_src/source/installation/upgrade_300.rst | 199 |
1 files changed, 165 insertions, 34 deletions
diff --git a/user_guide_src/source/installation/upgrade_300.rst b/user_guide_src/source/installation/upgrade_300.rst index 6915fafe2..497dc7263 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.1 to 3.0.0 ############################# .. note:: These upgrade notes are for a version that is yet to be released. @@ -83,37 +83,102 @@ 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: + + - ``session_id`` field is renamed to ``id`` + - ``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; @@ -158,6 +223,10 @@ Step 10: Many functions now return NULL instead of FALSE on missing items Many methods and functions now return NULL instead of FALSE when the required items don't exist: + - :doc:`Common functions <../general/common_functions>` + + - config_item() + - :doc:`Config Class <../libraries/config>` - config->item() @@ -219,8 +288,45 @@ Otherwise however, please review your usage of the following functions: ``$_COOKIE`` and ``$_SERVER`` superglobals are no longer automatically overwritten when global XSS filtering is turned on. +************************************************* +Step 12: Check for potential XSS issues with URIs +************************************************* + +The :doc:`URI Library <../libraries/uri>` used to automatically convert +a certain set of "programmatic characters" to HTML entities when they +are encountered in a URI segment. + +This was aimed at providing some automatic XSS protection, in addition +to the ``$config['permitted_uri_chars']`` setting, but has proven to be +problematic and is now removed in CodeIgniter 3.0. + +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 12: 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()`` @@ -230,15 +336,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 13: 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 14: 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 @@ -260,7 +366,7 @@ If your application relies on IF EXISTS, you'll have to change its usage. all drivers with the exception of ODBC. *********************************************************** -Step 15: 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 @@ -275,7 +381,7 @@ pass FALSE as the first parameter in the ``send()`` method: } *************************************************** -Step 16: 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 @@ -306,7 +412,7 @@ files and error messages format: later. **************************************************************** -Step 17: 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 @@ -327,11 +433,14 @@ Usage of the ``EXT`` constant has been deprecated since dropping support for PHP longer a need to maintain different filename extensions and in this new CodeIgniter version, the ``EXT`` constant has been removed. Use just '.php' instead. -Smiley helper js_insert_smiley() -================================ +Smiley helper +============= -:doc:`Smiley Helper <../helpers/smiley_helper>` function ``js_insert_smiley()`` has been deprecated -since CodeIgniter 1.7.2 and is now removed. You'll need to switch to ``smiley_js()`` instead. +The :doc:`Smiley Helper <../helpers/smiley_helper>` is a legacy feature from EllisLab's +ExpressionEngine product. However, it is too specific for a general purpose framework like +CodeIgniter and as such it is now deprecated. + +Also, the previously deprecated ``js_insert_smiley()`` (since version 1.7.2) is now removed. The Encrypt library =================== @@ -351,6 +460,16 @@ implemented cryptographic functions. .. important:: You are strongly encouraged to switch to the new :doc:`Encryption Library <../libraries/encryption>` as soon as possible! +The Cart library +================ + +The :doc:`Cart Library <../libraries/cart>`, similarly to the :doc:`Smiley Helper +<../helpers/smiley_helper>` is too specific for CodeIgniter. It is now deprecated +and scheduled for removal in CodeIgniter 3.1+. + +.. note:: The library is still available, but you're strongly encouraged to remove its usage sooner + rather than later. + Database drivers 'mysql', 'sqlite', 'mssql', 'pdo/dblib' ======================================================== @@ -409,6 +528,18 @@ scheduled for removal in CodeIgniter 3.1+. .. note:: This function is still available, but you're strongly encouraged to remove its usage sooner rather than later. +Form helper form_prep() +======================= + +:doc:`Form Helper <../helpers/form_helper>` function :func:`form_prep()` +is now just an alias for :doc:`common function </general/common_functions>` +:func:`html_escape()`. It is deprecated and will be removed in the future. + +Please use :func:`html_escape()` instead. + +.. note:: This function is still available, but you're strongly encouraged + to remove its usage sooner rather than later. + Email helper functions ====================== |