Logging and error handling

A log is a file where the site records what happened to it: errors, warnings, important events. On a production server the visitor is not shown the details of a failure, so the log is the main way to learn what went wrong.

Where the log is

Messages are written to the file runtime/logs/app.log. You do not create it; it appears by itself. All PHP errors and uncaught exceptions get there automatically.

Writing a message

// controllers/PostController.php
public function actionDelete(int $id)
{
    Post::findOne($id)?->delete();
 
    Yii::warning("Post $id deleted by user " . Yii::$app->user->id, 'post');
 
    return $this->redirect(['post/index']);
}

After a post is deleted, a line with the date, the warning level, the post category and the text appears in runtime/logs/app.log. The second argument is the category, an arbitrary label for searching and filtering.

Levels

Configuration

The log component is described in config/web.php:

// config/web.php
'log' => [
    'traceLevel' => YII_DEBUG ? 3 : 0,
    'targets' => [
        [
            'class' => 'yii\log\FileTarget',
            'levels' => ['error', 'warning'],
        ],
    ],
],

A target defines where and which messages are written. Here only errors and warnings get into the file; Yii::info() calls are skipped. To write them too, add 'info' to levels.

A separate file for a category

'targets' => [
    [
        'class' => 'yii\log\FileTarget',
        'levels' => ['error', 'warning'],
    ],
    [
        'class' => 'yii\log\FileTarget',
        'levels' => ['info', 'warning'],
        'categories' => ['post'],
        'logFile' => '@runtime/logs/post.log',
    ],
],

Messages with the post category are also written to runtime/logs/post.log. There are other targets: yii\log\EmailTarget sends messages by email, yii\log\DbTarget writes them to a table.

The error page

Which page to show on an error is defined by the errorHandler component:

// config/web.php
'errorHandler' => [
    'errorAction' => 'site/error',
],

The site/error action is already attached in SiteController through the ready-made class yii\web\ErrorAction, and its view is views/site/error.php. The variables $name (for example "Not Found (#404)") and $message, the exception text, are available in it. Change this view to make the error page look your way.

In development mode a detailed report with the place of the error and the call stack is shown instead of this page for failures in code.

Your own exceptions

To return the needed response code to the visitor, throw an exception:

use yii\web\HttpException;
 
throw new HttpException(410, 'The post has been deleted.');

The visitor sees the error page with code 410 and this text. Frequent codes have ready classes: NotFoundHttpException, ForbiddenHttpException.

Common mistake

Do not write passwords, access keys or card data to the log, for example the whole Yii::$app->request->post() array from the login form. The log is stored as plain text, many people read it, and it gets into backups.