Отловить ошибку laravel

Обычно веб-разработчики не следят за ошибками. Если что-то идет не так, то мы частенько видим дефолтный текст ошибки Laravel: «Whoops, something went wrong» или, что еще хуже, код исключения, который посетителю совсем ни к чему. Поэтому я решил написать пошаговую статью о том, как элегантно обрабатывать ошибки и показывать посетителю правильную информацию о произошедшем.

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

Подготовка: Задача поиска пользователя

Итак, у нас есть очень простой пример — форма для поиска пользователя по его идентификатору.

У нас есть два маршрута:

Route::get('/users', 'UserController@index')->name('users.index');
Route::post('/users/search', 'UserController@search')->name('users.search');

И контроллер с двумя методами:

class UserController extends Controller
{

    public function index()
    {
        return view('users.index');
    }

    public function search(Request $request)
    {
        $user = User::find($request->input('user_id'));
        return view('users.search', compact('user'));
    }

}

В файле resources/views/users/index.blade.php находится сама форма:

<form action="{{ route('users.search') }}" method="POST">
@csrf
<div class="form-group">
<input id="user_id" class="form-control" name="user_id" type="text" value="{{ old('user_id') }}" placeholder="User ID">
</div>
<input class="btn btn-info" type="submit" value="Search">
</form>

Если мы ищем существующего пользователя и он найден, мы видим такой результат:

Всё это находится в resources/views/users/search.blade.php:

<h3 class="page-title text-center">User found: {{ $user->name }}</h3>
<b>Email</b>: {{ $user->email }}
<br>
<b>Registered on</b>: {{ $user->created_at }}

Но это в идеальном случае, а что, если пользователь не найден?

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

Давайте вернемся в реальный мир. Мы не проверяем существование пользователя, в контроллере мы только делаем:

$user = User::find($request->input('user_id'));

И, если пользователь не найден, то получим это:

Или, понятное дело, мы можем задать APP_DEBUG=false в файле .env, и тогда браузер просто покажет пустую страницу с «Whoops, looks like something went wrong». Но для нашего посетителя все это совершенно бесполезно.

Еще одно быстрое исправление, которое мы можем сделать, это использовать User::findOrFail() вместо просто find() — тогда, если пользователь не найден, Laravel покажет страницу 404 с текстом «Sorry, the page you are looking for could not be found». Но это дефолтная страница ошибки для всего сайта. Для посетителя она, опять таки, бесполезна.

Поэтому нам нужно отлавливать ошибки, обрабатывать их и перенаправлять обратно в форму с действительно понятным сообщением об ошибке.

Нам нужно знать тип исключения и имя класса, которое оно будет возвращать. В случае с findOrFail() будет выдано Eloquent исключение ModelNotFoundException, поэтому нам нужно сделать так:

public function search(Request $request)
{
    try {
        $user = User::findOrFail($request->input('user_id'));
    } catch (ModelNotFoundException $exception) {
        return back()->withError($exception->getMessage())->withInput();
    }
    return view('users.search', compact('user'));
}

Теперь давайте покажем ошибку в Blade:

<h3 class="page-title text-center">Search for user by ID</h3>

@if (session('error'))
<div class="alert alert-danger">{{ session('error') }}</div>
@endif

<form action="{{ route('users.search') }}" method="POST">...</form>

Результат:

Отлично, мы отобразили ошибку! Но это еще не идеал, верно? Вместо $exception->getMessage() нам нужно показать наше собственное сообщение:

return back()->withError('User not found by ID ' . $request->input('user_id'))->withInput();

Финальный вариант!

Перемещаем обработку ошибок в Сервис

На данный момент мы взяли очень простой пример одного действия в контроллере — поиск пользователя. В реальном приложении все гораздо сложнее — обычно контроллер вызывает какой-нибудь внешний сервис или метод пакета, которые могут завершиться с какими-угодно ошибками.

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

Давайте переместим нашу логику в app/Services/UserService.php:

namespace App\Services;

use App\User;
use Illuminate\Database\Eloquent\ModelNotFoundException;

class UserService
{

    public function search($user_id)
    {
        $user = User::find($user_id);
        if (!$user) {
            throw new ModelNotFoundException('User not found by ID ' . $user_id);
        }
        return $user;
    }

}

А в контроллере нам нужно вызвать этот сервис. Для начала мы внедрим его в метод __construct():

use App\Services\UserService;

class UserController extends Controller
{

    private $userService;

    public function __construct(UserService $userService)
    {
        $this->userService = $userService;
    }

// ...

Если вы не знакомы с внедрением зависимостей и как работает контейнер Laravel IOC, то вот официальная документация.

А вот так теперь выглядит наш метод search():

public function search(Request $request)
{
    try {
        $user = $this->userService->search($request->input('user_id'));
    } catch (ModelNotFoundException $exception) {
        return back()->withError($exception->getMessage())->withInput();
    }
    return view('users.search', compact('user'));
}

Обратите внимание, мы снова можем использовать $exception->getMessage(), вся проверка ошибок и логика сообщений происходит внутри службы. Мы удалили это из контроллера, он не должен заниматься этим.

Следующий Шаг: Создание собственного класса исключений

Последняя глава этой статьи посвящена улучшению архитектуры. Это когда ваш сервис генерирует свое собственное исключение, связанное с этой конкретной ошибкой, и, в зависимости от ошибки, может быть несколько классов исключений. Хорошим примером такой архитектуры является библиотека Stripe, ее использование выглядит так:

try {
  // Use Stripe's library to make requests...
} catch(\Stripe\Error\Card $e) {
  // Since it's a decline, \Stripe\Error\Card will be caught
  $body = $e->getJsonBody();
  $err  = $body['error'];

  print('Status is:' . $e->getHttpStatus() . "\n");
  print('Type is:' . $err['type'] . "\n");
  print('Code is:' . $err['code'] . "\n");
  // param is '' in this case
  print('Param is:' . $err['param'] . "\n");
  print('Message is:' . $err['message'] . "\n");
} catch (\Stripe\Error\RateLimit $e) {
  // Too many requests made to the API too quickly
} catch (\Stripe\Error\InvalidRequest $e) {
  // Invalid parameters were supplied to Stripe's API
} catch (\Stripe\Error\Authentication $e) {
  // Authentication with Stripe's API failed
  // (maybe you changed API keys recently)
} catch (\Stripe\Error\ApiConnection $e) {
  // Network communication with Stripe failed
} catch (\Stripe\Error\Base $e) {
  // Display a very generic error to the user, and maybe send
  // yourself an email
} catch (Exception $e) {
  // Something else happened, completely unrelated to Stripe
}

Итак, как мы можем создать наш собственный класс исключений? Очень просто — с помощью команды Artisan:

php artisan make:exception UserNotFoundException

Сгенерируется app/Exceptions/UserNotFoundException.php:

namespace App\Exceptions;

use Exception;

class UserNotFoundException extends Exception
{
    //
}

Здесь же ничего нет, верно? Давайте заполним наше исключение логикой.
В этом классе может быть два метода:

• report() — используется, если вы хотите сделать дополнительную запись в журнал — отправить сообщение об ошибке в BugSnag, на почту, в Slack и т. д.
• render() — используется, если вы хотите сделать редирект с ошибкой или вернуть HTTP-ответ (например, свой собственный файл Blade ) непосредственно из класса Exception

Итак, для этого примера мы cделаем метод report():

namespace App\Exceptions;

use Exception;

class UserNotFoundException extends Exception
{
    /**
     * Report or log an exception.
     *
     * @return void
     */
    public function report()
    {
        \Log::debug('User not found');
    }
}

А вот так мы вызываем это исключение из контроллера:

public function search(Request $request)
{
    try {
        $user = $this->userService->search($request->input('user_id'));
    } catch (UserNotFoundException $exception) {
        report($exception);
        return back()->withError($exception->getMessage())->withInput();
    }
    return view('users.search', compact('user'));
}

Итак, это всё, что я хотел рассказать вам об обработке исключений и использовании Сервисов.

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

Подробнее об исключениях и обработке ошибок: официальная документация Laravel.

Автор: Povilas Korop
Перевод: Алексей Широков

Задать вопросы по урокам можно на нашем форуме.

Что такое исключения в Laravel

Исключения — это ошибки, возникающие во время выполнения программы и нарушающие нормальный поток управления. Например, попытка доступа к несуществующему свойству объекта, деление на ноль или вызов функции с недопустимыми аргументами — это всё примеры исключений.

Исключения могут создавать сами механизмы PHP (например, ParseError или TypeError) или кодом приложения (например, InvalidArgumentException или ModelNotFoundException). Исключение также могут быть определены пользователем путём расширения базового класса Exception или любого из его подклассов.

Как Laravel обрабатывает исключения

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

По умолчанию Laravel преобразует все исключения в HTTP ответы с соответствующими кодами состояния и сообщениями об ошибках. Например, исключение 404 Not Found приведёт к HTTP-ответу с кодом состояния 404 и сообщением Not Found. Исключение 500 Internal Server Error приведёт к HTTP-ответу с кодом состояния 500 и сообщением Whoops, something went wrong.

Laravel также предоставляет удобный способ отображения пользовательских страниц ошибок для разных кодов состояния HTTP. Например, вы можете создать файл resources/views/errors/404.blade.php, чтобы настроить страницу ошибки 404. Вы можете использовать любые функции шаблона Blade на своих страницах ошибок, такие как макеты, компоненты и хелперы.

Как выбрасывать исключения в Laravel

Иногда вам может потребоваться генерировать/выбросить исключение вручную в коде приложения, чтобы указать, что что-то пошло не так или что какое-то условие не было выполнено. Например, вы можете создать исключение, если пользователь попытается получить права доступа к ресурсу, на просмотр которого у него нет прав.

Чтобы выбросить исключение в Laravel, вы можете использовать ключевое слово throw, за которым следует экземпляр класса исключения. Например:

public function show($id)
{
    $post = Post::find($id);

    if ($post == null) {
        // Выбросить исключение, если статья не существует
        throw new ModelNotFoundException('Post not found');
    }

    if (Auth::user()->cannot('view', $post)) {
        // Выбросить исключение, если пользователь не авторизован для просмотра статьи
        throw new AuthorizationException('You are not allowed to view this post');
    }

    return view('posts.show', compact('post'));
}

Вы также можете использовать хелпер abort() для выбрасывания исключения, чтобы создать исключение с заданным кодом HTTP состояния и дополнительным сообщением. Например:

public function update(Request $request, $id)
{
    $post = Post::find($id);

    if ($post == null) {
        // Прервать с кодом состояния 404 и пользовательским сообщением
        abort(404, 'Post not found');
    }

    if (Auth::user()->cannot('update', $post)) {
        // Прервать с кодом состояния 403 и сообщением по умолчанию
        abort(403);
    }

    // Обновить статью ...
}

Как перехватывать исключения в Laravel

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

Чтобы перехватить исключения в Laravel, вы можете использовать блоки try-catch-finally. Блок try содержит код, который может вызвать исключение. Блок catch содержит код, который будет выполняться, если возникнет исключение. Блок finally содержит код, который всегда будет выполняться независимо от того, выброшено исключение или нет. Например:

try {
    // Пробуем списать деньги с кредитной карты пользователя ...
} catch (PaymentFailedException $e) {
    // Ловим и обрабатываем исключение сбоя платежа ...
} finally {
    // Всегда высвобождайте ресурсы ...
}

Как настроить обработку исключений в Laravel

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

Класс Handler имеет два метода: report и render. Метод report отвечает за регистрацию исключения или отправку его во внешний сервис, например Bugsnag or Sentry. Метод render отвечает за преобразование исключения в HTTP-ответ, который будет отправлен обратно пользователю.

Вы можете переопределить эти методы в своём классе Handler, чтобы настроить их поведение. Например, вы можете добавить некую дополнительную логику в метод report, чтобы сохранять в лог дополнительную информацию или отправлять уведомление по электронной почте:

public function report(Throwable $exception)
{
    // Вызов родительского метода report
    parent::report($exception);

    // Добавьте немного пользовательской логики
    if ($exception instanceof PaymentFailedException) {
        // Сохраняем в лог дополнительную информацию
        Log::info('Payment failed for user ' . Auth::id());

        // Отправляем уведомление по e-mail
        Mail::to(Auth::user())->send(new PaymentFailedNotification($exception));
    }
}

Также вы можете изменить метод render, чтобы изменить способ отображения исключения для пользователя. Например, вы можете вернуть пользовательский JSON-ответ для API запросов:

public function render($request, Throwable $exception)
{
    // Если request ожидает JSON
    if ($request->expectsJson()) {
        // Возвращаем пользовательский JSON-ответ
        return response()->json([
            'error' => $exception->getMessage(),
            'code' => $exception->getCode(),
        ], $exception->getStatusCode());
    }

    // В противном случае, вызываем родительский метод render
    return parent::render($request, $exception);
}

Как зарегистрировать пользовательские обработчики исключений в Laravel

Другой способ настроить обработку исключений в Laravel — зарегистрировать пользовательские обработчики исключений с помощью метода register класса Handler. Этот метод позволяет определить замыкание, которое будет выполняться при возникновении исключений определённого типа.

Например, вы можете зарегистрировать собственный обработчик для ValidationException, который будет перенаправлять пользователя обратно на предыдущую страницу с ошибками валидации:

public function register()
{
    // Регистрируем пользовательский обработчик для  ValidationException
    $this->renderable(function (ValidationException $e, $request) {
        // Если request ожидает JSON
        if ($request->expectsJson()) {
            // Возвращаем JSON-ответ с ошибками валидации
            return response()->json($e->errors(), $e->status);
        }

        // В противном случае, перенаправляем обратно с ошибками валидации
        return redirect()->back()->withInput()->withErrors($e->errors());
    });
}

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

public function register()
{
    // Регистрируем пользовательский обработчик для ModelNotFoundException
    $this->renderable(function (ModelNotFoundException $e, $request) {
        // Возвращаем ответ 404 с пользовательским сообщением
        return response()->view('errors.model', [
            'message' => 'The requested model was not found',
        ], 404);
    });
}

Заключение

В этой статье мы узнали несколько советов и приёмов, как эффективно обрабатывать исключения в Laravel. Мы увидели, как создавать и перехватывать исключения вручную, как настраивать обработку исключений с помощью класса Handler и как регистрировать пользовательские обработчики исключений.

Система обработки ошибок и исключений Laravel — одна из самых мощных функций, которая делает разработку веб-приложений проще и приятнее. Освоив эту систему, вы сможете создавать надёжные и удобные для пользователя приложения, способные корректно справляться с любыми непредвиденными ситуациями.