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です。下で紹介する2つ目のファミリーに属します。

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"に変換します。

独自の例外クラスを書く

たいていは1行のサブクラスで十分です。クラス名自体が意味を伝え、呼び出し側はまさにその型をキャッチできます。キャッチする側がデータ（どの注文か、いくらか）を必要とするなら、プロパティを加え、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をキャッチするコードがあなたの例外も処理します。ライブラリやモジュールごとに1つの基底例外を置き、その下に具体的なサブクラスを並べる小さな階層を作れば、呼び出し側は「決済のものを何でもキャッチする」と「この1つのケースだけキャッチする」を選べます。

previousで例外を連鎖させる

低レベルの例外をキャッチして高レベルの例外を投げるときは、元の例外を3つ目の引数として渡します。何も失われず、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は式なので、??のあと、三項演算子の中、アロー関数の中など、値が期待される場所ならどこにでも書けます。「これを取得する、できなければ失敗する」が1行になります。

<?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";
    }
}

例外のコードを読みやすく保つ習慣があと2つあります。例外を無視するためだけにキャッチしない（空のcatch (Exception $e) {}は次の本物のバグを隠します）ことと、素のExceptionではなく具体的なクラスを投げ、呼び出し側が1つのケースを処理するためにすべてをキャッチせざるをえない状況を作らないことです。