runtime-handling-errors.md 2.96 KB
Newer Older
Alexander Makarov committed
1 2 3
Error Handling
==============

4
> Note: This section is under development.
Qiang Xue committed
5

Alexander Makarov committed
6
Error handling in Yii is different than handling errors in plain PHP. First of all, Yii will convert all non-fatal errors
7 8 9 10 11 12 13
to *exceptions*:

```php
use yii\base\ErrorException;
use Yii;

try {
14
    10/0;
15
} catch (ErrorException $e) {
16
    Yii::warning("Tried dividing by zero.");
17 18 19 20 21 22 23 24 25
}

// execution may continue
```

As demonstrated above you may handle errors using `try`-`catch`.

Second, even fatal errors in Yii are rendered in a nice way. This means that in debugging mode, you can trace the causes
of fatal errors in order to more quickly identify the cause of the problem.
26

27

Larry Ullman committed
28 29
Rendering errors in a dedicated controller action
-------------------------------------------------
30

Alexander Makarov committed
31
The default Yii error page is great when developing a site, and is acceptable for production sites if `YII_DEBUG`
32
is turned off in your bootstrap `index.php` file. But you may want to customize the default error page to make it
Alexander Makarov committed
33
more suitable for your project.
Larry Ullman committed
34

Alexander Makarov committed
35 36
The easiest way to create a custom error page it is to use a dedicated controller action for error rendering. First,
you'll need to configure the `errorHandler` component in the application's configuration:
37 38

```php
39 40
// ...
'components' => [
41
    // ...
42 43
    'errorHandler' => [
        'errorAction' => 'site/error',
44
    ],
45
]
46 47
```

48
With that configuration in place, whenever an error occurs, Yii will execute the `error`-action of the `site`-controller.
Alexander Makarov committed
49
That action should look for an exception and, if present, render the proper view file, passing along the exception:
50 51 52 53

```php
public function actionError()
{
54 55 56
    $exception = \Yii::$app->errorHandler->exception;
    if ($exception !== null) {
        return $this->render('error', ['exception' => $exception]);
57
    }
58 59 60
}
```

Alexander Makarov committed
61 62
Next, you would create the `views/site/error.php` file, which would make use of the exception. The exception object has
the following properties:
Larry Ullman committed
63

64
- `statusCode`: the HTTP status code (e.g. 403, 500). Available for [[yii\web\HttpException|HTTP exceptions]] only.
Alexander Makarov committed
65 66 67 68 69
- `code`: the code of the exception.
- `message`: the error message.
- `file`: the name of the PHP script file where the error occurs.
- `line`: the line number of the code where the error occurs.
- `trace`: the call stack of the error.
70

Larry Ullman committed
71 72 73 74

Rendering errors without a dedicated controller action
------------------------------------------------------

Alexander Makarov committed
75 76
Instead of creating a dedicated action within the Site controller, you could just indicate to Yii what class should
be used to handle errors:
77 78 79 80 81 82 83 84 85 86 87 88

```php
public function actions()
{
    return [
        'error' => [
            'class' => 'yii\web\ErrorAction',
        ],
    ];
}
```

Alexander Makarov committed
89 90
After associating the class with the error as in the above, define the `views/site/error.php` file, which will
automatically be used. The view will be passed three variables:
91 92 93 94 95

- `$name`: the error name
- `$message`: the error message
- `$exception`: the exception being handled

96
The `$exception` object will have the same properties as outlined above.