Исключения в Laravel: методы обработки ошибок от простых до продвинутых

Расширенные примеры работы с исключениями в Laravel демонстрируют более специфические сценарии и комбинации описанных выше подходов.

Пример 1: Кастомное исключение для API с поддержкой локализации

Создайте исключение, которое принимает код ошибки и динамически формирует сообщение на основе локали пользователя.

// app/Exceptions/ApiException.php
namespace App\Exceptions;

use Exception;

class ApiException extends Exception
{
    public $statusCode;
    public $errorCode;

    public function __construct(string $errorCode, int $statusCode = 400, $message = null)
    {
        $this->errorCode = $errorCode;
        $this->statusCode = $statusCode;
        $message = $message ?: __('errors.'.$errorCode);
        parent::__construct($message, $statusCode);
    }
}

// resources/lang/en/errors.php
return [
    'user_not_found' => 'User not found.',
    'invalid_token' => 'Invalid or expired token.',
];

// В Handler::register
$this->renderable(function (ApiException $e, $request) {
    return response()->json([
        'error' => $e->errorCode,
        'message' => $e->getMessage()
    ], $e->statusCode);
});

// Использование в контроллере
throw new ApiException('user_not_found', 404);

// Ответ клиенту:
{
  "error": "user_not_found",
  "message": "User not found."
}

Этот подход удобен для API с международной поддержкой и единой структурой ошибок.

Пример 2: Обработка исключений очередей с уведомлениями

В классе Handler можно перехватывать исключения из очередей, используя метод reportable с проверкой окружения.

use Illuminate\Queue\MaxAttemptsExceededException;
use Illuminate\Support\Facades\Log;

// В register()
$this->reportable(function (MaxAttemptsExceededException $e) {
    Log::channel('slack')->warning('Job failed after max attempts', [
        'job' => get_class($e->job),
        'exception' => $e->getPrevious()?->getMessage()
    ]);
});

// В самом классе Job можно также использовать метод failed()

Такой подход позволяет централизованно отслеживать сбои в фоновых задачах.

Пример 3: Использование макросов для Handler

Laravel позволяет добавлять макросы к классу Handler через сервис-провайдер, что удобно для модульных расширений.

// AppServiceProvider.php
use App\Exceptions\Handler;
use Illuminate\Support\Facades\Log;

public function boot()
{
    Handler::macro('reportToExternalService', function (Throwable $e) {
        // Отправка в внешний сервис мониторинга
        Log::channel('external')->error($e->getMessage(), ['trace' => $e->getTraceAsString()]);
    });
}

// В Handler::register
$this->reportable(function (Throwable $e) {
    $this->reportToExternalService($e);
});

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

Пример 4: Тестирование исключений с помощью assertThrows

В тестах Laravel можно проверить, что определённая операция выбрасывает нужное исключение, используя PHPUnit или встроенные методы.

// tests/Feature/ApiExceptionTest.php
public function test_user_not_found_throws_api_exception()
{
    $this->expectException(\App\Exceptions\ApiException::class);
    $this->expectExceptionMessage('User not found.');

    $this->get('/api/user/99999');
}

// Альтернативный метод:
$response = $this->get('/api/user/99999');
$response->assertStatus(404);
$response->assertJson(['error' => 'user_not_found']);

// Результат теста (зелёная галочка): все ассерты проходят.

Такой подход гарантирует, что обработка исключений работает корректно.

Пример 5: Глобальный обработчик через middleware

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

// app/Http/Middleware/ExceptionLogger.php
namespace App\Http\Middleware;

use Closure;
use Illuminate\Support\Facades\Log;
use Throwable;

class ExceptionLogger
{
    public function handle($request, Closure $next)
    {
        try {
            return $next($request);
        } catch (Throwable $e) {
            Log::channel('sentry')->error($e->getMessage(), [
                'url' => $request->fullUrl(),
                'method' => $request->method()
            ]);
            throw $e; // Повторно выбрасываем для обработки Handler
        }
    }
}

// Зарегистрировать в kernel.php
protected $middlewareGroups = [
    'web' => [
        \App\Http\Middleware\ExceptionLogger::class,
        // ...
    ],
];

Этот middleware логирует все исключения, проходящие через маршруты группы web, и затем передаёт их дальше.