diff options
Diffstat (limited to 'user_guide_src/source/installation')
| -rw-r--r-- | user_guide_src/source/installation/downloads.rst | 5 | ||||
| -rw-r--r-- | user_guide_src/source/installation/upgrade_220.rst | 2 | ||||
| -rw-r--r-- | user_guide_src/source/installation/upgrade_300.rst | 43 | ||||
| -rw-r--r-- | user_guide_src/source/installation/upgrade_310.rst | 2 | ||||
| -rw-r--r-- | user_guide_src/source/installation/upgrade_320.rst | 259 | ||||
| -rw-r--r-- | user_guide_src/source/installation/upgrading.rst | 1 |
6 files changed, 286 insertions, 26 deletions
diff --git a/user_guide_src/source/installation/downloads.rst b/user_guide_src/source/installation/downloads.rst index 180734448..de9a22a58 100644 --- a/user_guide_src/source/installation/downloads.rst +++ b/user_guide_src/source/installation/downloads.rst @@ -2,7 +2,8 @@ Downloading CodeIgniter ####################### -- `CodeIgniter v3.1.12-dev (Current version) <https://codeload.github.com/bcit-ci/CodeIgniter/zip/3.1-stable>`_ +- `CodeIgniter v3.2.0-dev (Current version) <https://codeload.github.com/bcit-ci/CodeIgniter/zip/develop>`_ +- `CodeIgniter v3.1.12-dev <https://codeload.github.com/bcit-ci/CodeIgniter/zip/3.1-stable>`_ - `CodeIgniter v3.1.11 <https://codeload.github.com/bcit-ci/CodeIgniter/zip/3.1.11>`_ - `CodeIgniter v3.1.10 <https://codeload.github.com/bcit-ci/CodeIgniter/zip/3.1.10>`_ - `CodeIgniter v3.1.9 <https://codeload.github.com/bcit-ci/CodeIgniter/zip/3.1.9>`_ @@ -39,7 +40,7 @@ Downloading CodeIgniter GitHub ****** -`Git <http://git-scm.com/about>`_ is a distributed version control system. +`Git <https://git-scm.com/about>`_ is a distributed version control system. Public Git access is available at `GitHub <https://github.com/bcit-ci/CodeIgniter>`_. Please note that while every effort is made to keep this code base diff --git a/user_guide_src/source/installation/upgrade_220.rst b/user_guide_src/source/installation/upgrade_220.rst index 91f9e00cd..489dd6312 100644 --- a/user_guide_src/source/installation/upgrade_220.rst +++ b/user_guide_src/source/installation/upgrade_220.rst @@ -7,7 +7,7 @@ Upgrading from 2.1.4 to 2.2.x without Mcrypt, then this is a breaking change. You must install the Mcrypt extension in order to upgrade. For information on installing Mcrypt please see the PHP `documentation - <http://php.net/manual/en/mcrypt.setup.php>`. + <https://secure.php.net/manual/en/mcrypt.setup.php>`. Before performing an update you should take your site offline by replacing the index.php file with a static one. diff --git a/user_guide_src/source/installation/upgrade_300.rst b/user_guide_src/source/installation/upgrade_300.rst index 5b2d3947d..188144844 100644 --- a/user_guide_src/source/installation/upgrade_300.rst +++ b/user_guide_src/source/installation/upgrade_300.rst @@ -532,9 +532,9 @@ the ``EXT`` constant has been removed. Use just '.php' instead. Smiley helper ============= -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. +The *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. @@ -545,8 +545,8 @@ Following numerous vulnerability reports, the :doc:`Encrypt Library <../librarie been deprecated and a new, :doc:`Encryption Library <../libraries/encryption>` is added to take its place. -The new library requires either the `MCrypt extension <http://php.net/mcrypt>`_ (and /dev/urandom -availability) or PHP 5.3.3 and the `OpenSSL extension <http://php.net/openssl>`_. +The new library requires either the `MCrypt extension <https://secure.php.net/mcrypt>`_ (and /dev/urandom +availability) or PHP 5.3.3 and the `OpenSSL extension <https://secure.php.net/openssl>`_. While this might be rather inconvenient, it is a requirement that allows us to have properly implemented cryptographic functions. @@ -559,12 +559,12 @@ implemented cryptographic functions. 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+. +The *Cart Library*, similarly to the *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. +.. 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' ======================================================== @@ -624,7 +624,7 @@ CodeIgniter 3.1+. String helper repeater() ======================== -:doc:`String Helper <../helpers/string_helper>` function :php:func:`repeater()` is now just an alias for +:doc:`String Helper <../helpers/string_helper>` function ``repeater()`` is now just an alias for PHP's native ``str_repeat()`` function. It is deprecated and scheduled for removal in CodeIgniter 3.1+. .. note:: This function is still available, but you're strongly encouraged to remove its usage sooner @@ -633,7 +633,7 @@ PHP's native ``str_repeat()`` function. It is deprecated and scheduled for remov String helper trim_slashes() ============================ -:doc:`String Helper <../helpers/string_helper>` function :php:func:`trim_slashes()` is now just an alias +:doc:`String Helper <../helpers/string_helper>` function ``trim_slashes()`` is now just an alias for PHP's native ``trim()`` function (with a slash passed as its second argument). It is deprecated and scheduled for removal in CodeIgniter 3.1+. @@ -643,8 +643,8 @@ scheduled for removal in CodeIgniter 3.1+. Form helper form_prep() ======================= -:doc:`Form Helper <../helpers/form_helper>` function :php:func:`form_prep()` -is now just an alias for :doc:`common function </general/common_functions>` +:doc:`Form Helper <../helpers/form_helper>` function ``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 :php:func:`html_escape()` instead. @@ -655,14 +655,13 @@ Please use :php:func:`html_escape()` instead. Email helper functions ====================== -:doc:`Email Helper <../helpers/email_helper>` only has two functions +The *Email Helper* only has two functions: - - :php:func:`valid_email()` - - :php:func:`send_email()` + - ``valid_email()`` + - ``send_email()`` Both of them are now aliases for PHP's native ``filter_var()`` and ``mail()`` functions, respectively. -Therefore the :doc:`Email Helper <../helpers/email_helper>` altogether is being deprecated and -is scheduled for removal in CodeIgniter 3.1+. +Therefore, the *Email Helper* altogether is being deprecated and is scheduled for removal in CodeIgniter 3.1+. .. note:: These functions are still available, but you're strongly encouraged to remove their usage sooner rather than later. @@ -671,7 +670,7 @@ Date helper standard_date() =========================== :doc:`Date Helper <../helpers/date_helper>` function ``standard_date()`` is being deprecated due -to the availability of native PHP `constants <http://php.net/manual/en/class.datetime.php#datetime.constants.types>`_, +to the availability of native PHP `constants <https://secure.php.net/manual/en/class.datetime.php#datetime.constants.types>`_, which when combined with ``date()`` provide the same functionality. Furthermore, they have the exact same names as the ones supported by ``standard_date()``. Here are examples of how to replace its usage: @@ -845,8 +844,8 @@ CodeIgniter 3.1+. The Javascript library ====================== -The :doc:`Javascript Library <../libraries/javascript>` has always had an -'experimental' status and was never really useful, nor a proper solution. +The *Javascript Library* has always had an 'experimental' status and was +never really useful, nor a proper solution. It is now deprecated and scheduled for removal in CodeIgniter 3.1+. diff --git a/user_guide_src/source/installation/upgrade_310.rst b/user_guide_src/source/installation/upgrade_310.rst index 9e0108691..cae814327 100644 --- a/user_guide_src/source/installation/upgrade_310.rst +++ b/user_guide_src/source/installation/upgrade_310.rst @@ -35,4 +35,4 @@ does not provide a function that allows to safely escape user-supplied strings f inside an SQL query (which our :doc:`Query Builder <../database/query_builder>` relies on). Thus, user inputs MUST be bound, as shown in :doc:`Running Queries <../database/queries>`, -under the "Query Bindings" section.
\ No newline at end of file +under the "Query Bindings" section. diff --git a/user_guide_src/source/installation/upgrade_320.rst b/user_guide_src/source/installation/upgrade_320.rst new file mode 100644 index 000000000..3eadd8caf --- /dev/null +++ b/user_guide_src/source/installation/upgrade_320.rst @@ -0,0 +1,259 @@ +############################# +Upgrading from 3.1.x to 3.2.x +############################# + +Before performing an update you should take your site offline by +replacing the index.php file with a static one. + +Step 1: Update your CodeIgniter files +===================================== + +Replace all files and directories in your *system/* directory. + +.. note:: If you have any custom developed files in these directories, + please make copies of them first. + +Step 2: Check your PHP version +============================== + +We recommend always running versions that are `currently supported +<https://secure.php.net/supported-versions.php>`_, which right now is at least PHP 5.6. + +PHP 5.3.x versions are now officially not supported by CodeIgniter, and while 5.4.8+ +may be at least runnable, we strongly discourage you from using any PHP versions below +the ones listed on the `PHP.net Supported Versions <https://secure.php.net/supported-versions.php>`_ +page. + +Step 3: Remove calls to ``CI_Model::__construct()`` +=================================================== + +The class constructor for ``CI_Model`` never contained vital code or useful +logic, only a single line to log a message. A change in CodeIgniter 3.1.7 +moved this log message elsewhere and that naturally made the constructor +completely unnecessary. However, it was left in place to avoid immedate BC +breaks in a minor release. + +In version 3.2.0, that constructor is entirely removed, which would result +in fatal errors on attempts to call it. Particularly in code like this: +:: + + class Some_model extends CI_Model { + + public function __construct() + { + parent::__construct(); // calls CI_Model::__construct() + + do_some_other_thing(); + } + } + +All you need to do is remove that ``parent::__construct()`` call. On a side +note, the following seems to be a very common practice: +:: + + class Some_class extends CI_Something { + + public function __construct() + { + parent::__construct(); + } + } + +Please, do NOT do this! It's pointless; it serves no purpose and doesn't do +anything. If a parent class has a ``__construct()`` method, it will be +inherited by all its child classes and will execute just fine - you DON'T +have to explicitly call it unless you want to extend its logic. + +Step 4: Change database connection handling +=========================================== + +"Loading" a database, whether by using the *config/autoload.php* settings +or manually via calling ``$this->load->database()`` or the less-known +``DB()`` function, will now throw a ``RuntimeException`` in case of a +failure. + +In addition, being unable to set the configured character set is now also +considered a connection failure. + +.. note:: This has been the case for most database drivers in the in the + past as well (i.e. all but the 'mysql', 'mysqli' and 'postgre' + drivers). + +What this means is that if you're unable to connect to a database, or +have an erroneous character set configured, CodeIgniter will no longer +fail silently, but will throw an exception instead. + +You may choose to explicitly catch it (and for that purpose you can't use +*config/autoload.php* to load the :doc:`Database Class <../database/index>`) +:: + + try + { + $this->load->database(); + } + catch (RuntimeException $e) + { + // Handle the failure + } + +Or you may leave it to CodeIgniter's default exception handler, which would +log the error message and display an error screen if you're running in +development mode. + +Remove db_set_charset() calls +----------------------------- + +With the above-mentioned changes, the purpose of the ``db_set_charset()`` +method would now only be to change the connection character set at runtime. +That doesn't make sense and that's the reason why most database drivers +don't support it at all. +Thus, ``db_set_charset()`` is no longer necessary and is removed. + +Step 5: Check logic related to URI parsing of CLI requests +========================================================== + +When running a CodeIgniter application from the CLI, the +:doc:`URI Library <../libraries/uri>` will now ignore the +``$config['url_suffix']`` and ``$config['permitted_uri_chars']`` +configuration settings. + +These two options don't make sense under the command line (which is why +this change was made) and therefore you shouldn't be affected by this, but +if you've relied on them for some reason, you'd probably have to make some +changes to your code. + +Step 6: Check Cache Library configurations for Redis, Memcache(d) +================================================================= + +The new improvements for the 'redis' and 'memcached' drivers of the +:doc:`Cache Library <../libraries/caching>` may require some small +adjustments to your configuration values ... + +Redis +----- + +If you're using the 'redis' driver with a UNIX socket connection, you'll +have to move the socket path from ``$config['socket']`` to +``$config['host']`` instead. + +The ``$config['socket_type']`` option is also removed, although that won't +affect your application - it will be ignored and the connection type will +be determined by the format used for ``$config['host']`` instead. + +Memcache(d) +----------- + +The 'memcached' will now ignore configurations that don't specify a ``host`` +value (previously, it just set the host to the default '127.0.0.1'). + +Therefore, if you've added a configuration that only sets e.g. a ``port``, +you will now have to explicitly set the ``host`` to '127.0.0.1' as well. + +Step 7: Check usage of the Email library +======================================== + +The :doc:`Email Library <../libraries/email>` will now by default check the +validity of all e-mail addresses passed to it. This check used to be Off by +default, and required explicitly setting the **validate** option to ``TRUE`` +in order to enable it. + +Naturally, a validity check should not result in any problems, but this is +technically a backwards-compatibility break and you should check that +everything works fine. +If something indeed goes wrong with that, please report it as a bug to us, +and you can disable the **validate** option to revert to the old behavior. + +Step 8: Check usage of doctype() HTML helper +============================================ + +The :doc:`HTML Helper <../helpers/html_helper>` function +:php:func:`doctype()` used to default to 'xhtml1-strict' (XHTML 1.0 Strict) +when no document type was specified. That default value is now changed to +'html5', which obviously stands for the modern HTML 5 standard. + +Nothing should be really broken by this change, but if your application +relies on the default value, you should double-check it and either +explicitly set the desired format, or adapt your front-end to use proper +HTML 5 formatting. + +Step 9: Check usage of form_upload() Form helper +================================================ + +The :doc:`Form Helper <../helpers/form_helper>` function +:php:func:`form_upload()` used to have 3 parameters, the second of which +(``$value``) was never used, as it doesn't make sense for an HTML ``input`` +tag of the "file" type. + +That dead parameter is now removed, and so if you've used the third one +(``$extra``), having code like this:: + + form_upload('name', 'irrelevant value', $extra); + +You should change it to:: + + form_upload('name', $extra); + +Step 10: Remove usage of previously deprecated functionalities +============================================================== + +The following is a list of functionalities deprecated in previous +CodeIgniter versions that have been removed in 3.2.0: + +- ``$config['allow_get_array']`` (use ``$_GET = array();`` instead) +- ``$config['standardize_newlines']`` +- ``$config['rewrite_short_tags']`` (no impact; irrelevant on PHP 5.4+) + +- 'sqlite' database driver (no longer shipped with PHP 5.4+; 'sqlite3' is still available) + +- ``CI_Input::is_cli_request()`` (use :php:func:`is_cli()` instead) +- ``CI_Router::fetch_directory()`` (use ``CI_Router::$directory`` instead) +- ``CI_Router::fetch_class()`` (use ``CI_Router::$class`` instead) +- ``CI_Router::fetch_method()`` (use ``CI_Router::$method`` instead) +- ``CI_Config::system_url()`` (encourages insecure practices) +- ``CI_Form_validation::prep_for_form()`` (the *prep_for_form* rule) + +- ``standard_date()`` :doc:`Date Helper <../helpers/date_helper>` function (use ``date()`` instead) +- ``do_hash()`` :doc:`Security Helper <../helpers/security_helper>` function (use ``hash()`` instead) +- ``br()`` :doc:`HTML Helper <../helpers/html_helper>` function (use ``str_repeat()`` with ``'<br />'`` instead) +- ``nbs()`` :doc:`HTML Helper <../helpers/html_helper>` function (use ``str_repeat()`` with ``' '`` instead) +- ``trim_slashes()`` :doc:`String Helper <../helpers/string_helper>` function (use ``trim()`` with ``'/'`` instead) +- ``repeater()`` :doc:`String Helper <../helpers/string_helper>` function (use ``str_repeat()`` instead) +- ``read_file()`` :doc:`File Helper <../helpers/file_helper>` function (use ``file_get_contents()`` instead) +- ``form_prep()`` :doc:`Form Helper <../helpers/form_helper>` function (use :php:func:`html_escape()` instead) + +- The entire *Cart Library* (an archived version is available on GitHub: `bcit-ci/ci3-cart-library <https://github.com/bcit-ci/ci3-cart-library>`_) +- The entire *Javascript Library* (it was always experimental in the first place) + +- The entire *Email Helper*, which only had two functions: + + - ``valid_email()`` (use ``filter_var($email, FILTER_VALIDATE_EMAIL)`` instead) + - ``send_email()`` (use ``mail()`` instead) + +- The entire *Smiley Helper* (an archived version is available on GitHub: `bcit-ci/ci3-smiley-helper <https://github.com/bcit-ci/ci3-smiley-helper>`_) + +Step 11: Make sure you're validating all user inputs +==================================================== + +The :doc:`Input Library <../libraries/input>` used to (often +unconditionally) filter and/or sanitize user input in the ``$_GET``, +``$_POST`` and ``$_COOKIE`` superglobals. + +This was a legacy feature from older times, when things like +`register_globals <https://secure.php.net/register_globals>`_ and +`magic_quotes_gpc <https://secure.php.net/magic_quotes_gpc>`_ existed in +PHP. +It was a necessity back then, but this is no longer the case and reliance +on global filters is a bad practice, giving you a false sense of security. + +This functionality is now removed, and so if you've relied on it for +whatever reasons, you should double-check that you are properly validating +all user inputs in your application (as you always should do). + +Step 12: Clear your output cache (optional) +=========================================== + +Internal changes to the :doc:`Output Class <../libraries/output>` make it +so that if you're using the :doc:`Web Page Caching <../general/caching>` +feature, you'll be left with some old, garbage cache files. + +That shouldn't be a problem, but you may want to clear them. diff --git a/user_guide_src/source/installation/upgrading.rst b/user_guide_src/source/installation/upgrading.rst index 2499fe24b..789c9b32e 100644 --- a/user_guide_src/source/installation/upgrading.rst +++ b/user_guide_src/source/installation/upgrading.rst @@ -8,6 +8,7 @@ upgrading from. .. toctree:: :titlesonly: + Upgrading from 3.1.10+ to 3.2.x <upgrade_320> Upgrading from 3.1.11 to 3.1.12 <upgrade_3112> Upgrading from 3.1.10 to 3.1.11 <upgrade_3111> Upgrading from 3.1.9 to 3.1.10 <upgrade_3110> |