feat: Opt-in logging of deprecations

app/Config/Exceptions.php

@@ -3,6 +3,7 @@
 namespace Config;
 
 use CodeIgniter\Config\BaseConfig;
+use Psr\Log\LogLevel;
 
 /**
  * Setup how the exception handler works.
@@ -49,4 +50,28 @@ class Exceptions extends BaseConfig
  * ex. ['server', 'setup/password', 'secret_token']
  */
  public array $sensitiveDataInTrace = [];
+
+ /**
+ * --------------------------------------------------------------------------
+ * LOG DEPRECATIONS INSTEAD OF THROWING?
+ * --------------------------------------------------------------------------
+ * 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.
+ */
+ public bool $logDeprecationsOnly = false;
+
+ /**
+ * --------------------------------------------------------------------------
+ * LOG LEVEL THRESHOLD FOR DEPRECATIONS
+ * --------------------------------------------------------------------------
+ * If `$logDeprecationsOnly` is set to `true`, this sets the log level
+ * to which the deprecation will be logged. This should be one of the log
+ * levels recognized by PSR-3.
+ *
+ * The related `Config\Logger::$threshold` should be adjusted, if needed,
+ * to capture logging the deprecations.
+ */
+ public string $deprecationLogLevel = LogLevel::WARNING;
 }

system/Debug/Exceptions.php

@@ -22,6 +22,7 @@
 use Config\Exceptions as ExceptionsConfig;
 use Config\Paths;
 use ErrorException;
+use Psr\Log\LogLevel;
 use Throwable;
 
 /**
@@ -82,6 +83,10 @@ public function __construct(ExceptionsConfig $config, $request, ResponseInterfac
  if (! isset($this->config->sensitiveDataInTrace)) {
  $this->config->sensitiveDataInTrace = [];
  }
+ if (! isset($this->config->logDeprecationsOnly, $this->config->deprecationLogLevel)) {
+ $this->config->logDeprecationsOnly = false;
+ $this->config->deprecationLogLevel = LogLevel::WARNING;
+ }
  }
 
  /**
@@ -155,6 +160,10 @@ public function exceptionHandler(Throwable $exception)
  */
  public function errorHandler(int $severity, string $message, ?string $file = null, ?int $line = null)
  {
+ if ($this->isDeprecationError($severity) && $this->config->logDeprecationsOnly) {
+ return $this->handleDeprecationError($message, $file, $line);
+ }
+
  if (! (error_reporting() & $severity)) {
  return;
  }
@@ -328,6 +337,37 @@ protected function determineCodes(Throwable $exception): array
  return [$statusCode, $exitStatus];
  }
 
+ private function isDeprecationError(int $error): bool
+ {
+ $deprecations = E_DEPRECATED | E_USER_DEPRECATED;
+
+ return ($error & $deprecations) !== 0;
+ }
+
+ /**
+ * @noRector \Rector\DeadCode\Rector\ClassMethod\RemoveUselessReturnTagRector
+ *
+ * @return true
+ */
+ private function handleDeprecationError(string $message, ?string $file = null, ?int $line = null): bool
+ {
+ // Remove the trace of the error handler.
+ $trace = array_slice(debug_backtrace(), 2);
+
+ log_message(
+ $this->config->deprecationLogLevel,
+ "[DEPRECATED] {message} in {errFile} on line {errLine}.\n{trace}",
+ [
+ 'message' => $message,
+ 'errFile' => clean_path($file ?? ''),
+ 'errLine' => $line ?? 0,
+ 'trace' => self::renderBacktrace($trace),
+ ]
+ );
+
+ return true;
+ }
+
  // --------------------------------------------------------------------
  // Display Methods
  // --------------------------------------------------------------------

tests/system/Debug/ExceptionsTest.php

@@ -19,6 +19,7 @@
 use CodeIgniter\Test\ReflectionHelper;
 use Config\Exceptions as ExceptionsConfig;
 use Config\Services;
+use ErrorException;
 use RuntimeException;
 
 /**
@@ -32,9 +33,55 @@ final class ExceptionsTest extends CIUnitTestCase
 
  protected function setUp(): void
  {
+ parent::setUp();
+
  $this->exception = new Exceptions(new ExceptionsConfig(), Services::request(), Services::response());
  }
 
+ /**
+ * @requires PHP >= 8.1
+ */
+ public function testDeprecationsOnPhp81DoNotThrow(): void
+ {
+ $config = new ExceptionsConfig();
+
+ $config->logDeprecationsOnly = true;
+ $config->deprecationLogLevel = 'error';
+
+ $this->exception = new Exceptions($config, Services::request(), Services::response());
+ $this->exception->initialize();
+
+ // this is only needed for IDEs not to complain that strlen does not accept explicit null
+ $maybeNull = PHP_VERSION_ID >= 80100 ? null : 'random string';
+
+ try {
+ strlen($maybeNull);
+ $this->assertLogContains('error', '[DEPRECATED] strlen(): ');
+ } catch (ErrorException $e) {
+ $this->fail('The catch block should not be reached.');
+ } finally {
+ restore_error_handler();
+ restore_exception_handler();
+ }
+ }
+
+ public function testSuppressedDeprecationsAreLogged(): void
+ {
+ $config = new ExceptionsConfig();
+
+ $config->logDeprecationsOnly = true;
+ $config->deprecationLogLevel = 'error';
+
+ $this->exception = new Exceptions($config, Services::request(), Services::response());
+ $this->exception->initialize();
+
+ @trigger_error('Hello! I am a deprecation!', E_USER_DEPRECATED);
+ $this->assertLogContains('error', '[DEPRECATED] Hello! I am a deprecation!');
+
+ restore_error_handler();
+ restore_exception_handler();
+ }
+
  public function testDetermineViews(): void
  {
  $determineView = $this->getPrivateMethodInvoker($this->exception, 'determineView');

user_guide_src/source/changelogs/v4.3.0.rst

@@ -176,6 +176,11 @@ Helpers and Functions
 - Added :php:func:`request()` and :php:func:`response()` functions.
 - Add :php:func:`decamelize()` function to convert camelCase to snake_case.
 
+Error Handling
+==============
+
+- You can now log deprecation errors instead of throwing them. See :ref:`logging_deprecation_errors` for details.
+
 Others
 ======
 

user_guide_src/source/general/errors.rst

@@ -133,3 +133,31 @@ Since v4.3.0, you can specify the exit code for your Exception class to implemen
 ``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.
+
+.. _logging_deprecation_errors:
+
+Logging Deprecation Errors
+==========================
+
+.. 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

user_guide_src/source/general/errors/012.php

@@ -0,0 +1,14 @@
+<?php
+
+namespace Config;
+
+use CodeIgniter\Config\BaseConfig;
+use Psr\Log\LogLevel;
+
+class Exceptions extends BaseConfig
+{
+ // ... other properties
+
+ public bool $logDeprecationsOnly = true;
+ 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

@@ -0,0 +1,12 @@
+<?php
+
+namespace Config;
+
+use CodeIgniter\Config\BaseConfig;
+
+class Logger extends BaseConfig
+{
+ // .. other properties
+
+ public $threshold = 5; // originally 4 but changed to 5 to log the warnings from the deprecations
+}

user_guide_src/source/general/errors/014.php

@@ -0,0 +1,4 @@
+<?php
+
+@trigger_error('Do not use this class!', E_USER_DEPRECATED);
+// Your logs should contain a record with a message like: "[DEPRECATED] Do not use this class!"

app/Config/Exceptions.php

@@ -3,6 +3,7 @@
 namespace Config;
 
 use CodeIgniter\Config\BaseConfig;
+use Psr\Log\LogLevel;
 
 /**
  * Setup how the exception handler works.
@@ -49,4 +50,28 @@ class Exceptions extends BaseConfig
  * ex. ['server', 'setup/password', 'secret_token']
  */
  public array $sensitiveDataInTrace = [];
+
+ /**
+ * --------------------------------------------------------------------------
+ * LOG DEPRECATIONS INSTEAD OF THROWING?
+ * --------------------------------------------------------------------------
+ * 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.
+ */
+ public bool $logDeprecationsOnly = false;
+
+ /**
+ * --------------------------------------------------------------------------
+ * LOG LEVEL THRESHOLD FOR DEPRECATIONS
+ * --------------------------------------------------------------------------
+ * If `$logDeprecationsOnly` is set to `true`, this sets the log level
+ * to which the deprecation will be logged. This should be one of the log
+ * levels recognized by PSR-3.
+ *
+ * The related `Config\Logger::$threshold` should be adjusted, if needed,
+ * to capture logging the deprecations.
+ */
+ public string $deprecationLogLevel = LogLevel::WARNING;
 }

system/Debug/Exceptions.php

@@ -22,6 +22,7 @@
 use Config\Exceptions as ExceptionsConfig;
 use Config\Paths;
 use ErrorException;
+use Psr\Log\LogLevel;
 use Throwable;
 
 /**
@@ -82,6 +83,10 @@ public function __construct(ExceptionsConfig $config, $request, ResponseInterfac
  if (! isset($this->config->sensitiveDataInTrace)) {
  $this->config->sensitiveDataInTrace = [];
  }
+ if (! isset($this->config->logDeprecationsOnly, $this->config->deprecationLogLevel)) {
+ $this->config->logDeprecationsOnly = false;
+ $this->config->deprecationLogLevel = LogLevel::WARNING;
+ }
  }
 
  /**
@@ -155,6 +160,10 @@ public function exceptionHandler(Throwable $exception)
  */
  public function errorHandler(int $severity, string $message, ?string $file = null, ?int $line = null)
  {
+ if ($this->isDeprecationError($severity) && $this->config->logDeprecationsOnly) {
+ return $this->handleDeprecationError($message, $file, $line);
+ }
+
  if (! (error_reporting() & $severity)) {
  return;
  }
@@ -328,6 +337,37 @@ protected function determineCodes(Throwable $exception): array
  return [$statusCode, $exitStatus];
  }
 
+ private function isDeprecationError(int $error): bool
+ {
+ $deprecations = E_DEPRECATED | E_USER_DEPRECATED;
+
+ return ($error & $deprecations) !== 0;
+ }
+
+ /**
+ * @noRector \Rector\DeadCode\Rector\ClassMethod\RemoveUselessReturnTagRector
+ *
+ * @return true
+ */
+ private function handleDeprecationError(string $message, ?string $file = null, ?int $line = null): bool
+ {
+ // Remove the trace of the error handler.
+ $trace = array_slice(debug_backtrace(), 2);
+
+ log_message(
+ $this->config->deprecationLogLevel,
+ "[DEPRECATED] {message} in {errFile} on line {errLine}.\n{trace}",
+ [
+ 'message' => $message,
+ 'errFile' => clean_path($file ?? ''),
+ 'errLine' => $line ?? 0,
+ 'trace' => self::renderBacktrace($trace),
+ ]
+ );
+
+ return true;
+ }
+
  // --------------------------------------------------------------------
  // Display Methods
  // --------------------------------------------------------------------

tests/system/Debug/ExceptionsTest.php

@@ -19,6 +19,7 @@
 use CodeIgniter\Test\ReflectionHelper;
 use Config\Exceptions as ExceptionsConfig;
 use Config\Services;
+use ErrorException;
 use RuntimeException;
 
 /**
@@ -32,9 +33,55 @@ final class ExceptionsTest extends CIUnitTestCase
 
  protected function setUp(): void
  {
+ parent::setUp();
+
  $this->exception = new Exceptions(new ExceptionsConfig(), Services::request(), Services::response());
  }
 
+ /**
+ * @requires PHP >= 8.1
+ */
+ public function testDeprecationsOnPhp81DoNotThrow(): void
+ {
+ $config = new ExceptionsConfig();
+
+ $config->logDeprecationsOnly = true;
+ $config->deprecationLogLevel = 'error';
+
+ $this->exception = new Exceptions($config, Services::request(), Services::response());
+ $this->exception->initialize();
+
+ // this is only needed for IDEs not to complain that strlen does not accept explicit null
+ $maybeNull = PHP_VERSION_ID >= 80100 ? null : 'random string';
+
+ try {
+ strlen($maybeNull);
+ $this->assertLogContains('error', '[DEPRECATED] strlen(): ');
+ } catch (ErrorException $e) {
+ $this->fail('The catch block should not be reached.');
+ } finally {
+ restore_error_handler();
+ restore_exception_handler();
+ }
+ }
+
+ public function testSuppressedDeprecationsAreLogged(): void
+ {
+ $config = new ExceptionsConfig();
+
+ $config->logDeprecationsOnly = true;
+ $config->deprecationLogLevel = 'error';
+
+ $this->exception = new Exceptions($config, Services::request(), Services::response());
+ $this->exception->initialize();
+
+ @trigger_error('Hello! I am a deprecation!', E_USER_DEPRECATED);
+ $this->assertLogContains('error', '[DEPRECATED] Hello! I am a deprecation!');
+
+ restore_error_handler();
+ restore_exception_handler();
+ }
+
  public function testDetermineViews(): void
  {
  $determineView = $this->getPrivateMethodInvoker($this->exception, 'determineView');

user_guide_src/source/changelogs/v4.3.0.rst

@@ -176,6 +176,11 @@ Helpers and Functions
 - Added :php:func:`request()` and :php:func:`response()` functions.
 - Add :php:func:`decamelize()` function to convert camelCase to snake_case.
 
+Error Handling
+==============
+
+- You can now log deprecation errors instead of throwing them. See :ref:`logging_deprecation_errors` for details.
+
 Others
 ======
 

user_guide_src/source/general/errors.rst

@@ -133,3 +133,31 @@ Since v4.3.0, you can specify the exit code for your Exception class to implemen
 ``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.
+
+.. _logging_deprecation_errors:
+
+Logging Deprecation Errors
+==========================
+
+.. 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

user_guide_src/source/general/errors/012.php

@@ -0,0 +1,14 @@
+<?php
+
+namespace Config;
+
+use CodeIgniter\Config\BaseConfig;
+use Psr\Log\LogLevel;
+
+class Exceptions extends BaseConfig
+{
+ // ... other properties
+
+ public bool $logDeprecationsOnly = true;
+ 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

@@ -0,0 +1,12 @@
+<?php
+
+namespace Config;
+
+use CodeIgniter\Config\BaseConfig;
+
+class Logger extends BaseConfig
+{
+ // .. other properties
+
+ public $threshold = 5; // originally 4 but changed to 5 to log the warnings from the deprecations
+}

user_guide_src/source/general/errors/014.php

@@ -0,0 +1,4 @@
+<?php
+
+@trigger_error('Do not use this class!', E_USER_DEPRECATED);
+// Your logs should contain a record with a message like: "[DEPRECATED] Do not use this class!"

app/Config/Exceptions.php

@@ -3,6 +3,7 @@
 namespace Config;
 
 use CodeIgniter\Config\BaseConfig;
+use Psr\Log\LogLevel;
 
 /**
  * Setup how the exception handler works.
@@ -49,4 +50,28 @@ class Exceptions extends BaseConfig
  * ex. ['server', 'setup/password', 'secret_token']
  */
  public array $sensitiveDataInTrace = [];
+
+ /**
+ * --------------------------------------------------------------------------
+ * LOG DEPRECATIONS INSTEAD OF THROWING?
+ * --------------------------------------------------------------------------
+ * 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.
+ */
+ public bool $logDeprecationsOnly = false;
+
+ /**
+ * --------------------------------------------------------------------------
+ * LOG LEVEL THRESHOLD FOR DEPRECATIONS
+ * --------------------------------------------------------------------------
+ * If `$logDeprecationsOnly` is set to `true`, this sets the log level
+ * to which the deprecation will be logged. This should be one of the log
+ * levels recognized by PSR-3.
+ *
+ * The related `Config\Logger::$threshold` should be adjusted, if needed,
+ * to capture logging the deprecations.
+ */
+ public string $deprecationLogLevel = LogLevel::WARNING;
 }

system/Debug/Exceptions.php

@@ -22,6 +22,7 @@
 use Config\Exceptions as ExceptionsConfig;
 use Config\Paths;
 use ErrorException;
+use Psr\Log\LogLevel;
 use Throwable;
 
 /**
@@ -82,6 +83,10 @@ public function __construct(ExceptionsConfig $config, $request, ResponseInterfac
  if (! isset($this->config->sensitiveDataInTrace)) {
  $this->config->sensitiveDataInTrace = [];
  }
+ if (! isset($this->config->logDeprecationsOnly, $this->config->deprecationLogLevel)) {
+ $this->config->logDeprecationsOnly = false;
+ $this->config->deprecationLogLevel = LogLevel::WARNING;
+ }
  }
 
  /**
@@ -155,6 +160,10 @@ public function exceptionHandler(Throwable $exception)
  */
  public function errorHandler(int $severity, string $message, ?string $file = null, ?int $line = null)
  {
+ if ($this->isDeprecationError($severity) && $this->config->logDeprecationsOnly) {
+ return $this->handleDeprecationError($message, $file, $line);
+ }
+
  if (! (error_reporting() & $severity)) {
  return;
  }
@@ -328,6 +337,37 @@ protected function determineCodes(Throwable $exception): array
  return [$statusCode, $exitStatus];
  }
 
+ private function isDeprecationError(int $error): bool
+ {
+ $deprecations = E_DEPRECATED | E_USER_DEPRECATED;
+
+ return ($error & $deprecations) !== 0;
+ }
+
+ /**
+ * @noRector \Rector\DeadCode\Rector\ClassMethod\RemoveUselessReturnTagRector
+ *
+ * @return true
+ */
+ private function handleDeprecationError(string $message, ?string $file = null, ?int $line = null): bool
+ {
+ // Remove the trace of the error handler.
+ $trace = array_slice(debug_backtrace(), 2);
+
+ log_message(
+ $this->config->deprecationLogLevel,
+ "[DEPRECATED] {message} in {errFile} on line {errLine}.\n{trace}",
+ [
+ 'message' => $message,
+ 'errFile' => clean_path($file ?? ''),
+ 'errLine' => $line ?? 0,
+ 'trace' => self::renderBacktrace($trace),
+ ]
+ );
+
+ return true;
+ }
+
  // --------------------------------------------------------------------
  // Display Methods
  // --------------------------------------------------------------------

tests/system/Debug/ExceptionsTest.php

@@ -19,6 +19,7 @@
 use CodeIgniter\Test\ReflectionHelper;
 use Config\Exceptions as ExceptionsConfig;
 use Config\Services;
+use ErrorException;
 use RuntimeException;
 
 /**
@@ -32,9 +33,55 @@ final class ExceptionsTest extends CIUnitTestCase
 
  protected function setUp(): void
  {
+ parent::setUp();
+
  $this->exception = new Exceptions(new ExceptionsConfig(), Services::request(), Services::response());
  }
 
+ /**
+ * @requires PHP >= 8.1
+ */
+ public function testDeprecationsOnPhp81DoNotThrow(): void
+ {
+ $config = new ExceptionsConfig();
+
+ $config->logDeprecationsOnly = true;
+ $config->deprecationLogLevel = 'error';
+
+ $this->exception = new Exceptions($config, Services::request(), Services::response());
+ $this->exception->initialize();
+
+ // this is only needed for IDEs not to complain that strlen does not accept explicit null
+ $maybeNull = PHP_VERSION_ID >= 80100 ? null : 'random string';
+
+ try {
+ strlen($maybeNull);
+ $this->assertLogContains('error', '[DEPRECATED] strlen(): ');
+ } catch (ErrorException $e) {
+ $this->fail('The catch block should not be reached.');
+ } finally {
+ restore_error_handler();
+ restore_exception_handler();
+ }
+ }
+
+ public function testSuppressedDeprecationsAreLogged(): void
+ {
+ $config = new ExceptionsConfig();
+
+ $config->logDeprecationsOnly = true;
+ $config->deprecationLogLevel = 'error';
+
+ $this->exception = new Exceptions($config, Services::request(), Services::response());
+ $this->exception->initialize();
+
+ @trigger_error('Hello! I am a deprecation!', E_USER_DEPRECATED);
+ $this->assertLogContains('error', '[DEPRECATED] Hello! I am a deprecation!');
+
+ restore_error_handler();
+ restore_exception_handler();
+ }
+
  public function testDetermineViews(): void
  {
  $determineView = $this->getPrivateMethodInvoker($this->exception, 'determineView');

user_guide_src/source/changelogs/v4.3.0.rst

@@ -176,6 +176,11 @@ Helpers and Functions
 - Added :php:func:`request()` and :php:func:`response()` functions.
 - Add :php:func:`decamelize()` function to convert camelCase to snake_case.
 
+Error Handling
+==============
+
+- You can now log deprecation errors instead of throwing them. See :ref:`logging_deprecation_errors` for details.
+
 Others
 ======
 

user_guide_src/source/general/errors.rst

@@ -133,3 +133,31 @@ Since v4.3.0, you can specify the exit code for your Exception class to implemen
 ``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.
+
+.. _logging_deprecation_errors:
+
+Logging Deprecation Errors
+==========================
+
+.. 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

user_guide_src/source/general/errors/012.php

@@ -0,0 +1,14 @@
+<?php
+
+namespace Config;
+
+use CodeIgniter\Config\BaseConfig;
+use Psr\Log\LogLevel;
+
+class Exceptions extends BaseConfig
+{
+ // ... other properties
+
+ public bool $logDeprecationsOnly = true;
+ 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

@@ -0,0 +1,12 @@
+<?php
+
+namespace Config;
+
+use CodeIgniter\Config\BaseConfig;
+
+class Logger extends BaseConfig
+{
+ // .. other properties
+
+ public $threshold = 5; // originally 4 but changed to 5 to log the warnings from the deprecations
+}

user_guide_src/source/general/errors/014.php

@@ -0,0 +1,4 @@
+<?php
+
+@trigger_error('Do not use this class!', E_USER_DEPRECATED);
+// Your logs should contain a record with a message like: "[DEPRECATED] Do not use this class!"

app/Config/Exceptions.php

@@ -3,6 +3,7 @@
 namespace Config;
 
 use CodeIgniter\Config\BaseConfig;
+use Psr\Log\LogLevel;
 
 /**
  * Setup how the exception handler works.
@@ -49,4 +50,28 @@ class Exceptions extends BaseConfig
  * ex. ['server', 'setup/password', 'secret_token']
  */
  public array $sensitiveDataInTrace = [];
+
+ /**
+ * --------------------------------------------------------------------------
+ * LOG DEPRECATIONS INSTEAD OF THROWING?
+ * --------------------------------------------------------------------------
+ * 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.
+ */
+ public bool $logDeprecationsOnly = false;
+
+ /**
+ * --------------------------------------------------------------------------
+ * LOG LEVEL THRESHOLD FOR DEPRECATIONS
+ * --------------------------------------------------------------------------
+ * If `$logDeprecationsOnly` is set to `true`, this sets the log level
+ * to which the deprecation will be logged. This should be one of the log
+ * levels recognized by PSR-3.
+ *
+ * The related `Config\Logger::$threshold` should be adjusted, if needed,
+ * to capture logging the deprecations.
+ */
+ public string $deprecationLogLevel = LogLevel::WARNING;
 }

system/Debug/Exceptions.php

@@ -22,6 +22,7 @@
 use Config\Exceptions as ExceptionsConfig;
 use Config\Paths;
 use ErrorException;
+use Psr\Log\LogLevel;
 use Throwable;
 
 /**
@@ -82,6 +83,10 @@ public function __construct(ExceptionsConfig $config, $request, ResponseInterfac
  if (! isset($this->config->sensitiveDataInTrace)) {
  $this->config->sensitiveDataInTrace = [];
  }
+ if (! isset($this->config->logDeprecationsOnly, $this->config->deprecationLogLevel)) {
+ $this->config->logDeprecationsOnly = false;
+ $this->config->deprecationLogLevel = LogLevel::WARNING;
+ }
  }
 
  /**
@@ -155,6 +160,10 @@ public function exceptionHandler(Throwable $exception)
  */
  public function errorHandler(int $severity, string $message, ?string $file = null, ?int $line = null)
  {
+ if ($this->isDeprecationError($severity) && $this->config->logDeprecationsOnly) {
+ return $this->handleDeprecationError($message, $file, $line);
+ }
+
  if (! (error_reporting() & $severity)) {
  return;
  }
@@ -328,6 +337,37 @@ protected function determineCodes(Throwable $exception): array
  return [$statusCode, $exitStatus];
  }
 
+ private function isDeprecationError(int $error): bool
+ {
+ $deprecations = E_DEPRECATED | E_USER_DEPRECATED;
+
+ return ($error & $deprecations) !== 0;
+ }
+
+ /**
+ * @noRector \Rector\DeadCode\Rector\ClassMethod\RemoveUselessReturnTagRector
+ *
+ * @return true
+ */
+ private function handleDeprecationError(string $message, ?string $file = null, ?int $line = null): bool
+ {
+ // Remove the trace of the error handler.
+ $trace = array_slice(debug_backtrace(), 2);
+
+ log_message(
+ $this->config->deprecationLogLevel,
+ "[DEPRECATED] {message} in {errFile} on line {errLine}.\n{trace}",
+ [
+ 'message' => $message,
+ 'errFile' => clean_path($file ?? ''),
+ 'errLine' => $line ?? 0,
+ 'trace' => self::renderBacktrace($trace),
+ ]
+ );
+
+ return true;
+ }
+
  // --------------------------------------------------------------------
  // Display Methods
  // --------------------------------------------------------------------

tests/system/Debug/ExceptionsTest.php

@@ -19,6 +19,7 @@
 use CodeIgniter\Test\ReflectionHelper;
 use Config\Exceptions as ExceptionsConfig;
 use Config\Services;
+use ErrorException;
 use RuntimeException;
 
 /**
@@ -32,9 +33,55 @@ final class ExceptionsTest extends CIUnitTestCase
 
  protected function setUp(): void
  {
+ parent::setUp();
+
  $this->exception = new Exceptions(new ExceptionsConfig(), Services::request(), Services::response());
  }
 
+ /**
+ * @requires PHP >= 8.1
+ */
+ public function testDeprecationsOnPhp81DoNotThrow(): void
+ {
+ $config = new ExceptionsConfig();
+
+ $config->logDeprecationsOnly = true;
+ $config->deprecationLogLevel = 'error';
+
+ $this->exception = new Exceptions($config, Services::request(), Services::response());
+ $this->exception->initialize();
+
+ // this is only needed for IDEs not to complain that strlen does not accept explicit null
+ $maybeNull = PHP_VERSION_ID >= 80100 ? null : 'random string';
+
+ try {
+ strlen($maybeNull);
+ $this->assertLogContains('error', '[DEPRECATED] strlen(): ');
+ } catch (ErrorException $e) {
+ $this->fail('The catch block should not be reached.');
+ } finally {
+ restore_error_handler();
+ restore_exception_handler();
+ }
+ }
+
+ public function testSuppressedDeprecationsAreLogged(): void
+ {
+ $config = new ExceptionsConfig();
+
+ $config->logDeprecationsOnly = true;
+ $config->deprecationLogLevel = 'error';
+
+ $this->exception = new Exceptions($config, Services::request(), Services::response());
+ $this->exception->initialize();
+
+ @trigger_error('Hello! I am a deprecation!', E_USER_DEPRECATED);
+ $this->assertLogContains('error', '[DEPRECATED] Hello! I am a deprecation!');
+
+ restore_error_handler();
+ restore_exception_handler();
+ }
+
  public function testDetermineViews(): void
  {
  $determineView = $this->getPrivateMethodInvoker($this->exception, 'determineView');

user_guide_src/source/changelogs/v4.3.0.rst

@@ -176,6 +176,11 @@ Helpers and Functions
 - Added :php:func:`request()` and :php:func:`response()` functions.
 - Add :php:func:`decamelize()` function to convert camelCase to snake_case.
 
+Error Handling
+==============
+
+- You can now log deprecation errors instead of throwing them. See :ref:`logging_deprecation_errors` for details.
+
 Others
 ======
 

user_guide_src/source/general/errors.rst

@@ -133,3 +133,31 @@ Since v4.3.0, you can specify the exit code for your Exception class to implemen
 ``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.
+
+.. _logging_deprecation_errors:
+
+Logging Deprecation Errors
+==========================
+
+.. 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

user_guide_src/source/general/errors/012.php

@@ -0,0 +1,14 @@
+<?php
+
+namespace Config;
+
+use CodeIgniter\Config\BaseConfig;
+use Psr\Log\LogLevel;
+
+class Exceptions extends BaseConfig
+{
+ // ... other properties
+
+ public bool $logDeprecationsOnly = true;
+ 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

@@ -0,0 +1,12 @@
+<?php
+
+namespace Config;
+
+use CodeIgniter\Config\BaseConfig;
+
+class Logger extends BaseConfig
+{
+ // .. other properties
+
+ public $threshold = 5; // originally 4 but changed to 5 to log the warnings from the deprecations
+}

user_guide_src/source/general/errors/014.php

@@ -0,0 +1,4 @@
+<?php
+
+@trigger_error('Do not use this class!', E_USER_DEPRECATED);
+// Your logs should contain a record with a message like: "[DEPRECATED] Do not use this class!"

app/Config/Exceptions.php

@@ -3,6 +3,7 @@
 namespace Config;
 
 use CodeIgniter\Config\BaseConfig;
+use Psr\Log\LogLevel;
 
 /**
  * Setup how the exception handler works.
@@ -49,4 +50,28 @@ class Exceptions extends BaseConfig
  * ex. ['server', 'setup/password', 'secret_token']
  */
  public array $sensitiveDataInTrace = [];
+
+ /**
+ * --------------------------------------------------------------------------
+ * LOG DEPRECATIONS INSTEAD OF THROWING?
+ * --------------------------------------------------------------------------
+ * 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.
+ */
+ public bool $logDeprecationsOnly = false;
+
+ /**
+ * --------------------------------------------------------------------------
+ * LOG LEVEL THRESHOLD FOR DEPRECATIONS
+ * --------------------------------------------------------------------------
+ * If `$logDeprecationsOnly` is set to `true`, this sets the log level
+ * to which the deprecation will be logged. This should be one of the log
+ * levels recognized by PSR-3.
+ *
+ * The related `Config\Logger::$threshold` should be adjusted, if needed,
+ * to capture logging the deprecations.
+ */
+ public string $deprecationLogLevel = LogLevel::WARNING;
 }

system/Debug/Exceptions.php

@@ -22,6 +22,7 @@
 use Config\Exceptions as ExceptionsConfig;
 use Config\Paths;
 use ErrorException;
+use Psr\Log\LogLevel;
 use Throwable;
 
 /**
@@ -82,6 +83,10 @@ public function __construct(ExceptionsConfig $config, $request, ResponseInterfac
  if (! isset($this->config->sensitiveDataInTrace)) {
  $this->config->sensitiveDataInTrace = [];
  }
+ if (! isset($this->config->logDeprecationsOnly, $this->config->deprecationLogLevel)) {
+ $this->config->logDeprecationsOnly = false;
+ $this->config->deprecationLogLevel = LogLevel::WARNING;
+ }
  }
 
  /**
@@ -155,6 +160,10 @@ public function exceptionHandler(Throwable $exception)
  */
  public function errorHandler(int $severity, string $message, ?string $file = null, ?int $line = null)
  {
+ if ($this->isDeprecationError($severity) && $this->config->logDeprecationsOnly) {
+ return $this->handleDeprecationError($message, $file, $line);
+ }
+
  if (! (error_reporting() & $severity)) {
  return;
  }
@@ -328,6 +337,37 @@ protected function determineCodes(Throwable $exception): array
  return [$statusCode, $exitStatus];
  }
 
+ private function isDeprecationError(int $error): bool
+ {
+ $deprecations = E_DEPRECATED | E_USER_DEPRECATED;
+
+ return ($error & $deprecations) !== 0;
+ }
+
+ /**
+ * @noRector \Rector\DeadCode\Rector\ClassMethod\RemoveUselessReturnTagRector
+ *
+ * @return true
+ */
+ private function handleDeprecationError(string $message, ?string $file = null, ?int $line = null): bool
+ {
+ // Remove the trace of the error handler.
+ $trace = array_slice(debug_backtrace(), 2);
+
+ log_message(
+ $this->config->deprecationLogLevel,
+ "[DEPRECATED] {message} in {errFile} on line {errLine}.\n{trace}",
+ [
+ 'message' => $message,
+ 'errFile' => clean_path($file ?? ''),
+ 'errLine' => $line ?? 0,
+ 'trace' => self::renderBacktrace($trace),
+ ]
+ );
+
+ return true;
+ }
+
  // --------------------------------------------------------------------
  // Display Methods
  // --------------------------------------------------------------------

tests/system/Debug/ExceptionsTest.php

@@ -19,6 +19,7 @@
 use CodeIgniter\Test\ReflectionHelper;
 use Config\Exceptions as ExceptionsConfig;
 use Config\Services;
+use ErrorException;
 use RuntimeException;
 
 /**
@@ -32,9 +33,55 @@ final class ExceptionsTest extends CIUnitTestCase
 
  protected function setUp(): void
  {
+ parent::setUp();
+
  $this->exception = new Exceptions(new ExceptionsConfig(), Services::request(), Services::response());
  }
 
+ /**
+ * @requires PHP >= 8.1
+ */
+ public function testDeprecationsOnPhp81DoNotThrow(): void
+ {
+ $config = new ExceptionsConfig();
+
+ $config->logDeprecationsOnly = true;
+ $config->deprecationLogLevel = 'error';
+
+ $this->exception = new Exceptions($config, Services::request(), Services::response());
+ $this->exception->initialize();
+
+ // this is only needed for IDEs not to complain that strlen does not accept explicit null
+ $maybeNull = PHP_VERSION_ID >= 80100 ? null : 'random string';
+
+ try {
+ strlen($maybeNull);
+ $this->assertLogContains('error', '[DEPRECATED] strlen(): ');
+ } catch (ErrorException $e) {
+ $this->fail('The catch block should not be reached.');
+ } finally {
+ restore_error_handler();
+ restore_exception_handler();
+ }
+ }
+
+ public function testSuppressedDeprecationsAreLogged(): void
+ {
+ $config = new ExceptionsConfig();
+
+ $config->logDeprecationsOnly = true;
+ $config->deprecationLogLevel = 'error';
+
+ $this->exception = new Exceptions($config, Services::request(), Services::response());
+ $this->exception->initialize();
+
+ @trigger_error('Hello! I am a deprecation!', E_USER_DEPRECATED);
+ $this->assertLogContains('error', '[DEPRECATED] Hello! I am a deprecation!');
+
+ restore_error_handler();
+ restore_exception_handler();
+ }
+
  public function testDetermineViews(): void
  {
  $determineView = $this->getPrivateMethodInvoker($this->exception, 'determineView');

user_guide_src/source/changelogs/v4.3.0.rst

@@ -176,6 +176,11 @@ Helpers and Functions
 - Added :php:func:`request()` and :php:func:`response()` functions.
 - Add :php:func:`decamelize()` function to convert camelCase to snake_case.
 
+Error Handling
+==============
+
+- You can now log deprecation errors instead of throwing them. See :ref:`logging_deprecation_errors` for details.
+
 Others
 ======
 

user_guide_src/source/general/errors.rst

@@ -133,3 +133,31 @@ Since v4.3.0, you can specify the exit code for your Exception class to implemen
 ``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.
+
+.. _logging_deprecation_errors:
+
+Logging Deprecation Errors
+==========================
+
+.. 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

user_guide_src/source/general/errors/012.php

@@ -0,0 +1,14 @@
+<?php
+
+namespace Config;
+
+use CodeIgniter\Config\BaseConfig;
+use Psr\Log\LogLevel;
+
+class Exceptions extends BaseConfig
+{
+ // ... other properties
+
+ public bool $logDeprecationsOnly = true;
+ 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

@@ -0,0 +1,12 @@
+<?php
+
+namespace Config;
+
+use CodeIgniter\Config\BaseConfig;
+
+class Logger extends BaseConfig
+{
+ // .. other properties
+
+ public $threshold = 5; // originally 4 but changed to 5 to log the warnings from the deprecations
+}

user_guide_src/source/general/errors/014.php

@@ -0,0 +1,4 @@
+<?php
+
+@trigger_error('Do not use this class!', E_USER_DEPRECATED);
+// Your logs should contain a record with a message like: "[DEPRECATED] Do not use this class!"

app/Config/Exceptions.php

@@ -3,6 +3,7 @@
 namespace Config;
 
 use CodeIgniter\Config\BaseConfig;
+use Psr\Log\LogLevel;
 
 /**
  * Setup how the exception handler works.
@@ -49,4 +50,28 @@ class Exceptions extends BaseConfig
  * ex. ['server', 'setup/password', 'secret_token']
  */
  public array $sensitiveDataInTrace = [];
+
+ /**
+ * --------------------------------------------------------------------------
+ * LOG DEPRECATIONS INSTEAD OF THROWING?
+ * --------------------------------------------------------------------------
+ * 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.
+ */
+ public bool $logDeprecationsOnly = false;
+
+ /**
+ * --------------------------------------------------------------------------
+ * LOG LEVEL THRESHOLD FOR DEPRECATIONS
+ * --------------------------------------------------------------------------
+ * If `$logDeprecationsOnly` is set to `true`, this sets the log level
+ * to which the deprecation will be logged. This should be one of the log
+ * levels recognized by PSR-3.
+ *
+ * The related `Config\Logger::$threshold` should be adjusted, if needed,
+ * to capture logging the deprecations.
+ */
+ public string $deprecationLogLevel = LogLevel::WARNING;
 }

system/Debug/Exceptions.php

@@ -22,6 +22,7 @@
 use Config\Exceptions as ExceptionsConfig;
 use Config\Paths;
 use ErrorException;
+use Psr\Log\LogLevel;
 use Throwable;
 
 /**
@@ -82,6 +83,10 @@ public function __construct(ExceptionsConfig $config, $request, ResponseInterfac
  if (! isset($this->config->sensitiveDataInTrace)) {
  $this->config->sensitiveDataInTrace = [];
  }
+ if (! isset($this->config->logDeprecationsOnly, $this->config->deprecationLogLevel)) {
+ $this->config->logDeprecationsOnly = false;
+ $this->config->deprecationLogLevel = LogLevel::WARNING;
+ }
  }
 
  /**
@@ -155,6 +160,10 @@ public function exceptionHandler(Throwable $exception)
  */
  public function errorHandler(int $severity, string $message, ?string $file = null, ?int $line = null)
  {
+ if ($this->isDeprecationError($severity) && $this->config->logDeprecationsOnly) {
+ return $this->handleDeprecationError($message, $file, $line);
+ }
+
  if (! (error_reporting() & $severity)) {
  return;
  }
@@ -328,6 +337,37 @@ protected function determineCodes(Throwable $exception): array
  return [$statusCode, $exitStatus];
  }
 
+ private function isDeprecationError(int $error): bool
+ {
+ $deprecations = E_DEPRECATED | E_USER_DEPRECATED;
+
+ return ($error & $deprecations) !== 0;
+ }
+
+ /**
+ * @noRector \Rector\DeadCode\Rector\ClassMethod\RemoveUselessReturnTagRector
+ *
+ * @return true
+ */
+ private function handleDeprecationError(string $message, ?string $file = null, ?int $line = null): bool
+ {
+ // Remove the trace of the error handler.
+ $trace = array_slice(debug_backtrace(), 2);
+
+ log_message(
+ $this->config->deprecationLogLevel,
+ "[DEPRECATED] {message} in {errFile} on line {errLine}.\n{trace}",
+ [
+ 'message' => $message,
+ 'errFile' => clean_path($file ?? ''),
+ 'errLine' => $line ?? 0,
+ 'trace' => self::renderBacktrace($trace),
+ ]
+ );
+
+ return true;
+ }
+
  // --------------------------------------------------------------------
  // Display Methods
  // --------------------------------------------------------------------

tests/system/Debug/ExceptionsTest.php

@@ -19,6 +19,7 @@
 use CodeIgniter\Test\ReflectionHelper;
 use Config\Exceptions as ExceptionsConfig;
 use Config\Services;
+use ErrorException;
 use RuntimeException;
 
 /**
@@ -32,9 +33,55 @@ final class ExceptionsTest extends CIUnitTestCase
 
  protected function setUp(): void
  {
+ parent::setUp();
+
  $this->exception = new Exceptions(new ExceptionsConfig(), Services::request(), Services::response());
  }
 
+ /**
+ * @requires PHP >= 8.1
+ */
+ public function testDeprecationsOnPhp81DoNotThrow(): void
+ {
+ $config = new ExceptionsConfig();
+
+ $config->logDeprecationsOnly = true;
+ $config->deprecationLogLevel = 'error';
+
+ $this->exception = new Exceptions($config, Services::request(), Services::response());
+ $this->exception->initialize();
+
+ // this is only needed for IDEs not to complain that strlen does not accept explicit null
+ $maybeNull = PHP_VERSION_ID >= 80100 ? null : 'random string';
+
+ try {
+ strlen($maybeNull);
+ $this->assertLogContains('error', '[DEPRECATED] strlen(): ');
+ } catch (ErrorException $e) {
+ $this->fail('The catch block should not be reached.');
+ } finally {
+ restore_error_handler();
+ restore_exception_handler();
+ }
+ }
+
+ public function testSuppressedDeprecationsAreLogged(): void
+ {
+ $config = new ExceptionsConfig();
+
+ $config->logDeprecationsOnly = true;
+ $config->deprecationLogLevel = 'error';
+
+ $this->exception = new Exceptions($config, Services::request(), Services::response());
+ $this->exception->initialize();
+
+ @trigger_error('Hello! I am a deprecation!', E_USER_DEPRECATED);
+ $this->assertLogContains('error', '[DEPRECATED] Hello! I am a deprecation!');
+
+ restore_error_handler();
+ restore_exception_handler();
+ }
+
  public function testDetermineViews(): void
  {
  $determineView = $this->getPrivateMethodInvoker($this->exception, 'determineView');

user_guide_src/source/changelogs/v4.3.0.rst

@@ -176,6 +176,11 @@ Helpers and Functions
 - Added :php:func:`request()` and :php:func:`response()` functions.
 - Add :php:func:`decamelize()` function to convert camelCase to snake_case.
 
+Error Handling
+==============
+
+- You can now log deprecation errors instead of throwing them. See :ref:`logging_deprecation_errors` for details.
+
 Others
 ======
 

user_guide_src/source/general/errors.rst

@@ -133,3 +133,31 @@ Since v4.3.0, you can specify the exit code for your Exception class to implemen
 ``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.
+
+.. _logging_deprecation_errors:
+
+Logging Deprecation Errors
+==========================
+
+.. 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

user_guide_src/source/general/errors/012.php

@@ -0,0 +1,14 @@
+<?php
+
+namespace Config;
+
+use CodeIgniter\Config\BaseConfig;
+use Psr\Log\LogLevel;
+
+class Exceptions extends BaseConfig
+{
+ // ... other properties
+
+ public bool $logDeprecationsOnly = true;
+ 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

@@ -0,0 +1,12 @@
+<?php
+
+namespace Config;
+
+use CodeIgniter\Config\BaseConfig;
+
+class Logger extends BaseConfig
+{
+ // .. other properties
+
+ public $threshold = 5; // originally 4 but changed to 5 to log the warnings from the deprecations
+}

user_guide_src/source/general/errors/014.php

@@ -0,0 +1,4 @@
+<?php
+
+@trigger_error('Do not use this class!', E_USER_DEPRECATED);
+// Your logs should contain a record with a message like: "[DEPRECATED] Do not use this class!"

app/Config/Exceptions.php

@@ -3,6 +3,7 @@
 namespace Config;
 
 use CodeIgniter\Config\BaseConfig;
+use Psr\Log\LogLevel;
 
 /**
  * Setup how the exception handler works.
@@ -49,4 +50,28 @@ class Exceptions extends BaseConfig
  * ex. ['server', 'setup/password', 'secret_token']
  */
  public array $sensitiveDataInTrace = [];
+
+ /**
+ * --------------------------------------------------------------------------
+ * LOG DEPRECATIONS INSTEAD OF THROWING?
+ * --------------------------------------------------------------------------
+ * 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.
+ */
+ public bool $logDeprecationsOnly = false;
+
+ /**
+ * --------------------------------------------------------------------------
+ * LOG LEVEL THRESHOLD FOR DEPRECATIONS
+ * --------------------------------------------------------------------------
+ * If `$logDeprecationsOnly` is set to `true`, this sets the log level
+ * to which the deprecation will be logged. This should be one of the log
+ * levels recognized by PSR-3.
+ *
+ * The related `Config\Logger::$threshold` should be adjusted, if needed,
+ * to capture logging the deprecations.
+ */
+ public string $deprecationLogLevel = LogLevel::WARNING;
 }

system/Debug/Exceptions.php

@@ -22,6 +22,7 @@
 use Config\Exceptions as ExceptionsConfig;
 use Config\Paths;
 use ErrorException;
+use Psr\Log\LogLevel;
 use Throwable;
 
 /**
@@ -82,6 +83,10 @@ public function __construct(ExceptionsConfig $config, $request, ResponseInterfac
  if (! isset($this->config->sensitiveDataInTrace)) {
  $this->config->sensitiveDataInTrace = [];
  }
+ if (! isset($this->config->logDeprecationsOnly, $this->config->deprecationLogLevel)) {
+ $this->config->logDeprecationsOnly = false;
+ $this->config->deprecationLogLevel = LogLevel::WARNING;
+ }
  }
 
  /**
@@ -155,6 +160,10 @@ public function exceptionHandler(Throwable $exception)
  */
  public function errorHandler(int $severity, string $message, ?string $file = null, ?int $line = null)
  {
+ if ($this->isDeprecationError($severity) && $this->config->logDeprecationsOnly) {
+ return $this->handleDeprecationError($message, $file, $line);
+ }
+
  if (! (error_reporting() & $severity)) {
  return;
  }
@@ -328,6 +337,37 @@ protected function determineCodes(Throwable $exception): array
  return [$statusCode, $exitStatus];
  }
 
+ private function isDeprecationError(int $error): bool
+ {
+ $deprecations = E_DEPRECATED | E_USER_DEPRECATED;
+
+ return ($error & $deprecations) !== 0;
+ }
+
+ /**
+ * @noRector \Rector\DeadCode\Rector\ClassMethod\RemoveUselessReturnTagRector
+ *
+ * @return true
+ */
+ private function handleDeprecationError(string $message, ?string $file = null, ?int $line = null): bool
+ {
+ // Remove the trace of the error handler.
+ $trace = array_slice(debug_backtrace(), 2);
+
+ log_message(
+ $this->config->deprecationLogLevel,
+ "[DEPRECATED] {message} in {errFile} on line {errLine}.\n{trace}",
+ [
+ 'message' => $message,
+ 'errFile' => clean_path($file ?? ''),
+ 'errLine' => $line ?? 0,
+ 'trace' => self::renderBacktrace($trace),
+ ]
+ );
+
+ return true;
+ }
+
  // --------------------------------------------------------------------
  // Display Methods
  // --------------------------------------------------------------------

tests/system/Debug/ExceptionsTest.php

@@ -19,6 +19,7 @@
 use CodeIgniter\Test\ReflectionHelper;
 use Config\Exceptions as ExceptionsConfig;
 use Config\Services;
+use ErrorException;
 use RuntimeException;
 
 /**
@@ -32,9 +33,55 @@ final class ExceptionsTest extends CIUnitTestCase
 
  protected function setUp(): void
  {
+ parent::setUp();
+
  $this->exception = new Exceptions(new ExceptionsConfig(), Services::request(), Services::response());
  }
 
+ /**
+ * @requires PHP >= 8.1
+ */
+ public function testDeprecationsOnPhp81DoNotThrow(): void
+ {
+ $config = new ExceptionsConfig();
+
+ $config->logDeprecationsOnly = true;
+ $config->deprecationLogLevel = 'error';
+
+ $this->exception = new Exceptions($config, Services::request(), Services::response());
+ $this->exception->initialize();
+
+ // this is only needed for IDEs not to complain that strlen does not accept explicit null
+ $maybeNull = PHP_VERSION_ID >= 80100 ? null : 'random string';
+
+ try {
+ strlen($maybeNull);
+ $this->assertLogContains('error', '[DEPRECATED] strlen(): ');
+ } catch (ErrorException $e) {
+ $this->fail('The catch block should not be reached.');
+ } finally {
+ restore_error_handler();
+ restore_exception_handler();
+ }
+ }
+
+ public function testSuppressedDeprecationsAreLogged(): void
+ {
+ $config = new ExceptionsConfig();
+
+ $config->logDeprecationsOnly = true;
+ $config->deprecationLogLevel = 'error';
+
+ $this->exception = new Exceptions($config, Services::request(), Services::response());
+ $this->exception->initialize();
+
+ @trigger_error('Hello! I am a deprecation!', E_USER_DEPRECATED);
+ $this->assertLogContains('error', '[DEPRECATED] Hello! I am a deprecation!');
+
+ restore_error_handler();
+ restore_exception_handler();
+ }
+
  public function testDetermineViews(): void
  {
  $determineView = $this->getPrivateMethodInvoker($this->exception, 'determineView');

user_guide_src/source/changelogs/v4.3.0.rst

@@ -176,6 +176,11 @@ Helpers and Functions
 - Added :php:func:`request()` and :php:func:`response()` functions.
 - Add :php:func:`decamelize()` function to convert camelCase to snake_case.
 
+Error Handling
+==============
+
+- You can now log deprecation errors instead of throwing them. See :ref:`logging_deprecation_errors` for details.
+
 Others
 ======
 

user_guide_src/source/general/errors.rst

@@ -133,3 +133,31 @@ Since v4.3.0, you can specify the exit code for your Exception class to implemen
 ``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.
+
+.. _logging_deprecation_errors:
+
+Logging Deprecation Errors
+==========================
+
+.. 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

user_guide_src/source/general/errors/012.php

@@ -0,0 +1,14 @@
+<?php
+
+namespace Config;
+
+use CodeIgniter\Config\BaseConfig;
+use Psr\Log\LogLevel;
+
+class Exceptions extends BaseConfig
+{
+ // ... other properties
+
+ public bool $logDeprecationsOnly = true;
+ 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

@@ -0,0 +1,12 @@
+<?php
+
+namespace Config;
+
+use CodeIgniter\Config\BaseConfig;
+
+class Logger extends BaseConfig
+{
+ // .. other properties
+
+ public $threshold = 5; // originally 4 but changed to 5 to log the warnings from the deprecations
+}

user_guide_src/source/general/errors/014.php

@@ -0,0 +1,4 @@
+<?php
+
+@trigger_error('Do not use this class!', E_USER_DEPRECATED);
+// Your logs should contain a record with a message like: "[DEPRECATED] Do not use this class!"

app/Config/Exceptions.php

@@ -3,6 +3,7 @@
 namespace Config;
 
 use CodeIgniter\Config\BaseConfig;
+use Psr\Log\LogLevel;
 
 /**
  * Setup how the exception handler works.
@@ -49,4 +50,28 @@ class Exceptions extends BaseConfig
  * ex. ['server', 'setup/password', 'secret_token']
  */
  public array $sensitiveDataInTrace = [];
+
+ /**
+ * --------------------------------------------------------------------------
+ * LOG DEPRECATIONS INSTEAD OF THROWING?
+ * --------------------------------------------------------------------------
+ * 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.
+ */
+ public bool $logDeprecationsOnly = false;
+
+ /**
+ * --------------------------------------------------------------------------
+ * LOG LEVEL THRESHOLD FOR DEPRECATIONS
+ * --------------------------------------------------------------------------
+ * If `$logDeprecationsOnly` is set to `true`, this sets the log level
+ * to which the deprecation will be logged. This should be one of the log
+ * levels recognized by PSR-3.
+ *
+ * The related `Config\Logger::$threshold` should be adjusted, if needed,
+ * to capture logging the deprecations.
+ */
+ public string $deprecationLogLevel = LogLevel::WARNING;
 }

system/Debug/Exceptions.php

@@ -22,6 +22,7 @@
 use Config\Exceptions as ExceptionsConfig;
 use Config\Paths;
 use ErrorException;
+use Psr\Log\LogLevel;
 use Throwable;
 
 /**
@@ -82,6 +83,10 @@ public function __construct(ExceptionsConfig $config, $request, ResponseInterfac
  if (! isset($this->config->sensitiveDataInTrace)) {
  $this->config->sensitiveDataInTrace = [];
  }
+ if (! isset($this->config->logDeprecationsOnly, $this->config->deprecationLogLevel)) {
+ $this->config->logDeprecationsOnly = false;
+ $this->config->deprecationLogLevel = LogLevel::WARNING;
+ }
  }
 
  /**
@@ -155,6 +160,10 @@ public function exceptionHandler(Throwable $exception)
  */
  public function errorHandler(int $severity, string $message, ?string $file = null, ?int $line = null)
  {
+ if ($this->isDeprecationError($severity) && $this->config->logDeprecationsOnly) {
+ return $this->handleDeprecationError($message, $file, $line);
+ }
+
  if (! (error_reporting() & $severity)) {
  return;
  }
@@ -328,6 +337,37 @@ protected function determineCodes(Throwable $exception): array
  return [$statusCode, $exitStatus];
  }
 
+ private function isDeprecationError(int $error): bool
+ {
+ $deprecations = E_DEPRECATED | E_USER_DEPRECATED;
+
+ return ($error & $deprecations) !== 0;
+ }
+
+ /**
+ * @noRector \Rector\DeadCode\Rector\ClassMethod\RemoveUselessReturnTagRector
+ *
+ * @return true
+ */
+ private function handleDeprecationError(string $message, ?string $file = null, ?int $line = null): bool
+ {
+ // Remove the trace of the error handler.
+ $trace = array_slice(debug_backtrace(), 2);
+
+ log_message(
+ $this->config->deprecationLogLevel,
+ "[DEPRECATED] {message} in {errFile} on line {errLine}.\n{trace}",
+ [
+ 'message' => $message,
+ 'errFile' => clean_path($file ?? ''),
+ 'errLine' => $line ?? 0,
+ 'trace' => self::renderBacktrace($trace),
+ ]
+ );
+
+ return true;
+ }
+
  // --------------------------------------------------------------------
  // Display Methods
  // --------------------------------------------------------------------

tests/system/Debug/ExceptionsTest.php

@@ -19,6 +19,7 @@
 use CodeIgniter\Test\ReflectionHelper;
 use Config\Exceptions as ExceptionsConfig;
 use Config\Services;
+use ErrorException;
 use RuntimeException;
 
 /**
@@ -32,9 +33,55 @@ final class ExceptionsTest extends CIUnitTestCase
 
  protected function setUp(): void
  {
+ parent::setUp();
+
  $this->exception = new Exceptions(new ExceptionsConfig(), Services::request(), Services::response());
  }
 
+ /**
+ * @requires PHP >= 8.1
+ */
+ public function testDeprecationsOnPhp81DoNotThrow(): void
+ {
+ $config = new ExceptionsConfig();
+
+ $config->logDeprecationsOnly = true;
+ $config->deprecationLogLevel = 'error';
+
+ $this->exception = new Exceptions($config, Services::request(), Services::response());
+ $this->exception->initialize();
+
+ // this is only needed for IDEs not to complain that strlen does not accept explicit null
+ $maybeNull = PHP_VERSION_ID >= 80100 ? null : 'random string';
+
+ try {
+ strlen($maybeNull);
+ $this->assertLogContains('error', '[DEPRECATED] strlen(): ');
+ } catch (ErrorException $e) {
+ $this->fail('The catch block should not be reached.');
+ } finally {
+ restore_error_handler();
+ restore_exception_handler();
+ }
+ }
+
+ public function testSuppressedDeprecationsAreLogged(): void
+ {
+ $config = new ExceptionsConfig();
+
+ $config->logDeprecationsOnly = true;
+ $config->deprecationLogLevel = 'error';
+
+ $this->exception = new Exceptions($config, Services::request(), Services::response());
+ $this->exception->initialize();
+
+ @trigger_error('Hello! I am a deprecation!', E_USER_DEPRECATED);
+ $this->assertLogContains('error', '[DEPRECATED] Hello! I am a deprecation!');
+
+ restore_error_handler();
+ restore_exception_handler();
+ }
+
  public function testDetermineViews(): void
  {
  $determineView = $this->getPrivateMethodInvoker($this->exception, 'determineView');

user_guide_src/source/changelogs/v4.3.0.rst

@@ -176,6 +176,11 @@ Helpers and Functions
 - Added :php:func:`request()` and :php:func:`response()` functions.
 - Add :php:func:`decamelize()` function to convert camelCase to snake_case.
 
+Error Handling
+==============
+
+- You can now log deprecation errors instead of throwing them. See :ref:`logging_deprecation_errors` for details.
+
 Others
 ======
 

user_guide_src/source/general/errors.rst

@@ -133,3 +133,31 @@ Since v4.3.0, you can specify the exit code for your Exception class to implemen
 ``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.
+
+.. _logging_deprecation_errors:
+
+Logging Deprecation Errors
+==========================
+
+.. 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

user_guide_src/source/general/errors/012.php

@@ -0,0 +1,14 @@
+<?php
+
+namespace Config;
+
+use CodeIgniter\Config\BaseConfig;
+use Psr\Log\LogLevel;
+
+class Exceptions extends BaseConfig
+{
+ // ... other properties
+
+ public bool $logDeprecationsOnly = true;
+ 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

@@ -0,0 +1,12 @@
+<?php
+
+namespace Config;
+
+use CodeIgniter\Config\BaseConfig;
+
+class Logger extends BaseConfig
+{
+ // .. other properties
+
+ public $threshold = 5; // originally 4 but changed to 5 to log the warnings from the deprecations
+}

user_guide_src/source/general/errors/014.php

@@ -0,0 +1,4 @@
+<?php
+
+@trigger_error('Do not use this class!', E_USER_DEPRECATED);
+// Your logs should contain a record with a message like: "[DEPRECATED] Do not use this class!"