Merge pull request #7027 from kenjis/fix-docs-upgrade_4xx

docs: update Upgrading from 3.x to 4.x and MVC

Author: kenjis

user_guide_src/source/incoming/controllers.rst

@@ -16,6 +16,8 @@ A Controller is simply a class file that handles a HTTP request. :doc:`URI Routi
 Every controller you create should extend ``BaseController`` class.
 This class provides several features that are available to all of your controllers.
 
+.. _controller-constructor:
+
 Constructor
 ***********
 

user_guide_src/source/installation/upgrade_4xx.rst

@@ -35,8 +35,8 @@ General Adjustments
 Downloads
 =========
 
-- CI4 is still available as a ready-to-run zip or tarball.
-- It can also be installed using Composer.
+- CI4 is still available as a :doc:`ready-to-run zip or tarball <../installation/installing_manual>`.
+- It can also be installed using :doc:`Composer <../installation/installing_composer>`.
 
 Namespaces
 ==========
@@ -90,10 +90,10 @@ Class Loading
 
 - There is no longer a CodeIgniter "superobject", with framework component
   references magically injected as properties of your controller.
-- Classes are instantiated where needed, and components are managed
-  by ``Services``.
-- The class loader automatically handles PSR-4 style class locating,
-  within the ``App`` (**app**) and ``CodeIgniter`` (i.e., **system**) top level
+- Classes are instantiated where needed, and framework components are managed
+  by :doc:`../concepts/services`.
+- The :doc:`Autoloader <../concepts/autoloader>` automatically handles PSR-4 style class locating,
+  within the ``App`` (**app** folder) and ``CodeIgniter`` (i.e., **system** folder) top level
   namespaces; with Composer autoloading support.
 - You can configure the class loading to support whatever application structure
   you are most comfortable with, including the "HMVC" style.
@@ -102,21 +102,40 @@ Libraries
 =========
 
 - Your app classes can still go inside **app/Libraries**, but they don't have to.
-- Instead of CI3's ``$this->load->library(x);`` you can now use
+- Instead of CI3's ``$this->load->library('x');`` you can now use
   ``$this->x = new X();``, following namespaced conventions for your component.
 
 Helpers
 =======
 
-- Helpers are pretty much the same as before, though some have been simplified.
+- :doc:`Helpers <../general/helpers>` are pretty much the same as before, though some have been simplified.
+- Some helpers from CodeIgniter 3 no longer exists in Version 4. For all these
+  helpers, you have to find a new way to implement your functions. These
+  helpers are `CAPTCHA Helper <https://www.codeigniter.com/userguide3/helpers/captcha_helper.html>`_,
+  `Email Helper <https://www.codeigniter.com/userguide3/helpers/email_helper.html>`_.
+  `Path Helper <https://www.codeigniter.com/userguide3/helpers/path_helper.html>`_.
+  and `Smiley Helper <https://www.codeigniter.com/userguide3/helpers/smiley_helper.html>`_.
+- `Download Helper <https://www.codeigniter.com/userguide3/helpers/download_helper.html>`_
+  in CI3 was removed. You need to use Response object where you are using ``force_download()``.
+  See :ref:`force-file-download`.
+- `Language Helper <https://www.codeigniter.com/userguide3/helpers/language_helper.html>`_
+  in CI3 was removed. But ``lang()`` is always available in CI4. See :php:func:`lang()`.
+- `Typography Helper <https://www.codeigniter.com/userguide3/helpers/typography_helper.html>`_
+  in CI3 wll be :doc:`Typography Library <../libraries/typography>` in CI4.
+- `Directory Helper <https://www.codeigniter.com/userguide3/helpers/directory_helper.html>`_
+  and `File Helper <https://www.codeigniter.com/userguide3/helpers/file_helper.html>`_ in CI3
+  will be :doc:`../helpers/filesystem_helper` in CI4.
+- `String Helper <https://www.codeigniter.com/userguide3/helpers/string_helper.html>`_ functions
+  in CI3 are included in :doc:`../helpers/text_helper` in CI4.
 - In CI4, ``redirect()`` returns a ``RedirectResponse`` instance instead of redirecting and terminating script execution. You must return it.
     - `redirect() Documentation CodeIgniter 3.X <https://codeigniter.com/userguide3/helpers/url_helper.html#redirect>`_
     - `redirect() Documentation CodeIgniter 4.X <../general/common_functions.html#redirect>`_
 
 Events
 ======
 
-- Hooks have been replaced by Events.
+- `Hooks <https://www.codeigniter.com/userguide3/general/hooks.html>`_ have been
+  replaced by :doc:`../extending/events`.
 - Instead of CI3's ``$hook['post_controller_constructor']`` you now use
   ``Events::on('post_controller_constructor', ['MyClass', 'MyFunction']);``, with the namespace ``CodeIgniter\Events\Events;``.
 - Events are always enabled, and are available globally.
@@ -126,17 +145,18 @@ Extending the Framework
 
 - You don't need a **core** folder to hold ``MY_...`` framework
   component extensions or replacements.
-- You don't need ``MY_x`` classes inside your libraries folder
+- You don't need ``MY_X`` classes inside your libraries folder
   to extend or replace CI4 pieces.
 - Make any such classes where you like, and add appropriate
   service methods in **app/Config/Services.php** to load
   your components instead of the default ones.
+- See :doc:`../extending/core_classes` for details.
 
 Upgrading Libraries
 *******************
 
 - Your app classes can still go inside **app/Libraries**, but they don't have to.
-- Instead of CI3's ``$this->load->library(x);`` you can now use ``$this->x = new X();``,
+- Instead of CI3's ``$this->load->library('x');`` you can now use ``$this->x = new X();``,
   following namespaced conventions for your component.
 - Some libraries from CodeIgniter 3 no longer exists in Version 4. For all these
   libraries, you have to find a new way to implement your functions. These

user_guide_src/source/installation/upgrade_controllers.rst

@@ -15,10 +15,11 @@ What has been changed
 =====================
 
 - Since namespaces have been added to CodeIgniter 4, the controllers must be changed to support namespaces.
-- Controllers don't use constructors any more (to invoke CI 'magic') unless those are part of base controllers you make.
-- CI provides Request and Response objects for you to work with - more powerful than the CI3-way.
-- If you want a base controller (``MY_Controller`` in CI3), make it where you like,
-  e.g., BaseController extends Controller, and then have your controllers extend it
+- The constructor of CI4 Controller does not automatically load core classes into the properties.
+- CI4's Controller has a special constructor :ref:`initController() <controller-constructor>`.
+- CI4 provides :doc:`Request </incoming/incomingrequest>` and :doc:`Responses </outgoing/response>`
+  objects for you to work with - more powerful than the CI3-way.
+- If you want a base controller (``MY_Controller`` in CI3), use **app/Controllers/BaseController.php**.
 
 Upgrade Guide
 =============

user_guide_src/source/installation/upgrade_controllers/ci3sample/001.php

@@ -4,6 +4,6 @@ class Helloworld extends CI_Controller
 {
     public function index($name)
     {
-        echo "Hello $name! ";
+        echo 'Hello ' . html_escape($name) . '!';
     }
 }

user_guide_src/source/installation/upgrade_models.rst

@@ -24,15 +24,15 @@ Upgrade Guide
 2. Add this line just after the opening php tag: ``namespace App\Models;``.
 3. Below the ``namespace App\Models;`` line add this line: ``use CodeIgniter\Model;``.
 4. Replace ``extends CI_Model`` with ``extends Model``.
-5. Instead of CI3's ``$this->load->model(x);``, you would now use ``$this->x = new X();``, following namespaced conventions for your component. Alternatively, you can use the :php:func:`model()` function: ``$this->x = model('X');``.
+5. Instead of CI3's ``$this->load->model('x');``, you would now use ``$this->x = new X();``, following namespaced conventions for your component. Alternatively, you can use the :php:func:`model()` function: ``$this->x = model('X');``.
 
 If you use sub-directories in your model structure you have to change the namespace according to that.
 Example: You have a version 3 model located in **application/models/users/user_contact.php** the namespace has to be ``namespace App\Models\Users;`` and the model path in the version 4 should look like this: **app/Models/Users/UserContact.php**
 
 The new Model in CI4 has a lot of built-in methods. For example, the ``find($id)`` method. With this you can find data where the primary key is equal to ``$id``.
 Inserting data is also easier than before. In CI4 there is an ``insert($data)`` method. You can optionally make use of all those built-in methods and migrate your code to the new methods.
 
-You can find more information to those methods :doc:`here </models/model>`.
+You can find more information to those methods in :doc:`../models/model`.
 
 Code Example
 ============

user_guide_src/source/installation/upgrade_views.rst

@@ -15,9 +15,10 @@ What has been changed
 =====================
 
 - Your views look much like before, but they are invoked differently ... instead of CI3's
-  ``$this->load->view(x);``, you can use ``return view(x);``.
-- CI4 supports *View Cells* to build your response in pieces, and *View Layouts* for page layout.
-- The template parser is still there, and substantially enhanced.
+  ``$this->load->view('x');``, you can use ``return view('x');``.
+- CI4 supports :doc:`../outgoing/view_cells` to build your response in pieces,
+  and :doc:`../outgoing/view_layouts` for page layout.
+- The :doc:`Template Parser <../outgoing/view_parser>` is still there, and substantially enhanced.
 
 Upgrade Guide
 =============

user_guide_src/source/installation/upgrade_views/ci3sample/001.php

@@ -1,15 +1,15 @@
 <html>
 <head>
-    <title><?php echo $title; ?></title>
+    <title><?php echo html_escape($title); ?></title>
 </head>
 <body>
-    <h1><?php echo $heading; ?></h1>
+    <h1><?php echo html_escape($heading); ?></h1>
 
     <h3>My Todo List</h3>
 
     <ul>
     <?php foreach ($todo_list as $item): ?>
-        <li><?php echo $item; ?></li>
+        <li><?php echo html_escape($item); ?></li>
     <?php endforeach; ?>
     </ul>
 

user_guide_src/source/outgoing/response.rst

@@ -59,6 +59,8 @@ parameter. This is not case-sensitive.
 
 .. literalinclude:: response/006.php
 
+.. _force-file-download:
+
 Force File Download
 ===================