Merge remote-tracking branch 'upstream/develop' into docs-update-cli-generators

Author: sammyskills

composer.json

@@ -24,7 +24,7 @@
         "phpunit/phpcov": "^8.2",
         "phpunit/phpunit": "^9.1",
         "predis/predis": "^1.1 || ^2.0",
-        "rector/rector": "0.15.23",
+        "rector/rector": "0.15.24",
         "vimeo/psalm": "^5.0"
     },
     "suggest": {

contributing/documentation.rst

@@ -3,17 +3,12 @@ Writing CodeIgniter Documentation
 #################################
 
 CodeIgniter uses Sphinx to generate its documentation in a variety of formats,
-using reStructuredText to handle the formatting.  If you are familiar with
+using `reStructuredText`_ to handle the formatting.  If you are familiar with
 Markdown or Textile, you will quickly grasp reStructuredText.  The focus is
 on readability and user friendliness.
 While they can be quite technical, we always write for humans!
 
-A local table of contents should always be included, like the one below.
-It is created automatically by inserting the following::
-
-    .. contents::
-        :local:
-        :depth: 2
+.. _reStructuredText: https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html
 
 .. contents::
   :local:
@@ -26,7 +21,18 @@ To see the rendered HTML, ePub, PDF, etc., you will need to install Sphinx
 along with the PHP domain extension for Sphinx. The underlying requirement
 is to have Python installed.
 
-You can read more about installing all tools in /user_guide_src/README.rst
+You can read more about installing all tools in **user_guide_src/README.rst**
+
+*****************
+Table of Contents
+*****************
+
+A local table of contents should always be included, like the one below.
+It is created automatically by inserting the following::
+
+    .. contents::
+        :local:
+        :depth: 2
 
 *****************************************
 Page and Section Headings and Subheadings
@@ -119,15 +125,21 @@ You can reference a page like the following::
 To a URL
 ========
 
+::
+
     `CodeIgniter 4 framework <https://github.com/codeigniter4/framework>`_
 
 To a Function
 =============
 
+::
+
     :php:func:`dot_array_search()`
 
 To a Method
-=============
+===========
+
+::
 
     :php:meth:`CodeIgniter\\HTTP\\Response::setCookie()`
 
@@ -138,10 +150,24 @@ Other Directives
 New Feature
 ===========
 
+::
+
     .. versionadded:: 4.3.0
 
 Deprecated
 ==========
 
+::
+
     .. deprecated:: 4.3.0
        Use :php:meth:`CodeIgniter\\Database\\BaseBuilder::setData()` instead.
+
+***************
+Text Decoration
+***************
+
+As a general rule, we use ``**`` for in-line file paths, and `````` for source code.
+
+E.g.::
+
+    Open the **app/Config/Filters.php** file and update the ``$methods`` property like the following:

user_guide_src/source/general/configuration.rst

@@ -63,6 +63,8 @@ One of today's best practices for application setup is to use Environment Variab
 
 Environment Variables should also be used for anything private such as passwords, API keys, or other sensitive data.
 
+.. _dotenv-file:
+
 Environment Variables and CodeIgniter
 =====================================
 

user_guide_src/source/general/environments.rst

@@ -11,29 +11,44 @@ tools loaded that you don't in production environments, etc.
 
 .. contents::
     :local:
-    :depth: 2
+    :depth: 3
+
+************************
+The Defined Environments
+************************
+
+By default, CodeIgniter has three environments defined.
+
+- ``production`` for production
+- ``development`` for development
+- ``testing`` for PHPUnit testing
+
+.. important:: The environment ``testing`` is reserved for PHPUnit testing. It
+    has special conditions built into the framework at various places to assist
+    with that. You can't use it for your development.
+
+If you want another environment, e.g., for staging, you can add custom environments.
+See `Adding Environments`_.
+
+*******************
+Setting Environment
+*******************
 
 .. _environment-constant:
 
 The ENVIRONMENT Constant
 ========================
 
-By default, CodeIgniter comes with the ``ENVIRONMENT`` constant set to use
-the value provided in ``$_SERVER['CI_ENVIRONMENT']``, otherwise defaulting to
-``production``. This can be set in several ways depending on your server setup.
-
-.. note:: The environment ``testing`` is the special one for PHPUnit testing.
-    It has special conditions built into the framework at various places to assist with that.
-    You can't use it for your development.
+To set your environment, CodeIgniter comes with the ``ENVIRONMENT`` constant.
+If you set ``$_SERVER['CI_ENVIRONMENT']``, the value will be used,
+otherwise defaulting to ``production``.
 
-.. note:: You can check the current environment by ``spark env`` command::
-
-    > php spark env
+This can be set in several ways depending on your server setup.
 
 .env
 ----
 
-The simplest method to set the variable is in your :doc:`.env file </general/configuration>`.
+The simplest method to set the variable is in your :ref:`.env file <dotenv-file>`.
 
 .. code-block:: ini
 
@@ -88,8 +103,14 @@ In addition to affecting some basic framework behavior (see the next
 section), you may use this constant in your own development to
 differentiate between which environment you are running in.
 
+*******************
+Adding Environments
+*******************
+
+To add custom environments, you just need to add boot files for them.
+
 Boot Files
-----------
+==========
 
 CodeIgniter requires that a PHP script matching the environment's name is located
 under **APPPATH/Config/Boot**. These files can contain any customizations that
@@ -102,15 +123,32 @@ a fresh install:
 * production.php
 * testing.php
 
+For example, if you want to add ``staging`` environment for staging, all you need
+to do is:
+
+1. copy **APPPATH/Config/Boot/production.php** to **staging.php**.
+2. customize settings in **staging.php** if you want.
+
+**********************************
+Confirming the Current Environment
+**********************************
+
+To confirm the current environment, simply echo the constant ``ENVIRONMENT``.
+
+You can also check the current environment by ``spark env`` command::
+
+    > php spark env
+
+*************************************
 Effects on Default Framework Behavior
-=====================================
+*************************************
 
 There are some places in the CodeIgniter system where the ``ENVIRONMENT``
 constant is used. This section describes how default framework behavior
 is affected.
 
 Error Reporting
----------------
+===============
 
 Setting the ``ENVIRONMENT`` constant to a value of ``development`` will cause
 all PHP errors to be rendered to the browser when they occur.

user_guide_src/source/installation/upgrade_4xx.rst

@@ -62,7 +62,10 @@ Application Structure
 Routing
 =======
 
-- The Auto Routing is disabled by default. If you want to use the Auto Routing in the same way as CI3, you need to enable :ref:`auto-routing-legacy`.
+- The Auto Routing is disabled by default. You need to :ref:`define all routes
+  <defined-route-routing>` by default.
+- If you want to use the Auto Routing in the same way as CI3, you need to enable
+  :ref:`auto-routing-legacy`.
 - CI4 also has an optional new more secure :ref:`auto-routing-improved`.
 
 Model, View and Controller
@@ -204,6 +207,3 @@ Upgrading Libraries
     upgrade_sessions
     upgrade_validations
     upgrade_view_parser
-
-.. note::
-    More upgrade guides coming soon

user_guide_src/source/installation/upgrade_validations.rst

@@ -15,6 +15,9 @@ What has been changed
 =====================
 - If you want to change validation error display, you have to set CI4 :ref:`validation View templates <validation-customizing-error-display>`.
 - CI4 validation has no Callbacks nor Callable in CI3.
+  Use :ref:`Rule Classes <validation-using-rule-classes>` or
+  :ref:`Closure Rule <validation-using-closure-rule>`
+  instead.
 - CI4 validation format rules do not permit empty string.
 - CI4 validation never changes your data.
 - Since v4.3.0, :php:func:`validation_errors()` has been introduced, but the API is different from CI3's.

user_guide_src/source/libraries/security.rst

@@ -121,6 +121,9 @@ Redirection on Failure
 Since v4.3.0, when a request fails the CSRF validation check,
 it will throw a SecurityException by default,
 
+.. note:: In production environment, when you use HTML forms, it is recommended
+    to enable this redirection for a better user experience.
+
 If you want to make it redirect to the previous page,
 change the following config parameter value in
 **app/Config/Security.php**:

user_guide_src/source/libraries/validation.rst

@@ -612,6 +612,8 @@ right after the name of the field the error should belong to::
 Creating Custom Rules
 *********************
 
+.. _validation-using-rule-classes:
+
 Using Rule Classes
 ==================