Merge remote-tracking branch 'upstream/develop' into 4.5

Author: kenjis

system/Debug/ExceptionHandler.php

@@ -99,8 +99,8 @@ public function handle(
             . DIRECTORY_SEPARATOR . 'errors' . DIRECTORY_SEPARATOR . $addPath;
 
         // Determine the views
-        $view    = $this->determineView($exception, $path);
-        $altView = $this->determineView($exception, $altPath);
+        $view    = $this->determineView($exception, $path, $statusCode);
+        $altView = $this->determineView($exception, $altPath, $statusCode);
 
         // Check if the view exists
         $viewFile = null;
@@ -121,13 +121,16 @@ public function handle(
     }
 
     /**
-     * Determines the view to display based on the exception thrown,
-     * whether an HTTP or CLI request, etc.
+     * Determines the view to display based on the exception thrown, HTTP status
+     * code, whether an HTTP or CLI request, etc.
      *
      * @return string The filename of the view file to use
      */
-    protected function determineView(Throwable $exception, string $templatePath): string
-    {
+    protected function determineView(
+        Throwable $exception,
+        string $templatePath,
+        int $statusCode = 500
+    ): string {
         // Production environments should have a custom exception file.
         $view = 'production.php';
 
@@ -149,8 +152,8 @@ protected function determineView(Throwable $exception, string $templatePath): st
         $templatePath = rtrim($templatePath, '\\/ ') . DIRECTORY_SEPARATOR;
 
         // Allow for custom views based upon the status code
-        if (is_file($templatePath . 'error_' . $exception->getCode() . '.php')) {
-            return 'error_' . $exception->getCode() . '.php';
+        if (is_file($templatePath . 'error_' . $statusCode . '.php')) {
+            return 'error_' . $statusCode . '.php';
         }
 
         return $view;

tests/system/Debug/ExceptionHandlerTest.php

@@ -71,7 +71,7 @@ public function testDetermineViewsRuntimeExceptionCode404(): void
         $templatePath = APPPATH . 'Views/errors/html';
         $viewFile     = $determineView($exception, $templatePath);
 
-        $this->assertSame('error_404.php', $viewFile);
+        $this->assertSame('error_exception.php', $viewFile);
     }
 
     public function testDetermineViewsDisplayErrorsOffRuntimeException(): void

user_guide_src/source/changelogs/v4.4.8.rst

@@ -14,6 +14,11 @@ Release Date: Unreleased
 BREAKING
 ********
 
+- A bug that caused the :doc:`Exception handler <../general/errors>` to display
+  incorrect error view file corresponding to the exception code has been fixed.
+  The third parameter ``int $statusCode = 500`` has been added to
+  ``CodeIgniter\Debug\ExceptionHandler::determineView()`` for this purpose.
+
 ***************
 Message Changes
 ***************

user_guide_src/source/database/metadata.rst

@@ -51,14 +51,14 @@ $db->getFieldNames()
 Returns an array containing the field names. This query can be called
 two ways:
 
-1. You can supply the table name and call it from the ``$db->object``:
+1. You can supply the table name and call it from the ``$db`` object:
 
-   .. literalinclude:: metadata/003.php
+    .. literalinclude:: metadata/003.php
 
 2. You can gather the field names associated with any query you run by
-calling the function from your query result object:
+   calling the function from your query result object:
 
-.. literalinclude:: metadata/004.php
+    .. literalinclude:: metadata/004.php
 
 Determine If a Field is Present in a Table
 ==========================================

user_guide_src/source/database/transactions.rst

@@ -67,11 +67,11 @@ Strict Mode can be disabled as follows:
 Managing Errors
 ===============
 
-When you have ``DBDebug`` true in your **app/Config/Database.php** file,
-if a query error occurs, all the queries will be rolled backed, and an exception
-will be thrown. So you'll see a standard error page.
+.. note::
+    Since v4.3.0, during transactions, exceptions are not thrown by default
+    even if ``DBDebug`` is true.
 
-If the ``DBDebug`` is false, you can manage your own errors like this:
+You can manage your own errors like this:
 
 .. literalinclude:: transactions/003.php
 

user_guide_src/source/general/errors.rst

@@ -19,20 +19,29 @@ Using Exceptions
 
 This section is a quick overview for newer programmers, or for developers who are not experienced with using exceptions.
 
+What is Exceptions
+------------------
+
 Exceptions are simply events that happen when the exception is "thrown". This halts the current flow of the script, and
 execution is then sent to the error handler which displays the appropriate error page:
 
 .. literalinclude:: errors/001.php
 
+Catching Exceptions
+-------------------
+
 If you are calling a method that might throw an exception, you can catch that exception using a ``try/catch`` block:
 
 .. literalinclude:: errors/002.php
 
 If the ``$userModel`` throws an exception, it is caught and the code within the catch block is executed. In this example,
 the scripts dies, echoing the error message that the ``UserModel`` defined.
 
+Catching Specific Exceptions
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
 In the example above, we catch any type of Exception. If we only want to watch for specific types of exceptions, like
-a ``UnknownFileException``, we can specify that in the catch parameter. Any other exceptions that are thrown and are
+a ``DataException``, we can specify that in the catch parameter. Any other exceptions that are thrown and are
 not child classes of the caught exception will be passed on to the error handler:
 
 .. literalinclude:: errors/003.php
@@ -65,7 +74,7 @@ See :ref:`setting-environment`.
 Logging Exceptions
 ------------------
 
-By default, all Exceptions other than 404 - Page Not Found exceptions are logged. This can be turned on and off
+By default, all Exceptions other than "404 - Page Not Found" exceptions are logged. This can be turned on and off
 by setting the ``$log`` value of **app/Config/Exceptions.php**:
 
 .. literalinclude:: errors/005.php
@@ -74,8 +83,40 @@ To ignore logging on other status codes, you can set the status code to ignore i
 
 .. literalinclude:: errors/006.php
 
-.. note:: It is possible that logging still will not happen for exceptions if your current Log settings
-    are not set up to log **critical** errors, which all exceptions are logged as.
+.. note:: It is possible that logging still will not happen for exceptions if your current
+    :ref:`Log settings <logging-configuration>`
+    are not set up to log ``critical`` errors, which all exceptions are logged as.
+
+.. _logging_deprecation_warnings:
+
+Logging Deprecation Warnings
+----------------------------
+
+.. versionadded:: 4.3.0
+
+By default, all errors reported by ``error_reporting()`` will be thrown as an ``ErrorException`` object. These
+include both ``E_DEPRECATED`` and ``E_USER_DEPRECATED`` errors. With the surge in use of PHP 8.1+, many users
+may see exceptions thrown for `passing null to non-nullable arguments of internal functions <https://wiki.php.net/rfc/deprecate_null_to_scalar_internal_arg>`_.
+To ease the migration to PHP 8.1, you can instruct CodeIgniter to log the deprecations instead of throwing them.
+
+First, make sure your copy of ``Config\Exceptions`` is updated with the two new properties and set as follows:
+
+.. literalinclude:: errors/012.php
+
+Next, depending on the log level you set in ``Config\Exceptions::$deprecationLogLevel``, check whether the
+logger threshold defined in ``Config\Logger::$threshold`` covers the deprecation log level. If not, adjust
+it accordingly.
+
+.. literalinclude:: errors/013.php
+
+After that, subsequent deprecations will be logged instead of thrown.
+
+This feature also works with user deprecations:
+
+.. literalinclude:: errors/014.php
+
+For testing your application you may want to always throw on deprecations. You may configure this by
+setting the environment variable ``CODEIGNITER_SCREAM_DEPRECATIONS`` to a truthy value.
 
 Framework Exceptions
 ====================
@@ -85,15 +126,17 @@ The following framework exceptions are available:
 PageNotFoundException
 ---------------------
 
-This is used to signal a 404, Page Not Found error. When thrown, the system will show the view found at
-**app/Views/errors/html/error_404.php**. You should customize all of the error views for your site.
-If, in **app/Config/Routes.php**, you have specified a 404 Override, that will be called instead of the standard
-404 page:
+This is used to signal a 404, Page Not Found error:
 
 .. literalinclude:: errors/007.php
 
 You can pass a message into the exception that will be displayed in place of the default message on the 404 page.
 
+For the default 404 view file location, see :ref:`http-status-code-and-error-views`.
+
+If, in **app/Config/Routing.php** or **app/Config/Routes.php**, you have specified
+a :ref:`404-override`, that will be called instead of the standard 404 page.
+
 ConfigException
 ---------------
 
@@ -144,52 +187,52 @@ Specify HTTP Status Code in Your Exception
 .. versionadded:: 4.3.0
 
 Since v4.3.0, you can specify the HTTP status code for your Exception class to implement
-``HTTPExceptionInterface``.
+``CodeIgniter\Exceptions\HTTPExceptionInterface``.
 
 When an exception implementing ``HTTPExceptionInterface`` is caught by CodeIgniter's exception handler, the Exception code will become the HTTP status code.
 
-.. _error-specify-exit-code:
+.. _http-status-code-and-error-views:
 
-Specify Exit Code in Your Exception
-===================================
+HTTP Status Code and Error Views
+================================
 
-.. versionadded:: 4.3.0
+The exception handler displays the error view corresponding to the HTTP status
+code, if one exists.
 
-Since v4.3.0, you can specify the exit code for your Exception class to implement
-``HasExitCodeInterface``.
-
-When an exception implementing ``HasExitCodeInterface`` is caught by CodeIgniter's exception handler, the code returned from the ``getExitCode()`` method will become the exit code.
+For example, ``PageNotFoundException`` implements the ``HTTPExceptionInterface``,
+so its exception code ``404`` will be the HTTP status code. Therefore if it is
+thrown, the system will show the **error_404.php** in the **app/Views/errors/html**
+folder when it is a web request. If it is invoked via CLI, the system will show
+the **error_404.php** in the **app/Views/errors/cli** folder.
 
-.. _logging_deprecation_warnings:
+If there is no view file corresponding to the HTTP status code, **production.php**
+or **error_exception.php** will be displayed.
 
-Logging Deprecation Warnings
-============================
-
-.. versionadded:: 4.3.0
-
-By default, all errors reported by ``error_reporting()`` will be thrown as an ``ErrorException`` object. These
-include both ``E_DEPRECATED`` and ``E_USER_DEPRECATED`` errors. With the surge in use of PHP 8.1+, many users
-may see exceptions thrown for `passing null to non-nullable arguments of internal functions <https://wiki.php.net/rfc/deprecate_null_to_scalar_internal_arg>`_.
-To ease the migration to PHP 8.1, you can instruct CodeIgniter to log the deprecations instead of throwing them.
+.. note:: If ``display_errors`` is on in the PHP INI configuration,
+    **error_exception.php** is selected and a detailed error report is displayed.
 
-First, make sure your copy of ``Config\Exceptions`` is updated with the two new properties and set as follows:
+You should customize all of the error views in the **app/Views/errors/html** folder
+for your site.
 
-.. literalinclude:: errors/012.php
+You can also create error views for specific HTTP status code. For example, if
+you want to create an error view for "400 Bad Request", add **error_400.php**.
 
-Next, depending on the log level you set in ``Config\Exceptions::$deprecationLogLevel``, check whether the
-logger threshold defined in ``Config\Logger::$threshold`` covers the deprecation log level. If not, adjust
-it accordingly.
+.. warning:: If an error view file with the corresponding HTTP status code exists,
+    the exception handler will display that file regardless of the environment.
+    The view file must be implemented in such a way that it does not display
+    detailed error messages in production environment by yourself.
 
-.. literalinclude:: errors/013.php
+.. _error-specify-exit-code:
 
-After that, subsequent deprecations will be logged instead of thrown.
+Specify Exit Code in Your Exception
+===================================
 
-This feature also works with user deprecations:
+.. versionadded:: 4.3.0
 
-.. literalinclude:: errors/014.php
+Since v4.3.0, you can specify the exit code for your Exception class to implement
+``CodeIgniter\Exceptions\HasExitCodeInterface``.
 
-For testing your application you may want to always throw on deprecations. You may configure this by
-setting the environment variable ``CODEIGNITER_SCREAM_DEPRECATIONS`` to a truthy value.
+When an exception implementing ``HasExitCodeInterface`` is caught by CodeIgniter's exception handler, the code returned from the ``getExitCode()`` method will become the exit code.
 
 .. _custom-exception-handlers:
 

user_guide_src/source/general/errors/003.php

@@ -1,7 +1,9 @@
 <?php
 
+use CodeIgniter\Database\Exceptions\DataException;
+
 try {
     $user = $userModel->find($id);
-} catch (\CodeIgniter\UnknownFileException $e) {
+} catch (DataException $e) {
     // do something here...
 }

user_guide_src/source/general/errors/004.php

@@ -1,8 +1,10 @@
 <?php
 
+use CodeIgniter\Database\Exceptions\DataException;
+
 try {
     $user = $userModel->find($id);
-} catch (\CodeIgniter\UnknownFileException $e) {
+} catch (DataException $e) {
     // do something here...
 
     throw new \RuntimeException($e->getMessage(), $e->getCode(), $e);

user_guide_src/source/general/errors/005.php

@@ -6,5 +6,7 @@
 
 class Exceptions extends BaseConfig
 {
-    public $log = true;
+    // ...
+    public bool $log = true;
+    // ...
 }

user_guide_src/source/general/errors/006.php

@@ -6,5 +6,7 @@
 
 class Exceptions extends BaseConfig
 {
-    public $ignoredCodes = [404];
+    // ...
+    public array $ignoreCodes = [404];
+    // ...
 }