에러 처리 - Knowledge of Laravel

개요

Laravel 프로젝트를 생성하면 오류와 예외 처리는 미리 설정된 상태로 준비되어 있습니다. 커스터마이징은 bootstrap/app.php의 withExceptions 메서드에서 수행합니다.

예외 처리 흐름

예외가 발생하고 클라이언트에게 응답이 돌아갈 때까지의 흐름을 나타냅니다.

// bootstrap/app.php
use Illuminate\Foundation\Application;
use Illuminate\Foundation\Configuration\Exceptions;

return Application::configure(basePath: dirname(__DIR__))
    ->withExceptions(function (Exceptions $exceptions): void {
        // 예외 보고·렌더링을 여기서 설정한다
    })->create();

withExceptions 클로저에 전달되는 $exceptions 객체는 Illuminate\Foundation\Configuration\Exceptions의 인스턴스로, 애플리케이션 전체의 예외 핸들링을 관리합니다.

디버그 설정

config/app.php의 debug 옵션이 오류 정보 표시량을 제어합니다. 기본적으로는 .env의 APP_DEBUG 환경 변수 값이 사용됩니다.

# 로컬 개발
APP_DEBUG=true

# 프로덕션 환경
APP_DEBUG=false

프로덕션 환경에서는 APP_DEBUG를 반드시 false로 설정하세요. true 상태로 두면 기밀 정보가 최종 사용자에게 노출될 위험이 있습니다.

예외 리포팅

예외 리포팅이란 예외를 로그에 기록하거나 Laravel Nightwatch, Sentry, Flare 등의 외부 서비스에 전송하는 처리입니다. 기본적으로는 config/logging.php의 설정에 기반하여 로그에 기록됩니다.

커스텀 리포트 콜백

예외 종류에 따라 다른 리포트 처리를 하고 싶다면 report 메서드에 클로저를 전달합니다. Laravel은 클로저의 타입 힌트에서 예외 종류를 판단합니다.

use App\Exceptions\InvalidOrderException;

->withExceptions(function (Exceptions $exceptions): void {
    $exceptions->report(function (InvalidOrderException $e) {
        // 외부 서비스에 알림 등
    });
})

커스텀 콜백을 등록해도 기본 로그 기록은 계속됩니다. 기본으로의 전파를 멈추려면 stop()을 호출하거나 false를 반환합니다.

->withExceptions(function (Exceptions $exceptions): void {
    $exceptions->report(function (InvalidOrderException $e) {
        // ...
    })->stop();
})

`report()` 헬퍼

에러 페이지를 표시하지 않고 예외만 리포트하고 싶다면 report() 헬퍼를 사용합니다.

public function isValid(string $value): bool
{
    try {
        // 검증 처리...
    } catch (Throwable $e) {
        report($e);

        return false;
    }
}

report() 헬퍼는 사용자에 대한 응답을 중단하지 않고 오류를 기록할 수 있습니다. 백그라운드 잡이나 중요하지 않은 처리의 예외 처리에 편리합니다.

중복 리포트 방지

같은 예외 인스턴스가 여러 번 report()에 전달되면 로그에 중복 엔트리가 만들어질 수 있습니다. dontReportDuplicates()를 설정하면 같은 인스턴스는 최초 1회만 기록됩니다.

->withExceptions(function (Exceptions $exceptions): void {
    $exceptions->dontReportDuplicates();
})

$original = new RuntimeException('Whoops!');

report($original); // 기록됨

try {
    throw $original;
} catch (Throwable $caught) {
    report($caught); // 무시됨 (같은 인스턴스)
}

전역 로그 컨텍스트

모든 예외 로그에 공통 정보를 부여하고 싶다면 context 메서드를 사용합니다. 가능하다면 현재 사용자 ID는 자동으로 부여됩니다.

->withExceptions(function (Exceptions $exceptions): void {
    $exceptions->context(fn () => [
        'app_version' => config('app.version'),
    ]);
})

예외 클래스에 `context()` 메서드 추가

예외 클래스 자신에 context() 메서드를 정의하면, 그 예외에 고유한 컨텍스트 정보를 로그에 포함할 수 있습니다.

<?php

namespace App\Exceptions;

use Exception;

class InvalidOrderException extends Exception
{
    public function __construct(
        private readonly int $orderId,
        string $message = '',
    ) {
        parent::__construct($message);
    }

    /**
     * 예외의 컨텍스트 정보를 반환
     *
     * @return array<string, mixed>
     */
    public function context(): array
    {
        return ['order_id' => $this->orderId];
    }
}

로그 레벨 변경

특정 예외를 특정 로그 레벨로 기록하고 싶다면 level 메서드를 사용합니다.

use PDOException;
use Psr\Log\LogLevel;

->withExceptions(function (Exceptions $exceptions): void {
    $exceptions->level(PDOException::class, LogLevel::CRITICAL);
})

예외 리포트 스로틀링

대량의 예외가 발생하는 경우, throttle 메서드로 리포트 수를 제어할 수 있습니다.

use Illuminate\Support\Lottery;
use Throwable;

->withExceptions(function (Exceptions $exceptions): void {
    // 1000회에 1회만 랜덤으로 리포트
    $exceptions->throttle(function (Throwable $e) {
        return Lottery::odds(1, 1000);
    });
})

1분당 건수로 제한하고 싶다면 Limit을 사용합니다.

use Illuminate\Broadcasting\BroadcastException;
use Illuminate\Cache\RateLimiting\Limit;
use Throwable;

->withExceptions(function (Exceptions $exceptions): void {
    $exceptions->throttle(function (Throwable $e) {
        if ($e instanceof BroadcastException) {
            return Limit::perMinute(300);
        }
    });
})

예외 렌더링

렌더링이란 예외를 HTTP 응답으로 변환하는 처리입니다. 기본적으로는 Laravel이 자동으로 적절한 응답을 생성하지만, 커스터마이징도 가능합니다.

커스텀 렌더링 콜백

render 메서드에 클로저를 전달하여 예외를 응답으로 변환합니다.

use App\Exceptions\InvalidOrderException;
use Illuminate\Http\Request;

->withExceptions(function (Exceptions $exceptions): void {
    $exceptions->render(function (InvalidOrderException $e, Request $request) {
        return response()->view('errors.invalid-order', status: 500);
    });
})

내장된 예외(NotFoundHttpException 등)의 렌더링도 덮어쓸 수 있습니다. 클로저가 값을 반환하지 않는 경우 기본 렌더링이 사용됩니다.

use Illuminate\Http\Request;
use Symfony\Component\HttpKernel\Exception\NotFoundHttpException;

->withExceptions(function (Exceptions $exceptions): void {
    $exceptions->render(function (NotFoundHttpException $e, Request $request) {
        if ($request->is('api/*')) {
            return response()->json([
                'message' => 'Record not found.',
            ], 404);
        }
        // null을 반환하면 기본 404 페이지가 표시됨
    });
})

JSON / HTML 자동 판정

Laravel은 요청의 Accept 헤더에 기반하여 HTML과 JSON 중 어느 것으로 반환할지 자동 판정합니다. 이 판정 로직을 커스터마이징하고 싶다면 shouldRenderJsonWhen을 사용합니다.

use Illuminate\Http\Request;
use Throwable;

->withExceptions(function (Exceptions $exceptions): void {
    $exceptions->shouldRenderJsonWhen(function (Request $request, Throwable $e) {
        if ($request->is('admin/*')) {
            return true; // 관리 화면은 항상 JSON으로 반환
        }

        return $request->expectsJson();
    });
})

응답 전체 커스터마이징

respond 메서드를 사용하면 생성된 응답을 추가로 가공할 수 있습니다.

use Symfony\Component\HttpFoundation\Response;

->withExceptions(function (Exceptions $exceptions): void {
    $exceptions->respond(function (Response $response) {
        if ($response->getStatusCode() === 419) {
            return back()->with([
                'message' => '페이지 유효 기간이 만료되었습니다. 다시 시도해 주세요.',
            ]);
        }

        return $response;
    });
})

커스텀 예외 클래스

app/Exceptions/ 디렉터리에 자체 예외 클래스를 만들 수 있습니다. report() 메서드와 render() 메서드를 정의하면 bootstrap/app.php에 설정을 작성하지 않아도 자동으로 호출됩니다.

예외 클래스 작성

php artisan make:exception InvalidOrderException

report()와 render() 구현

<?php

namespace App\Exceptions;

use Exception;
use Illuminate\Http\Request;
use Illuminate\Http\Response;

class InvalidOrderException extends Exception
{
    public function __construct(
        private readonly int $orderId,
        string $message = 'Invalid order.',
    ) {
        parent::__construct($message);
    }

    /**
     * 예외를 리포트한다
     */
    public function report(): void
    {
        // 외부 서비스에 알림 등
    }

    /**
     * 예외를 HTTP 응답으로 변환한다
     */
    public function render(Request $request): Response
    {
        return response()->view('errors.invalid-order', [
            'orderId' => $this->orderId,
        ], 422);
    }
}

report() 메서드에는 타입 힌트로 의존성 주입을 사용할 수 있습니다. Laravel의 서비스 컨테이너가 자동으로 해결합니다.

`ShouldntReport` 인터페이스

리포트가 필요 없는 예외에는 ShouldntReport 인터페이스를 구현합니다. 이 인터페이스를 구현한 예외는 일절 리포트되지 않습니다.

<?php

namespace App\Exceptions;

use Exception;
use Illuminate\Contracts\Debug\ShouldntReport;

class PodcastProcessingException extends Exception implements ShouldntReport
{
    //
}

예외 던지기

`abort()` 헬퍼

애플리케이션의 어디에서든 HTTP 에러 응답을 발생시킬 수 있습니다.

// 404 Not Found
abort(404);

// 메시지 포함
abort(403, '이 작업을 수행할 권한이 없습니다.');

`abort_if()` / `abort_unless()`

조건부로 예외를 던지는 헬퍼입니다.

// $condition이 true일 때 abort
abort_if(! $user->isAdmin(), 403);

// $condition이 false일 때 abort
abort_unless($user->hasPermission('edit'), 403, 'Permission denied.');

컨트롤러나 미들웨어에서 권한 검사를 할 때 편리합니다. 게이트나 정책과 조합하여 사용되는 경우도 많습니다.

예외의 전역 제어

특정 예외 무시하기

리포트하지 않을 예외를 dontReport로 지정합니다. 렌더링의 커스텀 로직은 계속 기능합니다.

use App\Exceptions\InvalidOrderException;

->withExceptions(function (Exceptions $exceptions): void {
    $exceptions->dontReport([
        InvalidOrderException::class,
    ]);
})

조건부로 무시하고 싶다면 dontReportWhen에 클로저를 전달합니다.

use Throwable;

->withExceptions(function (Exceptions $exceptions): void {
    $exceptions->dontReportWhen(function (Throwable $e) {
        return $e instanceof PodcastProcessingException &&
               $e->reason() === 'Subscription expired';
    });
})

Laravel은 기본적으로 404 오류나 CSRF 토큰 부정(419), 오리진 불일치(403) 등 일부 예외를 자동으로 무시하고 있습니다.

Laravel이 무시하고 있는 예외 활성화

기본으로 무시되는 예외를 리포트 대상으로 되돌리려면 stopIgnoring을 사용합니다.

use Symfony\Component\HttpKernel\Exception\HttpException;

->withExceptions(function (Exceptions $exceptions): void {
    $exceptions->stopIgnoring(HttpException::class);
})

HTTP 에러 페이지

Laravel에서는 HTTP 상태 코드별로 커스텀 에러 뷰를 정의할 수 있습니다.

커스텀 에러 뷰 작성

resources/views/errors/ 디렉터리에 상태 코드를 파일명으로 한 Blade 템플릿을 작성합니다.

resources/
└── views/
    └── errors/
        ├── 404.blade.php
        ├── 403.blade.php
        └── 500.blade.php

뷰 안에서는 $exception 변수를 사용하여 에러 정보에 접근할 수 있습니다.

{{-- resources/views/errors/404.blade.php --}}
<!DOCTYPE html>
<html lang="ko">
<head>
    <meta charset="UTF-8">
    <title>페이지를 찾을 수 없습니다</title>
</head>
<body>
    <h1>404 - 페이지를 찾을 수 없습니다</h1>
    <p>{{ $exception->getMessage() }}</p>
    <a href="{{ url('/') }}">홈으로 돌아가기</a>
</body>
</html>

기본 에러 템플릿 배포

Laravel 표준 에러 페이지를 커스터마이징의 출발점으로 사용하고 싶다면 vendor:publish로 가져옵니다.

php artisan vendor:publish --tag=laravel-errors

폴백 에러 페이지

특정 상태 코드에 대응하는 뷰가 없을 경우의 폴백으로, 4xx.blade.php와 5xx.blade.php를 만들 수 있습니다.

resources/
└── views/
    └── errors/
        ├── 4xx.blade.php  # 400번대의 폴백
        └── 5xx.blade.php  # 500번대의 폴백

404, 500, 503에 대해서는 Laravel이 기본 에러 페이지를 준비합니다. 이것들을 커스터마이징하려면 폴백이 아니라 개별 파일(404.blade.php 등)을 만드세요.

실전 예: API 예외 핸들러

API를 제공하는 애플리케이션에서는 예외를 항상 JSON으로 반환해야 합니다. 다음은 bootstrap/app.php에서 API 에러를 일원 관리하는 구현 예입니다.

use Illuminate\Auth\AuthenticationException;
use Illuminate\Http\Request;
use Illuminate\Validation\ValidationException;
use Symfony\Component\HttpKernel\Exception\NotFoundHttpException;

->withExceptions(function (Exceptions $exceptions): void {
    // API 요청에는 항상 JSON으로 반환
    $exceptions->render(function (NotFoundHttpException $e, Request $request) {
        if ($request->is('api/*')) {
            return response()->json([
                'message' => '리소스를 찾을 수 없습니다.',
            ], 404);
        }
    });

    $exceptions->render(function (AuthenticationException $e, Request $request) {
        if ($request->is('api/*')) {
            return response()->json([
                'message' => '인증이 필요합니다.',
            ], 401);
        }
    });

    $exceptions->render(function (ValidationException $e, Request $request) {
        if ($request->is('api/*')) {
            return response()->json([
                'message' => '검증 오류.',
                'errors'  => $e->errors(),
            ], 422);
        }
    });
})

커스텀 API 예외 클래스 구현

API 전용 기본 예외 클래스를 만들면, 각 엔드포인트에서 통일된 에러 응답을 반환할 수 있습니다.

<?php

namespace App\Exceptions;

use Exception;
use Illuminate\Http\JsonResponse;
use Illuminate\Http\Request;

class ApiException extends Exception
{
    public function __construct(
        string $message = 'An error occurred.',
        private readonly int $statusCode = 500,
        private readonly array $errors = [],
    ) {
        parent::__construct($message);
    }

    public function render(Request $request): JsonResponse
    {
        $data = ['message' => $this->getMessage()];

        if (! empty($this->errors)) {
            $data['errors'] = $this->errors;
        }

        return response()->json($data, $this->statusCode);
    }
}

컨트롤러에서의 사용 예입니다.

<?php

namespace App\Http\Controllers\Api;

use App\Exceptions\ApiException;
use App\Models\Order;

class OrderController extends Controller
{
    public function show(int $id): JsonResponse
    {
        $order = Order::find($id);

        if (! $order) {
            throw new ApiException('주문을 찾을 수 없습니다.', 404);
        }

        if ($order->isCancelled()) {
            throw new ApiException('이 주문은 취소되었습니다.', 422);
        }

        return response()->json($order);
    }
}

정리

예외 리포트 정리

방법	용도
`$exceptions->report()`	예외 종류별로 커스텀 리포트 로직 등록
`$exceptions->context()`	모든 예외 로그에 공통 정보 부여
`context()` 메서드	예외 클래스 자신에 고유한 컨텍스트를 가지게 함
`report()` 헬퍼	응답을 중단하지 않고 예외만 리포트
`dontReportDuplicates()`	같은 인스턴스의 중복 리포트 방지
`ShouldntReport` 인터페이스	일절 리포트하지 않는 예외 클래스 작성

예외 렌더링 정리

방법	용도
`$exceptions->render()`	예외 종류별로 커스텀 응답을 반환
`render()` 메서드	예외 클래스 자신에 렌더링 로직을 가지게 함
`shouldRenderJsonWhen()`	JSON/HTML 판정 로직 커스터마이징
`respond()`	생성된 응답을 추가로 가공

HTTP 에러 페이지 정리

resources/views/errors/404.blade.php 등의 파일을 만드는 것만으로 자동으로 사용됨
$exception 변수로 에러의 상세에 접근 가능
php artisan vendor:publish --tag=laravel-errors로 기본 템플릿 취득 가능
4xx.blade.php / 5xx.blade.php로 폴백 페이지 정의 가능

프로덕션 환경에서의 모범 사례

APP_DEBUG=false를 반드시 설정하고 스택 트레이스를 사용자에게 보이지 않기
Sentry나 Flare 등의 외부 에러 추적 서비스와 연동하여 에러를 일원 관리
throttle()을 사용하여 대량의 예외가 발생했을 때의 로그 넘침 방지
API 엔드포인트에서는 일관된 JSON 에러 응답 형식 유지

​개요

​예외 처리 흐름

​디버그 설정

​예외 리포팅

​커스텀 리포트 콜백

​report() 헬퍼

​중복 리포트 방지

​전역 로그 컨텍스트

​예외 클래스에 context() 메서드 추가

​로그 레벨 변경

​예외 리포트 스로틀링

​예외 렌더링

​커스텀 렌더링 콜백

​JSON / HTML 자동 판정

​응답 전체 커스터마이징

​커스텀 예외 클래스

​예외 클래스 작성

​ShouldntReport 인터페이스

​예외 던지기

​abort() 헬퍼

​abort_if() / abort_unless()

​예외의 전역 제어

​특정 예외 무시하기

​Laravel이 무시하고 있는 예외 활성화

​HTTP 에러 페이지

​커스텀 에러 뷰 작성

​기본 에러 템플릿 배포

​폴백 에러 페이지

​실전 예: API 예외 핸들러

​커스텀 API 예외 클래스 구현

​정리

개요

예외 처리 흐름

디버그 설정

예외 리포팅

커스텀 리포트 콜백

`report()` 헬퍼

중복 리포트 방지

전역 로그 컨텍스트

예외 클래스에 `context()` 메서드 추가

로그 레벨 변경

예외 리포트 스로틀링

예외 렌더링

커스텀 렌더링 콜백

JSON / HTML 자동 판정

응답 전체 커스터마이징

커스텀 예외 클래스

예외 클래스 작성

`ShouldntReport` 인터페이스

예외 던지기

`abort()` 헬퍼

`abort_if()` / `abort_unless()`

예외의 전역 제어

특정 예외 무시하기

Laravel이 무시하고 있는 예외 활성화

HTTP 에러 페이지

커스텀 에러 뷰 작성

기본 에러 템플릿 배포

폴백 에러 페이지

실전 예: API 예외 핸들러

커스텀 API 예외 클래스 구현

정리