Может войдёшь?
Черновики Написать статью Профиль

Ошибки и журнал

перевод документация 5.х

  1. 1. Введение
  2. 2. Настройка
    1. 2.1. Детализация ошибок
    2. 2.2. Хранилище журналов
    3. 2.3. Уровни важности событий
  3. 3. Обработчик исключений
    1. 3.1. Метод PHPreport()
    2. 3.2. Метод PHPrender()
  4. 4. HTTP-исключения
    1. 4.1. Свои страницы HTTP-ошибок
  5. 5. Журналы
Этот перевод актуален для англоязычной документации на (ветка 5.3) , (ветка 5.2) , (ветка 5.1) и (ветка 5.0). Опечатка? Выдели и нажми Ctrl+Enter.

Введение

Когда вы начинаете новый Laravel проект, обработка ошибок и исключений уже настроена для вас. Все происходящие в вашем приложении исключения записываются в журнал и отображаются пользователю в классе App\Exceptions\Handler. В этой статье мы подробно рассмотрим этот класс.

Для журналирования Laravel использует библиотеку Monolog, которая обеспечивает поддержку различных мощных обработчиков журналов. В Laravel настроены несколько из них, благодаря чему вы можете выбрать между единым файлом журнала, ротируемыми файлами журналов и записью информации в системный журнал.

Настройка

Детализация ошибок

Параметр confdebug в файле настроек config/app.php определяет, сколько информации об ошибке показывать пользователю. По умолчанию этот параметр установлен в соответствии со значением переменной среды APP_DEBUG, которая хранится в файле .env.

Для локальной разработки вам следует установить переменную среды APP_DEBUG в значение true. В продакшн-среде эта переменная всегда должна иметь значение false. Если значение равно true на продакшн-сервере, вы рискуете раскрыть важные значения настроек вашим конечным пользователям.

Хранилище журналов

Изначально Laravel поддерживает запись журналов в единый файл (single), в отдельные файлы за каждый день (daily), в syslog и errorlog. Для использования определённого механизма хранения вам надо изменить параметр conflog в файле config/app.php. Например, если вы хотите использовать ежедневные файлы журнала вместо единого файла, вам надо установить значение log равное daily в файле настроек app:

PHP
'log' => 'daily'
+ 5.3 5.2

добавлено в 5.3 () 5.2 ()

Максимальное число ежедневных файлов журнала

При использовании режима daily Laravel по умолчанию хранит журналы только за последние 5 дней. Если вы хотите изменить число хранимых файлов, добавьте в файл app значение для параметра log_max_files:

PHP
'log_max_files' => 30
+ 5.3 5.2

добавлено в 5.3 () 5.2 ()

Уровни важности событий

При использовании Monolog сообщения в журнале могут иметь разные уровни важности. По умолчанию Laravel сохраняет в журнал события всех уровней. Но на продакшн-сервере вы можете задать минимальный уровень важности, который необходимо заносить в журнал, добавив параметр conflog_level в файл app.php.

После задания этого параметра Laravel будет записывать события всех уровней начиная с указанного и выше. Например, при conflog_level равном error будут записываться события error, critical, alert и emergency:

conf'log_level' => env('APP_LOG_LEVEL', 'error'),

В Monolog используются следующие уровни важности — от меньшего к большему: debug, info, notice, warning, error, critical, alert, emergency.

Изменение настроек Monolog

Если вы хотите иметь полный контроль над конфигурацией Monolog для вашего приложения, вы можете использовать метод приложения PHPconfigureMonologUsing(). Вызов этого метода необходимо поместить в файл bootstrap/app.php прямо перед тем, как в нём возвращается переменная PHP$app:

PHP
$app->configureMonologUsing(function ($monolog) {
  
$monolog->pushHandler(...);
});

return 
$app;

Обработчик исключений

Метод PHPreport()

Все исключения обрабатываются классом App\Exceptions\Handler. Этот класс содержит два метода: PHPreport() и PHPrender(). Рассмотрим каждый из них подробнее. Метод PHPreport() используется для занесения исключений в журнал или для отправки их во внешний сервис, такой как BugSnag или Sentry. По умолчанию метод PHPreport() просто передаёт исключение в базовую реализацию родительского класса, где это исключение зафиксировано. Но вы можете регистрировать исключения как пожелаете.

Например, если вам необходимо сообщать о различных типах исключений разными способами, вы можете использовать оператор сравнения PHP PHPinstanceof::

PHP
/**
 * Сообщить или зарегистрировать исключение.
 *
 * Это отличное место для отправки исключений в Sentry, Bugsnag, и т.д.
 *
 * @param  \Exception  $exception
 * @return void
 */
public function report(Exception $exception)
{
  if (
$exception instanceof CustomException) {
    
//
  
}

  return 
parent::report($exception);
}

Игнорирование исключений заданного типа

Свойство обработчика исключений PHP$dontReport содержит массив с типами исключений, которые не будут заноситься в журнал. Например, исключения, возникающие при ошибке 404, а также при некоторых других типах ошибок, не записываются в журналы. При необходимости вы можете включить другие типы исключений в этот массив:

PHP
/**
 * Список типов исключений, о которых не надо сообщать.
 *
 * @var array
 */
protected $dontReport = [
  \
Illuminate\Auth\AuthenticationException::class,
  \
Illuminate\Auth\Access\AuthorizationException::class,
  \
Symfony\Component\HttpKernel\Exception\HttpException::class,
  \
Illuminate\Database\Eloquent\ModelNotFoundException::class,
  \
Illuminate\Validation\ValidationException::class,
];

Метод PHPrender()

Метод PHPrender() отвечает за конвертацию исключения в HTTP-отклик, который должен быть возвращён браузеру. По умолчанию исключение передаётся в базовый класс, который генерирует для вас отклик. Но вы можете проверить тип исключения или вернуть ваш собственный отклик:

PHP
/**
 * Отрисовка HTTP-оклика для исключения.
 *
 * @param  \Illuminate\Http\Request  $request
 * @param  \Exception  $exception
 * @return \Illuminate\Http\Response
 */
public function render($requestException $exception)
{
  if (
$exception instanceof CustomException) {
    return 
response()->view('errors.custom', [], 500);
  }

  return 
parent::render($request$exception);
}

HTTP-исключения

Некоторые исключения описывают коды HTTP-ошибок от сервера. Например, это может быть ошибка «страница не найдена» (404), «ошибка авторизации» (401) или даже сгенерированная разработчиком ошибка 500. Для возврата такого отклика из любого места в приложении можете использовать вспомогательный метод PHPabort():

PHP
abort(404);

Вспомогательный метод PHPabort() немедленно создаёт исключение, которое будет отрисовано обработчиком исключений. Или вы можете предоставить такой отклик:

PHP
abort(403'Unauthorized action.');

Свои страницы HTTP-ошибок

В Laravel можно легко возвращать свои собственные страницы для различных кодов HTTP-ошибок. Например, для выдачи собственной страницы для ошибки 404 создайте файл resources/views/errors/404.blade.php. Этот файл будет использован для всех ошибок 404, генерируемых вашим приложением. Представления в этой папке должны иметь имена, соответствующие кодам ошибок. Экземпляр HttpException, созданный функцией PHPabort(), будет передан в представление как переменная PHP$exception.

Журналы

Laravel обеспечивает простой простой уровень абстракции над мощной библиотекой Monolog. По умолчанию Laravel настроен на создание файла журнала в storage/logs. Вы можете записывать информацию в журнал при помощи фасада Log:

PHP
<?php

namespace App\Http\Controllers;

use 
Illuminate\Support\Facades\Log;
//для версии 5.2 и ранее:
//use Log;
use App\User;
use 
App\Http\Controllers\Controller;

class 
UserController extends Controller
{
  
/**
   * Показать профиль данного пользователя.
   *
   * @param  int  $id
   * @return Response
   */
  
public function showProfile($id)
  {
    
Log::info('Showing user profile for user: '.$id);

    return 
view('user.profile', ['user' => User::findOrFail($id)]);
  }
}

Регистратор событий предоставляет восемь уровней журналирования, описанных в RFC 5424: debug, info, notice, warning, error, critical, alert и emergency.

PHP
Log::emergency($message);
Log::alert($message);
Log::critical($message);
Log::error($message);
Log::warning($message);
Log::notice($message);
Log::info($message);
Log::debug($message);

Контекстная информация

Также в методы журналирования может быть передан массив контекстных данных:

PHP
Log::info('User failed to login.', ['id' => $user->id]);

Обращение к низкоуровневому экземпляру Monolog

В Monolog доступно множество дополнительных обработчиков для журналов. При необходимости вы можете получить доступ к низкоуровневому экземпляру Monolog, используемому в Laravel:

PHP
$monolog Log::getMonolog();
+ 5.0

добавлено в 5.0 ()

Вы также можете зарегистрировать событие для перехвата всех сообщений, передаваемых в журнал.

Регистрация слушателя событий журнала

PHP
Log::listen(function($level$message$context)
{
  
//
});

Комментарии (1)

Bavial

v5.5 При использовании режима daily, каждый новый файл создается с ограниченными правами и выпадает ошибка permission deny для этого нового файла. Исправляет только ручное изменение прав на каждый новый дневной файл

Написать комментарий

Разметка: ? ?

Авторизуйся, чтобы прокомментировать.