Eccezioni in PHP: throw e classi di eccezione personalizzate

In PHP lanci un'eccezione con throw new Exception('message');. L'esecuzione si ferma in quella riga e salta al blocco catch più vicino che accetta il tipo dell'eccezione, dove $e->getMessage() restituisce il messaggio. Usa una classe specifica, come InvalidArgumentException, così chi chiama può distinguere i problemi.

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

Un'eccezione è un oggetto. throw la passa su per lo stack delle chiamate fino al primo chiamante con un catch corrispondente, e quel chiamante decide cosa fare; la funzione che ha trovato il problema non deve saperlo. Il meccanismo della cattura, finally e la cattura di più tipi sono nella pagina su try catch.

Cosa contiene un oggetto eccezione

Ogni eccezione porta con sé un messaggio, un codice intero, il file e la riga in cui è stata creata e uno stack trace. Il costruttore accetta ($message, $code, $previous), tutti facoltativi:

<?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() è la riga di throw new, non quella del catch. Il trace elenca le chiamate che hanno portato lì (#0 /home/index.php(8): findOrder()), ed è di solito la prima cosa da leggere quando un errore compare in un log. Convertire l'eccezione in stringa (echo $e; o (string) $e) stampa tutto nel formato standard di PHP.

Classi di eccezione predefinite

PHP include una famiglia di classi di eccezione nella sua Standard PHP Library (SPL). Lanciare quella che dà il nome al problema rende il codice più leggibile e permette ai chiamanti di catturare in modo mirato. Tutte queste estendono Exception:

InvalidArgumentException, DomainException, LengthException e OutOfRangeException estendono LogicException; OutOfBoundsException, RangeException e UnexpectedValueException estendono RuntimeException. Puoi verificare tu stesso i padri di qualsiasi classe:

<?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 ha come padre Error, non Exception: appartiene alla seconda famiglia, qui sotto.

Gli errori che PHP lancia da solo

Da PHP 7, e molto di più da PHP 8, le funzioni e gli operatori di PHP lanciano sottoclassi di Error per problemi che prima erano warning. Le catturi allo stesso modo, ma catch (Exception $e) non le intercetta:

<?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 e il semplice Error estendono tutti Error. Ciascuno indica più spesso un bug nel codice chiamante che dati errati, ed è per questo che vivono fuori dall'albero di Exception. È declare(strict_types=1) a rendere str_repeat(5, 2) un TypeError; senza, PHP convertirebbe 5 in "5".

Scrivere una classe di eccezione personalizzata

Spesso basta una sottoclasse di una riga: il nome della classe porta già il significato, e i chiamanti possono catturare esattamente quel tipo. Quando chi cattura ha bisogno di dati (quale ordine, quale importo), aggiungi proprietà e passa il messaggio in su con 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";
}

Scegli il padre con attenzione: estendere RuntimeException (invece del semplice Exception) significa che il codice che cattura RuntimeException gestisce anche la tua. Una piccola gerarchia, un'eccezione base per libreria o modulo con sottoclassi specifiche sotto, permette ai chiamanti di scegliere tra "cattura tutto ciò che viene dai pagamenti" e "cattura solo questo caso".

Concatenare le eccezioni con previous

Quando catturi un'eccezione di basso livello e ne lanci una di livello più alto, passa l'originale come terzo argomento. Nulla va perso: getPrevious() risale fino alla causa principale.

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

L'utente vede "customers.csv could not be imported"; il log, percorrendo la catena, riceve anche "row 2 has 2 columns". Se un'eccezione concatenata non viene mai catturata, l'errore fatale di PHP stampa l'intera catena: prima la causa originale, poi ogni involucro sotto una riga Next.

throw come espressione

Da PHP 8.0, throw è un'espressione, quindi può stare ovunque sia atteso un valore: dopo ??, in un ternario, in una arrow function. Rende "prendi questo o fallisci" una sola riga:

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

Quando non lanciare

Le eccezioni servono per le situazioni che la funzione corrente non può gestire e che il flusso normale non prevede. Una ricerca che non trova nulla, un campo facoltativo vuoto o un utente non autenticato sono esiti ordinari: restituisci null, false o un array vuoto e lascia che sia il chiamante a verificare, e tieni le eccezioni per i casi in cui andare avanti sarebbe sbagliato.

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

Altre due abitudini mantengono leggibile il codice con le eccezioni: non catturare mai un'eccezione solo per ignorarla (un catch (Exception $e) {} vuoto nasconde il prossimo bug reale), e lancia classi specifiche invece del semplice Exception, così un chiamante non è mai costretto a catturare tutto per gestire un solo caso.