Error Handling

CodeIgniter builds error reporting into your system through Exceptions, both the SPL collection, as well as a few custom exceptions that are provided by the framework. Depending on your environment’s setup, the default action when an error or exception is thrown is to display a detailed error report unless the application is running under the production environment. In this case, a more generic message is displayed to keep the best user experience for your users.

Using Exceptions
Configuration
- Logging Exceptions
Framework Exceptions
Specify HTTP Status Code in Your Exception
Specify Exit Code in Your Exception
Logging Deprecation Warnings

Using Exceptions 

This section is a quick overview for newer programmers, or for developers who are not experienced with using 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:

<?php

throw new \Exception('Some message goes here');

If you are calling a method that might throw an exception, you can catch that exception using a try/catch block:

<?php

try {
    $user = $userModel->find($id);
} catch (\Exception $e) {
    exit($e->getMessage());
}

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.

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 not child classes of the caught exception will be passed on to the error handler:

<?php

try {
    $user = $userModel->find($id);
} catch (\CodeIgniter\UnknownFileException $e) {
    // do something here...
}

This can be handy for handling the error yourself, or for performing cleanup before the script ends. If you want the error handler to function as normal, you can throw a new exception within the catch block:

<?php

try {
    $user = $userModel->find($id);
} catch (\CodeIgniter\UnknownFileException $e) {
    // do something here...

    throw new \RuntimeException($e->getMessage(), $e->getCode(), $e);
}

Configuration 

By default, CodeIgniter will display all errors in the development and testing environments, and will not display any errors in the production environment. You can change this by setting the CI_ENVIRONMENT variable in the .env file.

Important

Disabling error reporting DOES NOT stop logs from being written if there are errors.

Logging Exceptions 

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:

<?php

namespace Config;

use CodeIgniter\Config\BaseConfig;

class Exceptions extends BaseConfig
{
    public $log = true;
}

To ignore logging on other status codes, you can set the status code to ignore in the same file:

<?php

namespace Config;

use CodeIgniter\Config\BaseConfig;

class Exceptions extends BaseConfig
{
    public $ignoredCodes = [404];
}

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.

Framework Exceptions 

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:

<?php

if (! $page = $pageModel->find($id)) {
    throw \CodeIgniter\Exceptions\PageNotFoundException::forPageNotFound();
}

You can pass a message into the exception that will be displayed in place of the default message on the 404 page.

ConfigException 

This exception should be used when the values from the configuration class are invalid, or when the config class is not the right type, etc:

<?php

throw new \CodeIgniter\Exceptions\ConfigException();

This provides an exit code of 3.

DatabaseException 

This exception is thrown for database errors, such as when the database connection cannot be created, or when it is temporarily lost:

<?php

throw new \CodeIgniter\Database\Exceptions\DatabaseException();

This provides an exit code of 8.

RedirectException 

This exception is a special case allowing for overriding of all other response routing and forcing a redirect to a specific URI:

<?php

throw new \CodeIgniter\Router\Exceptions\RedirectException($uri);

$uri is a URI path relative to baseURL. You can also supply a redirect code to use instead of the default (302, “temporary redirect”):

<?php

throw new \CodeIgniter\Router\Exceptions\RedirectException($uri, 301);

Specify HTTP Status Code in Your Exception 

New in version 4.3.0.

Since v4.3.0, you can specify the HTTP status code for your Exception class to implement HTTPExceptionInterface.

When an exception implementing HTTPExceptionInterface is caught by CodeIgniter’s exception handler, the Exception code will become the HTTP status code.

Specify Exit Code in Your Exception 

New in version 4.3.0.

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.

Logging Deprecation Warnings 

New in version 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. 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:

<?php

namespace Config;

use CodeIgniter\Config\BaseConfig;
use Psr\Log\LogLevel;

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
}

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.

<?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
}

After that, subsequent deprecations will be logged instead of thrown.

This feature also works with user deprecations:

<?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!"

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.