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.