Excepciones en PHP: throw y clases de excepción propias

En PHP lanzas una excepción con throw new Exception('message');. La ejecución se detiene en esa línea y salta al bloque catch más cercano que acepte el tipo de la excepción, donde $e->getMessage() devuelve el mensaje. Usa una clase específica, como InvalidArgumentException, para que quienes llaman puedan distinguir los problemas.

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

Una excepción es un objeto. throw lo pasa hacia arriba por la pila de llamadas hasta el primer llamador con un catch que coincida, y ese llamador decide qué hacer; la función que encontró el problema no tiene por qué saberlo. La mecánica de la captura, finally y capturar varios tipos está en la página de try catch.

Qué contiene un objeto de excepción

Toda excepción lleva un mensaje, un código entero, el archivo y la línea donde se creó, y una traza de la pila. El constructor recibe ($message, $code, $previous), todos opcionales:

<?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() es la línea del throw new, no la del catch. La traza lista las llamadas que llevaron hasta ahí (#0 /home/index.php(8): findOrder()), que suele ser lo primero que hay que leer cuando aparece un error en un log. Convertir la excepción en cadena (echo $e; o (string) $e) lo imprime todo en el formato estándar de PHP.

Clases de excepción nativas

PHP trae una familia de clases de excepción en su Standard PHP Library (SPL). Lanzar la que nombra el problema hace que tu código se lea mejor y permite a quienes llaman capturar de forma precisa. Todas estas extienden Exception:

InvalidArgumentException, DomainException, LengthException y OutOfRangeException extienden LogicException; OutOfBoundsException, RangeException y UnexpectedValueException extienden RuntimeException. Puedes comprobar tú mismo los padres de cualquier clase:

<?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 tiene como padre Error, no Exception: pertenece a la segunda familia, la de abajo.

Errores que lanza el propio PHP

Desde PHP 7, y mucho más desde PHP 8, las funciones y los operadores del propio PHP lanzan subclases de Error para problemas que antes eran warnings. Los capturas de la misma forma, pero catch (Exception $e) no coincide con ellos:

<?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 y el Error simple extienden todos Error. Cada uno indica más a menudo un bug en el código que llama que datos incorrectos, y por eso viven fuera del árbol de Exception. declare(strict_types=1) es lo que hace de str_repeat(5, 2) un TypeError; sin él, PHP convertiría 5 en "5".

Escribir una clase de excepción propia

Una subclase de una línea suele ser todo lo que necesitas: el propio nombre de la clase lleva el significado, y quienes llaman pueden capturar justo ese tipo. Cuando quien captura necesita datos (qué pedido, qué importe), añade propiedades y pasa el mensaje hacia arriba 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";
}

Elige el padre con cuidado: extender RuntimeException (en lugar de Exception a secas) significa que el código que captura RuntimeException también maneja la tuya. Una jerarquía pequeña, una excepción base por librería o módulo con subclases específicas debajo, permite a quienes llaman elegir entre "capturar todo lo de pagos" y "capturar solo este caso".

Encadenar excepciones con previous

Cuando capturas una excepción de bajo nivel y lanzas una de más alto nivel, pasa la original como tercer argumento. No se pierde nada: getPrevious() recorre el camino hasta la causa raíz.

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

El usuario ve "customers.csv could not be imported"; el log, al recorrer la cadena, recibe además "row 2 has 2 columns". Si una excepción encadenada nunca se captura, el error fatal de PHP imprime toda la cadena: primero la causa original y luego cada envoltorio bajo una línea Next.

throw como expresión

Desde PHP 8.0, throw es una expresión, así que puede ir donde se espera un valor: después de ??, en un ternario, en una función flecha. Convierte "obtén esto o falla" en una sola línea:

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

Cuándo no lanzar una excepción

Las excepciones son para situaciones que la función actual no puede manejar y que el flujo normal no espera. Una búsqueda que no encuentra nada, un campo opcional vacío o un usuario que no ha iniciado sesión son resultados normales: devuelve null, false o un array vacío y deja que quien llama lo compruebe, y reserva las excepciones para los casos en los que continuar sería un error.

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

Dos hábitos más mantienen legible el código con excepciones: nunca captures una excepción solo para ignorarla (un catch (Exception $e) {} vacío esconde el siguiente bug real), y lanza clases específicas en lugar de una Exception a secas, para que quien llama nunca se vea obligado a capturarlo todo para manejar un caso.