How To Use Yii2 Error Handler

1 Disable Or Enable

The Yii2 error handler is enabled by default. You can disable it by adding following code to your application entry script: YOUR_APP_FOLDER/web/index.php.

// YOUR_APP_FOLDER/web/index.php
// Disable Yii2 error handler
define('YII_ENABLE_ERROR_HANDLER', false);

 

2 Default Configuration

Yii2 application template has default error handler configurations and it's ready to use on the fly.

Yii2 error handler is registered as an application component named errorHandler. The configuration locates in:

• for Yii2 basic application template, YOUR_APP/config/web.php;
• for Yii2 advanced application template, YOUR_PROJECT/YOUR_APP/config/main.php;

For example, the default configuration of error handler is to use site/error action to display errors and exceptions.

return [
    // ...
    'components' => [
        // ...
        'errorHandler' => [
            'errorAction' => 'site/error',
        ],
        // ...
    ],
    // ...
];

But there is no need to write a real error action in SiteController. Because Yii2 gives a default ErrorAction and it has been used in SiteController.php file of Yii2 application template already.

// SiteController.php
class SiteController extends Controller
{
    // ...
    public function actions()
    {
        return [
            'error' => [
                'class' => 'yii\web\ErrorAction',
            ],
            // ...
        ];
    }
    // ...
}

With this default configuration, yii\web\ErrorAction will use YOUR_APP/views/site/error.php as the view to display errors.

 

3 Using Default Configuration But Customized View

Assume that you are using default error handler configurations as follows:

In YOUR_APP/config/web.php or YOUR_PROJECT/YOUR_APP/config/main.php:

return [
    // ...
    'components' => [
        // ...
        'errorHandler' => [
            'errorAction' => 'site/error',
        ],
        // ...
    ],
    // ...
];

In YOUR_APP/controllers/SiteController.php:

// SiteController.php
class SiteController extends Controller
{
    // ...
    public function actions()
    {
        return [
            'error' => [
                'class' => 'yii\web\ErrorAction',
            ],
            // ...
        ];
    }
    // ...
}

3.1 Customizing Error View

It is easy to use a customized error view, just add a view option in SiteController.php, this will override the view property of yii\web\ErrorAction.

// SiteController.php
class SiteController extends Controller
{
    // ...
    public function actions()
    {
        return [
            'error' => [
                'class' => 'yii\web\ErrorAction',
                'view' => '@app/views/site/YOUR_ERROR_VIEW.php'
            ],
            // ...
        ];
    }
    // ...
}

3.2 Customizing Error View Layout

There are two methods to assign a customized layout to a error view.

3.2.1

Edit and specify the layout in your error view PHP file directly. For example, assign error_layout.php to your error view:

// YOUR_ERROR_VIEW.php
$this->context->layout = 'error_layout';

3.2.2

Assign your customized error layout in beforeAction of SiteController.

// SiteController.php
public function beforeAction($action)
{
    if ($action->id == 'error') {
        $this->layout = 'error_layout';
    }

    return parent::beforeAction($action);
}

 

4 Using Customized Error Action

Alternatively, you can write your own error action method and use your own error view or layout.

First of all, for example, create a site/fault action in your SiteController, and use it as error action.

// SiteController.php
public function actionFault()
{
    $exception = Yii::$app->errorHandler->exception;

    if ($exception !== null) {
        $statusCode = $exception->statusCode;
        $name = $exception->getName();
        $message = $exception->getMessage();

        $this->layout = 'your_error_layout';

        return $this->render('your_error_view', [
            'exception' => $exception,
            'statusCode' => $statusCode,
            'name' => $name,
            'message' => $message
        ]);
    }
}

Secondly, comment out the default error action configuration in SiteController.

// SiteController.php
class SiteController extends Controller
{
    // ...
    public function actions()
    {
        return [
             // Comment out or remove following error configuration
            // 'error' => [
            //    'class' => 'yii\web\ErrorAction',
            //    'view' => '@app/views/site/YOUR_ERROR_VIEW.php'
            // ],
            // ...
        ];
    }
    // ...
}

Finally, edit YOUR_APP/config/web.php or YOUR_PROJECT/YOUR_APP/config/main.php:

return [
    // ...
    'components' => [
        // ...
        'errorHandler' => [
            'errorAction' => 'site/fault',
        ],
        // ...
    ],
    // ...
];

That's all. Yii2 then will use site/fault as error action, and render your_error_view with your_error_layout to display errors.