PHP 예외: throw와 사용자 정의 예외 클래스

PHP에서는 throw new Exception('message');로 예외를 던집니다. 실행은 그 줄에서 멈추고 예외의 타입을 받아들이는 가장 가까운 catch 블록으로 넘어가며, 그곳에서 $e->getMessage()가 메시지를 반환합니다. 호출한 쪽이 문제를 구별할 수 있도록 InvalidArgumentException 같은 구체적인 클래스를 쓰세요.

<?php
function setQuantity(int $qty): string
{
    if ($qty < 1) {
        throw new InvalidArgumentException("Quantity must be at least 1, got $qty");
    }
    return "Quantity set to $qty";
}

try {
    echo setQuantity(3), "\n";
    echo setQuantity(0), "\n";
} catch (InvalidArgumentException $e) {
    echo 'Rejected: ', $e->getMessage(), "\n";
}

예외는 객체입니다. throw는 그것을 호출 스택 위로 올려 보내 일치하는 catch가 있는 첫 번째 호출자에게 전달하고, 그 호출자가 무엇을 할지 정합니다. 문제를 발견한 함수는 그것을 알 필요가 없습니다. 잡는 방법, finally, 여러 타입 잡기는 try catch 페이지에 있습니다.

예외 객체에 담긴 것

모든 예외는 메시지, 정수 코드, 만들어진 파일과 줄, 스택 트레이스를 가집니다. 생성자는 ($message, $code, $previous)를 받으며 모두 선택 사항입니다.

<?php
function findOrder(int $id): array
{
    throw new RuntimeException("Order $id not found", 404);
}

try {
    findOrder(77);
} catch (RuntimeException $e) {
    echo 'Class:   ', get_class($e), "\n";
    echo 'Message: ', $e->getMessage(), "\n";
    echo 'Code:    ', $e->getCode(), "\n";
    echo 'File:    ', basename($e->getFile()), "\n";
    echo 'Line:    ', $e->getLine(), "\n";
    echo "Trace:\n", $e->getTraceAsString(), "\n";
}

getLine()은 catch의 줄이 아니라 throw new의 줄입니다. 트레이스는 그곳에 이르기까지의 호출을 나열하며(#0 /home/index.php(8): findOrder()), 로그에 에러가 나타났을 때 보통 가장 먼저 읽는 것입니다. 예외를 문자열로 바꾸면(echo $e; 또는 (string) $e) PHP의 표준 형식으로 전부 출력됩니다.

내장 예외 클래스

PHP는 표준 PHP 라이브러리(SPL)에 예외 클래스 가족을 담고 있습니다. 문제를 이름으로 말해 주는 것을 던지면 코드가 더 잘 읽히고 호출한 쪽이 좁게 잡을 수 있습니다. 모두 Exception을 상속합니다.

InvalidArgumentException, DomainException, LengthException, OutOfRangeException은 LogicException을 상속하고, OutOfBoundsException, RangeException, UnexpectedValueException은 RuntimeException을 상속합니다. 어떤 클래스의 부모든 직접 확인할 수 있습니다.

<?php
foreach ([InvalidArgumentException::class, RangeException::class, JsonException::class, TypeError::class] as $class) {
    echo $class, ' -> ', implode(' -> ', class_parents($class)), "\n";
}

$e = new OutOfRangeException('Index 9 is out of range');
var_dump($e instanceof LogicException, $e instanceof RuntimeException, $e instanceof Throwable);

TypeError의 부모는 Exception이 아니라 Error입니다. 아래의 두 번째 가족에 속합니다.

PHP가 직접 던지는 에러

PHP 7부터, 그리고 PHP 8부터는 훨씬 더, PHP 자체의 함수와 연산자는 예전에 경고였던 문제에 대해 Error 하위 클래스를 던집니다. 같은 방식으로 잡지만 catch (Exception $e)는 일치하지 않습니다.

<?php
declare(strict_types=1);

$cases = [
    'intdiv by zero'  => fn () => intdiv(10, 0),
    'modulo by zero'  => fn () => 7 % 0,
    'wrong arg type'  => fn () => str_repeat(5, 2),
    'invalid value'   => fn () => array_fill(0, -1, 'x'),
    'too few args'    => fn () => (fn (int $a, int $b) => $a + $b)(1),
    'no match arm'    => fn () => match (99) { 1 => 'one', 2 => 'two' },
    'undefined func'  => fn () => undefined_function(),
];

foreach ($cases as $label => $run) {
    try {
        $run();
    } catch (Error $e) {
        printf("%-16s %-22s %s\n", $label, get_class($e), $e->getMessage());
    }
}

DivisionByZeroError, TypeError, ValueError, ArgumentCountError, UnhandledMatchError, 그리고 그냥 Error는 모두 Error를 상속합니다. 각각은 잘못된 데이터보다 호출하는 코드의 버그를 가리키는 경우가 많으며, 그래서 Exception 트리 밖에 있습니다. str_repeat(5, 2)를 TypeError로 만드는 것은 declare(strict_types=1)입니다. 없으면 PHP가 5를 "5"로 변환합니다.

사용자 정의 예외 클래스 만들기

한 줄짜리 하위 클래스로 충분한 경우가 많습니다. 클래스 이름 자체가 의미를 담고, 호출한 쪽은 정확히 그 타입을 잡을 수 있습니다. 잡는 쪽에 데이터(어떤 주문, 어떤 금액)가 필요하면 속성을 추가하고 parent::__construct()로 메시지를 넘기세요.

<?php
class PaymentException extends RuntimeException {}

class InsufficientFundsException extends PaymentException
{
    public function __construct(
        public readonly int $balanceCents,
        public readonly int $neededCents,
    ) {
        parent::__construct(sprintf(
            'Insufficient funds: balance %.2f, needed %.2f',
            $balanceCents / 100,
            $neededCents / 100,
        ), 402);
    }

    public function shortfall(): int
    {
        return $this->neededCents - $this->balanceCents;
    }
}

function pay(int $balance, int $amount): string
{
    if ($amount > $balance) {
        throw new InsufficientFundsException($balance, $amount);
    }
    return 'paid';
}

try {
    echo pay(5000, 1200), "\n";
    echo pay(5000, 8000), "\n";
} catch (InsufficientFundsException $e) {
    echo $e->getMessage(), "\n";
    echo 'Top up at least ', $e->shortfall() / 100, " EUR (code {$e->getCode()})\n";
} catch (PaymentException $e) {
    echo 'Payment failed: ', $e->getMessage(), "\n";
}

부모는 신중하게 고르세요. 그냥 Exception이 아니라 RuntimeException을 상속하면 RuntimeException을 잡는 코드가 여러분의 예외도 처리합니다. 라이브러리나 모듈마다 기반 예외 하나와 그 아래 구체적인 하위 클래스를 둔 작은 계층 구조는 호출한 쪽이 "결제 관련은 모두 잡기"와 "이 경우만 잡기" 중에서 고르게 해 줍니다.

previous로 예외 연결하기

저수준 예외를 잡고 상위 수준 예외를 던질 때, 원래 예외를 세 번째 인수로 넘기세요. 아무것도 잃지 않습니다. getPrevious()가 근본 원인까지 거슬러 올라갑니다.

<?php
class ImportException extends RuntimeException {}

function parseRow(string $line, int $n): array
{
    $cols = str_getcsv($line);
    if (count($cols) !== 3) {
        throw new UnexpectedValueException("row $n has " . count($cols) . ' columns, expected 3');
    }
    return $cols;
}

function import(array $lines): int
{
    foreach ($lines as $i => $line) {
        try {
            parseRow($line, $i + 1);
        } catch (UnexpectedValueException $e) {
            throw new ImportException('customers.csv could not be imported', 0, $e);
        }
    }
    return count($lines);
}

try {
    import(['Ada,ada@example.com,UK', 'Linus,linus@example.com']);
} catch (ImportException $e) {
    $level = 0;
    for ($x = $e; $x !== null; $x = $x->getPrevious()) {
        echo str_repeat('  ', $level++), get_class($x), ': ', $x->getMessage(), "\n";
    }
}

사용자는 "customers.csv could not be imported"를 보고, 체인을 따라가는 로그는 "row 2 has 2 columns"도 얻습니다. 연결된 예외가 끝내 잡히지 않으면 PHP의 치명적 에러가 체인 전체를 출력합니다. 원래 원인이 먼저, 그다음 각 감싼 예외가 Next 줄 아래에 나옵니다.

표현식으로서의 throw

PHP 8.0부터 throw는 표현식이므로 값이 와야 하는 곳 어디에나 둘 수 있습니다. ?? 뒤, 삼항 연산자 안, 화살표 함수 안입니다. "이것을 얻거나 실패하기"를 한 줄로 만듭니다.

<?php
$config = ['host' => 'localhost', 'port' => '5432'];

function setting(array $config, string $key): string
{
    return $config[$key] ?? throw new OutOfBoundsException("Missing setting '$key'");
}

echo setting($config, 'host'), "\n";

$port = (int) $config['port'] ?: throw new DomainException('Port must not be 0');
echo $port, "\n";

$positive = fn (int $n) => $n > 0 ? $n : throw new DomainException("$n is not positive");
echo $positive(8), "\n";

try {
    echo setting($config, 'password'), "\n";
} catch (OutOfBoundsException $e) {
    echo $e->getMessage(), "\n";
}

예외를 던지지 말아야 할 때

예외는 현재 함수가 처리할 수 없고 정상 흐름이 예상하지 않는 상황을 위한 것입니다. 아무것도 찾지 못한 검색, 비어 있는 선택적 필드, 로그인하지 않은 사용자는 평범한 결과입니다. null, false, 빈 배열을 반환해 호출한 쪽이 확인하게 하고, 예외는 계속 진행하면 잘못되는 경우를 위해 남겨 두세요.

<?php
$users = ['ada' => 'Ada Lovelace', 'linus' => 'Linus Torvalds'];

// Ordinary outcome: "not found" is a normal answer, so return null
function findUser(array $users, string $handle): ?string
{
    return $users[$handle] ?? null;
}

// Broken input: an empty handle is a bug in the caller, so throw
function requireHandle(string $handle): string
{
    if ($handle === '') {
        throw new InvalidArgumentException('Handle must not be empty');
    }
    return strtolower($handle);
}

foreach (['ADA', 'grace', ''] as $input) {
    try {
        $name = findUser($users, requireHandle($input));
        echo $input, ': ', $name ?? 'no such user', "\n";
    } catch (InvalidArgumentException $e) {
        echo 'Bug: ', $e->getMessage(), "\n";
    }
}

예외 코드를 읽기 좋게 유지하는 습관이 두 가지 더 있습니다. 예외를 무시하려고 잡지 마세요(빈 catch (Exception $e) {}는 다음 진짜 버그를 숨깁니다). 그리고 그냥 Exception이 아니라 구체적인 클래스를 던져서 호출한 쪽이 한 경우를 처리하려고 모든 것을 잡지 않아도 되게 하세요.