PHP Exceptions: throw und eigene Exception-Klassen

Eine Exception wirfst du in PHP mit throw new Exception('message');. Die Ausführung stoppt in dieser Zeile und springt zum nächsten catch-Block, der den Typ der Exception akzeptiert, wo $e->getMessage() die Meldung liefert. Verwende eine bestimmte Klasse wie InvalidArgumentException, damit Aufrufer Probleme unterscheiden können.

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

Eine Exception ist ein Objekt. throw reicht sie den Aufrufstapel hinauf zum ersten Aufrufer mit passendem catch, und dieser Aufrufer entscheidet, was zu tun ist; die Funktion, die das Problem gefunden hat, muss das nicht wissen. Die Mechanik des Abfangens, finally und das Abfangen mehrerer Typen stehen auf der Seite zu try catch.

Was ein Exception-Objekt enthält

Jede Exception trägt eine Meldung, einen Ganzzahl-Code, die Datei und Zeile, in der sie erzeugt wurde, und einen Stack Trace. Der Konstruktor nimmt ($message, $code, $previous), alles optional:

<?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() ist die Zeile von throw new, nicht die Zeile des catch. Der Trace listet die Aufrufe auf, die dorthin geführt haben (#0 /home/index.php(8): findOrder()), und das liest man meist zuerst, wenn ein Fehler in einem Log auftaucht. Die Exception in einen String umzuwandeln (echo $e; oder (string) $e) gibt alles im Standardformat von PHP aus.

Eingebaute Exception-Klassen

PHP bringt in seiner Standard PHP Library (SPL) eine Familie von Exception-Klassen mit. Diejenige zu werfen, die das Problem benennt, macht deinen Code lesbarer und lässt Aufrufer gezielt abfangen. Alle diese Klassen erweitern Exception:

InvalidArgumentException, DomainException, LengthException und OutOfRangeException erweitern LogicException; OutOfBoundsException, RangeException und UnexpectedValueException erweitern RuntimeException. Die Elternklassen jeder Klasse kannst du selbst prüfen:

<?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 hat Error als Elternklasse, nicht Exception: Es gehört zur zweiten Familie, unten.

Fehler, die PHP selbst wirft

Seit PHP 7, und viel stärker seit PHP 8, werfen PHPs eigene Funktionen und Operatoren Unterklassen von Error für Probleme, die früher Warnungen waren. Du fängst sie genauso ab, aber catch (Exception $e) passt nicht auf sie:

<?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 und das einfache Error erweitern alle Error. Jede davon markiert öfter einen Bug im aufrufenden Code als schlechte Daten, und deshalb leben sie außerhalb des Exception-Baums. declare(strict_types=1) ist das, was str_repeat(5, 2) zu einem TypeError macht; ohne würde PHP 5 in "5" umwandeln.

Eine eigene Exception-Klasse schreiben

Eine einzeilige Unterklasse ist oft alles, was du brauchst: Der Klassenname selbst trägt die Bedeutung, und Aufrufer können genau diesen Typ abfangen. Wenn der Abfangende Daten braucht (welche Bestellung, welcher Betrag), fügst du Eigenschaften hinzu und reichst die Meldung mit parent::__construct() weiter:

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

Wähl die Elternklasse mit Bedacht: RuntimeException zu erweitern (statt einfach Exception) bedeutet, dass Code, der RuntimeException abfängt, auch deine behandelt. Eine kleine Hierarchie, eine Basis-Exception pro Bibliothek oder Modul mit spezifischen Unterklassen darunter, lässt Aufrufer wählen zwischen „alles aus dem Zahlungsmodul abfangen“ und „nur genau diesen einen Fall abfangen“.

Exceptions mit previous verketten

Wenn du eine Exception einer unteren Ebene abfängst und eine einer höheren Ebene wirfst, übergib die ursprüngliche als drittes Argument. Nichts geht verloren: getPrevious() geht zurück bis zur eigentlichen Ursache.

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

Der Nutzer sieht „customers.csv could not be imported“; das Log, das die Kette abgeht, bekommt außerdem „row 2 has 2 columns“. Wird eine verkettete Exception nie abgefangen, gibt PHPs fataler Fehler die ganze Kette aus: zuerst die ursprüngliche Ursache, dann jede Hülle unter einer Zeile Next.

throw als Ausdruck

Seit PHP 8.0 ist throw ein Ausdruck und kann damit überall stehen, wo ein Wert erwartet wird: nach ??, in einem ternären Ausdruck, in einer Arrow Function. Das macht „hol das oder scheitere“ zu einer einzigen Zeile:

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

Wann man nicht wirft

Exceptions sind für Situationen, die die aktuelle Funktion nicht behandeln kann und die der normale Ablauf nicht erwartet. Eine Suche ohne Treffer, ein leeres optionales Feld oder ein Nutzer, der nicht angemeldet ist, sind gewöhnliche Ergebnisse: Liefere null, false oder ein leeres Array, lass den Aufrufer prüfen, und behalte Exceptions für die Fälle, in denen Weitermachen falsch wäre.

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

Zwei weitere Gewohnheiten halten Exception-Code lesbar: Fang nie eine Exception ab, nur um sie zu ignorieren (ein leeres catch (Exception $e) {} versteckt den nächsten echten Bug), und wirf bestimmte Klassen statt eines bloßen Exception, damit ein Aufrufer nie gezwungen ist, alles abzufangen, um einen Fall zu behandeln.