Merge pull request #8866 from kenjis/fix-ug-logging-deprecation

docs: update "Logging Deprecation Warnings" description

Author: kenjis

app/Config/Exceptions.php

@@ -60,12 +60,10 @@ class Exceptions extends BaseConfig
 
     /**
      * --------------------------------------------------------------------------
-     * LOG DEPRECATIONS INSTEAD OF THROWING?
+     * WHETHER TO THROW AN EXCEPTION ON DEPRECATED ERRORS
      * --------------------------------------------------------------------------
-     * By default, CodeIgniter converts deprecations into exceptions. Also,
-     * starting in PHP 8.1 will cause a lot of deprecated usage warnings.
-     * Use this option to temporarily cease the warnings and instead log those.
-     * This option also works for user deprecations.
+     * If set to `true`, DEPRECATED errors are only logged and no exceptions are
+     * thrown. This option also works for user deprecations.
      */
     public bool $logDeprecations = true;
 

user_guide_src/source/general/errors.rst

@@ -94,12 +94,26 @@ 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.
+Prior to v4.3.0, all errors reported by ``error_reporting()`` will be thrown as
+an ``ErrorException`` object.
 
-First, make sure your copy of ``Config\Exceptions`` is updated with the two new properties and set as follows:
+But 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, starting with v4.3.0, CodeIgniter has the feature
+that only logs the deprecation errors (``E_DEPRECATED`` and ``E_USER_DEPRECATED``)
+without throwing them as exceptions.
+
+By default, CodeIgniter will only log deprecations without throwing exceptions in
+development environment. In production environment, no logging is done and no
+exceptions are thrown.
+
+Configuration
+^^^^^^^^^^^^^
+
+The settings for this feature are as follows.
+First, make sure your copy of ``Config\Exceptions`` is updated with the two new
+properties and set as follows:
 
 .. literalinclude:: errors/012.php
 
@@ -109,7 +123,8 @@ it accordingly.
 
 .. literalinclude:: errors/013.php
 
-After that, subsequent deprecations will be logged instead of thrown.
+After that, subsequent deprecations will be logged as configured without throwing
+as exceptions.
 
 This feature also works with user deprecations:
 

user_guide_src/source/general/errors/012.php

@@ -7,8 +7,9 @@
 
 class Exceptions extends BaseConfig
 {
-    // ... other properties
-
-    public bool $logDeprecations       = true;
-    public string $deprecationLogLevel = LogLevel::WARNING; // this should be one of the log levels supported by PSR-3
+    // ...
+    public bool $logDeprecations = true; // If set to false, an exception will be thrown.
+    // ...
+    public string $deprecationLogLevel = LogLevel::WARNING; // This should be one of the log levels supported by PSR-3.
+    // ...
 }

user_guide_src/source/general/errors/013.php

@@ -6,7 +6,8 @@
 
 class Logger extends BaseConfig
 {
-    // .. other properties
-
-    public $threshold = 5; // originally 4 but changed to 5 to log the warnings from the deprecations
+    // ...
+    // This must contain the log level (5 for LogLevel::WARNING) corresponding to $deprecationLogLevel.
+    public $threshold = (ENVIRONMENT === 'production') ? 4 : 9;
+    // ...
 }