Skip to content

7. Excepciones y errores

Cuando un método de una clase encuentra un error irrecuperable (el archivo no existe, la base de datos no está conectada, la conexión de red está caída), no muestra un error en una consola (archivo, base de datos) sino que lanza una excepción. Las excepciones extienden la clase [\Exception]. Además de las excepciones, el funcionamiento interno de PHP también lanza errores cuya clase base es [\Error]. Ambas clases implementan la interfaz [\Throwable].

PHP 8 cambió radicalmente el manejo de errores: muchas situaciones que en PHP 7 producían una simple advertencia (y a menudo un resultado absurdo) ahora lanzan un error que se puede capturar. Lo veremos a lo largo de los ejemplos.

7.1. Estructura de directorios de los scripts

Los scripts de este capítulo se encuentran en la carpeta [scripts-console/exceptions]:

1
2
3
4
5
6
php8-oct-2026/scripts-console/exceptions
├── exceptions-01.php
├── exceptions-02.php
├── ...
├── exceptions-11.php
└── throwables.php

7.2. La interfaz [\Throwable]

La interfaz [\Throwable] es la siguiente (consulte la documentación):

interface Throwable extends Stringable
{
    public function getMessage(): string;
    public function getCode(): int;
    public function getFile(): string;
    public function getLine(): int;
    public function getTrace(): array;
    public function getTraceAsString(): string;
    public function getPrevious(): ?Throwable;
    public function __toString(): string;
}

La función de los métodos de la interfaz es la siguiente:

Método
Propósito
[getMessage]
Devuelve el mensaje de error
[getCode]
devuelve el código de error (un entero)
[getFile]
devuelve el nombre del archivo donde se creó el objeto
[getLine]
devuelve el número de la línea donde se creó el objeto
[getTrace]
devuelve la pila de llamadas a funciones como un arreglo
[getTraceAsString]
devuelve la pila de llamadas como una cadena de caracteres
[getPrevious]
devuelve el objeto [Throwable] anterior (encapsulado), o [null]
[__toString]
devuelve una representación del objeto como cadena de caracteres

Observe que la interfaz [Throwable] extiende la interfaz [Stringable] que se vio en el capítulo sobre clases. Una clase no puede implementar directamente la interfaz [Throwable]; debe derivar de [\Exception] o de [\Error].

7.3. Excepciones y errores predefinidos en PHP 8

El siguiente script [throwables.php] muestra la estructura de árbol de las clases predefinidas que implementan la interfaz [Throwable]. Lo usamos para obtener una lista exacta (la de PHP 8.5) en lugar de copiarla de la documentación. El lector no se perderá nada si no intenta comprender su código, que utiliza la API de reflexión de PHP (la clase [ReflectionClass] permite consultar a PHP sobre una clase: su nombre, su extensión de origen, sus interfaces, etc.) y una función recursiva:

<?php

// respeto estricto de los tipos declarados de los parámetros de las funciones
declare(strict_types=1);

// muestra el árbol de las clases predefinidas que implementan la interfaz [Throwable]
// nos limitamos a las extensiones siempre presentes en PHP 8.5:
// el núcleo (Core), la biblioteca estándar, la biblioteca SPL, JSON y Random
$extensions = ["Core", "standard", "SPL", "json", "random"];

// las clases predefinidas de estas extensiones que implementan [Throwable]
$classes = array_filter(
    get_declared_classes(),
    function (string $class) use ($extensions): bool {
        $reflection = new ReflectionClass($class);
        return $reflection->isInternal()
            && $reflection->implementsInterface(Throwable::class)
            && in_array($reflection->getExtensionName(), $extensions, true);
    }
);
sort($classes);

// visualización recursiva de las clases hijas de la clase [$parent]
function display(?string $parent, array $classes, string $indentation): void
{
    // los hijos directos de [$parent]
    $children = array_values(array_filter(
        $classes,
        fn(string $class): bool => (get_parent_class($class) ?: null) === $parent
    ));
    foreach ($children as $i => $child) {
        $last = $i === count($children) - 1;
        print $indentation . ($last ? "└── " : "├── ") . $child . "\n";
        display($child, $classes, $indentation . ($last ? "    " : "│   "));
    }
}

print "Throwable\n";
display(null, $classes, "");

Resultados:

> php throwables.php
Throwable
├── Error
│   ├── ArithmeticError
│   │   └── DivisionByZeroError
│   ├── AssertionError
│   ├── CompileError
│   │   └── ParseError
│   ├── FiberError
│   ├── Random\RandomError
│   │   └── Random\BrokenRandomEngineError
│   ├── TypeError
│   │   └── ArgumentCountError
│   ├── UnhandledMatchError
│   └── ValueError
└── Exception
    ├── ClosedGeneratorException
    ├── ErrorException
    ├── JsonException
    ├── LogicException
    │   ├── BadFunctionCallException
    │   │   └── BadMethodCallException
    │   ├── DomainException
    │   ├── InvalidArgumentException
    │   ├── LengthException
    │   └── OutOfRangeException
    ├── Random\RandomException
    ├── RequestParseBodyException
    └── RuntimeException
        ├── OutOfBoundsException
        ├── OverflowException
        ├── RangeException
        ├── UnderflowException
        └── UnexpectedValueException

Comentarios

  • línea 13: la función [get_declared_classes] devuelve una lista de todas las clases conocidas hasta ese momento, ya sean predefinidas o no;
  • líneas 16–18: solo se conservan las clases predefinidas (internas), es decir, las que implementan la interfaz [Throwable] y pertenecen a extensiones siempre presentes en PHP 8.5 (línea 9). Otras extensiones agregan sus propias excepciones (por ejemplo, [PDOException] para el acceso a bases de datos, que encontraremos más adelante);
  • líneas 24–36: una función recursiva que muestra las clases hijas directas de la clase [$parent], luego las hijas de cada una de ellas, y así sucesivamente. La función [get_parent_class] devuelve [false] para una clase sin padre: el operador [?:] transforma entonces [false] en [null];
  • línea 29: una función flecha (PHP 7.4), una forma abreviada de función anónima reducida a una expresión;
  • línea 39: se comienza con las clases sin padre: [Error] y [Exception].

Los resultados muestran dos familias:

  • la familia [Exception]: son las excepciones lanzadas por las bibliotecas y el código de la aplicación. Incluye:
    • [ErrorException], que convierte una advertencia de PHP en una excepción (la usaremos al final del capítulo);
    • [JsonException] (PHP 7.3), lanzada por [json_encode] y [json_decode] con la opción [JSON_THROW_ON_ERROR];
    • [Random\RandomException] (PHP 8.2), iniciada por las funciones de generación de números aleatorios;
    • las excepciones de la biblioteca SPL (Standard PHP Library), un conjunto de clases e interfaces diseñadas para resolver problemas que los desarrolladores encuentran con frecuencia. Forman dos subfamilias:
    • [LogicException] y sus derivadas: errores de programación que se resuelven corrigiendo el código: argumento no válido ([InvalidArgumentException]), valor fuera del rango esperado ([DomainException]), método inexistente ([BadMethodCallException])...;
    • [RuntimeException] y sus variantes: errores que solo se pueden detectar en tiempo de ejecución: índice fuera de los límites ([OutOfBoundsException]), valor inesperado ([UnexpectedValueException]), capacidad excedida ([OverflowException])... ;
  • la familia [Error]: son los errores lanzados por el propio motor de PHP. Incluye:
    • [TypeError]: un valor no es del tipo esperado (parámetro de una función, atributo tipado, valor de retorno, operando de un operador, etc.). Su derivada, [ArgumentCountError], indica un número insuficiente de argumentos;
    • [ValueError] (PHP 8.0): un valor es del tipo correcto pero tiene un valor no válido (por ejemplo, una longitud negativa o cero);
    • [ArithmeticError] y su derivada [DivisionByZeroError]: errores en operaciones aritméticas;
    • [UnhandledMatchError] (PHP 8.0): ninguna rama de la expresión [match] es adecuada;
    • [AssertionError]: falló la aserción de [assert];
    • [CompileError] y su derivada [ParseError]: error de sintaxis en un archivo cargado por [require] o [include];
    • [FiberError] (PHP 8.1) y [Random\RandomError] (PHP 8.2): errores relacionados con las fibras y los generadores de números aleatorios, que no utilizaremos.

Las dos familias no tienen relación entre sí: una cláusula [catch (\Exception $e)] no intercepta un error [Error]. Solo la interfaz [Throwable] las vincula.

7.4. Ejemplo 1

El primer ejemplo, [exceptions-01.php], muestra tanto una advertencia como un error de PHP:

<?php

// respeto estricto de los tipos declarados de los parámetros de las funciones
declare(strict_types=1);

// visualización de todos los errores
error_reporting(E_ALL);
ini_set("display_errors", "1");
// código ────────
$var = [];
// clave desconocida
print $var["abcd"];
// división por cero
$var = 7 / 0;
var_dump($var);
// arreglo de límites fijos
$array = new \SplFixedArray(5);
$array[1] = 2;
$array[4] = "foo";
// índice fuera de los límites
$array[5] = 8;

Comentarios

  • Línea 7: se indica a PHP que informe todos los errores. El parámetro de la función [error_reporting] es el nivel de reporte de errores. Es una combinación de las siguientes constantes (las principales):
Constante
Significado
[E_ERROR]
Error fatal en tiempo de ejecución: el script se termina
[E_WARNING]
Advertencia: el script continúa
[E_PARSE]
Error de sintaxis detectado durante la compilación
[E_NOTICE]
Nota: algo que podría ser un error
[E_DEPRECATED]
Uso de una característica obsoleta, que se eliminará en una versión futura
[E_USER_WARNING], [E_USER_NOTICE], [E_USER_DEPRECATED]
Los mismos niveles, activados por el código mediante la función [trigger_error]
[E_ALL]
todos los niveles
  • la constante [E_STRICT], que ya no corresponde a ningún mensaje desde PHP 8.0, está obsoleta desde PHP 8.4, al igual que el uso del nivel [E_USER_ERROR] con [trigger_error]: para señalar un error fatal, el código lanza una excepción;
  • línea 8: se configura el código para mostrar los errores en la consola. En producción se hace lo contrario: los errores se escriben en un archivo de registro y no se muestran;
  • línea 12: se intenta acceder a un elemento inexistente del arreglo [$var];
  • línea 14: se produce una división por cero;
  • línea 17: se crea una instancia de la clase [SplFixedArray] de la biblioteca SPL. Esta clase permite crear un arreglo de tamaño fijo con índices enteros;
  • línea 21: se intenta acceder a un elemento inexistente del arreglo.

Resultados:

1
2
3
4
5
6
7
8
> php exceptions-01.php

Warning: Undefined array key "abcd" in .../php8-oct-2026/scripts-console/exceptions/exceptions-01.php on line 12

Fatal error: Uncaught DivisionByZeroError: Division by zero in .../php8-oct-2026/scripts-console/exceptions/exceptions-01.php:14
Stack trace:
#0 {main}
  thrown in .../php8-oct-2026/scripts-console/exceptions/exceptions-01.php on line 14

Comentarios sobre los resultados

  • línea 3: acceder a una clave inexistente en un arreglo genera una advertencia de nivel [E_WARNING] (en PHP 7 era una simple nota [E_NOTICE] ). Esto no interrumpe la ejecución del script;
  • líneas 5–8: en PHP 7, dividir un número por cero generaba una advertencia [E_WARNING] y devolvía el valor [INF] (infinito). En PHP 8, el operador [/] lanza un error de tipo [DivisionByZeroError]. Como no se captura, interrumpe la ejecución del script: es un error fatal (Fatal error: Uncaught...). El mensaje muestra la pila de llamadas (Stack trace) en el momento del error;
  • el código que sigue a la división no se ejecuta: el intento de acceder a un índice inexistente en el arreglo [SplFixedArray] no llega a ocurrir. Lo veremos de nuevo en los ejemplos siguientes.

7.5. Manejo de excepciones

El script [exceptions-02.php] muestra cómo manejar excepciones:

<?php

// respeto estricto de los tipos declarados de los parámetros de las funciones
declare(strict_types=1);

// mostramos todos los errores
error_reporting(E_ALL);
ini_set("display_errors", "1");
// rodeamos el código con un try / catch
try {
    $var = [];
    // clave desconocida
    print $var["abcd"];
    // división por cero
    $var = 7 / 0;
    var_dump($var);
    // arreglo de límites fijos
    $array = new \SplFixedArray(5);
    $array[1] = 2;
    $array[4] = "foo";
    // índice fuera de los límites
    $array[5] = 8;
    // verificación
    print "this message will not be displayed\n";
} catch (\Throwable $ex) {
    // \Throwable es la interfaz implementada por todos los errores y excepciones
    // mostramos la excepción
    print "error, message: " . $ex->getMessage() . ", type: " . $ex::class . "\n";
}

Comentarios

  • El script es el presentado en la sección anterior. Sin embargo, ahora hemos encerrado el código que podría causar errores dentro de una estructura [try / catch]: si el código de las líneas 11–24 provoca (lanza) una excepción o un error, este será manejado por la cláusula [catch] de las líneas 25–29;
  • línea 25: el parámetro de la cláusula [catch] es el tipo de excepción o de error que se desea manejar. Al fijar el tipo en [\Throwable], que es una interfaz, indicamos que queremos manejar cualquier instancia de clase que implemente la interfaz [\Throwable]. Como todas las clases de errores y excepciones implementan esta interfaz, la cláusula [catch] maneja aquí todos los errores y excepciones;
  • línea 15: la instrucción que desencadena el error. En cuanto ocurre una excepción, el control se transfiere a la cláusula [catch]. Por lo tanto, el código que sigue en [try] no se ejecuta;
  • línea 28: la notación [$ex::class] devuelve el nombre de la clase del objeto [$ex].

Resultados:

1
2
3
4
> php exceptions-02.php

Warning: Undefined array key "abcd" in .../php8-oct-2026/scripts-console/exceptions/exceptions-02.php on line 13
error, message: Division by zero, type: DivisionByZeroError

Comentarios sobre los resultados

  • Línea 3: vemos la advertencia de nivel [E_WARNING]. Una advertencia no es una excepción y, por lo tanto, la cláusula [catch] no la maneja. Al final de este capítulo veremos cómo convertir las advertencias en excepciones;
  • Línea 4: el mensaje de error se escribe en la cláusula [catch]. Esto significa que ocurrió una excepción derivada de [\Exception] o un error derivado de [\Error] . Aquí vemos que se trata de la clase [DivisionByZeroError]. El script terminó normalmente.

7.6. Parámetros de la cláusula [catch]

Examinemos el siguiente script [exceptions-03.php]:

<?php

// respeto estricto de los tipos declarados de los parámetros de las funciones
declare(strict_types=1);

// mostramos todos los errores
error_reporting(E_ALL);
ini_set("display_errors", "1");

// un arreglo de límites fijos
$array = new \SplFixedArray(5);
try {
    // índice fuera de los límites
    $array[5] = 8;
} catch (\Throwable $ex) {
    // visualización del mensaje de error
    print "Error 1: " . $ex->getMessage() . " (" . $ex::class . ")\n";
}

try {
    // índice fuera de los límites
    $array[5] = 8;
} catch (\Exception $ex) {
    // visualización del mensaje de error
    print "Error 2: " . $ex->getMessage() . "\n";
}

try {
    // índice fuera de los límites
    $array[5] = 8;
} catch (\RuntimeException $ex) {
    // visualización del mensaje de error
    print "Error 3: " . $ex->getMessage() . "\n";
}

try {
    // índice fuera de los límites
    $array[5] = 8;
} catch (\OutOfBoundsException $ex) {
    // visualización del mensaje de error
    print "Error 4: " . $ex->getMessage() . "\n";
}

try {
    // división entre 0
    intdiv(5, 0);
} catch (\Throwable $ex) {
    // visualización del mensaje de error
    print "Error 5: " . $ex->getMessage() . " (" . $ex::class . ")\n";
}

try {
    // división entre 0
    intdiv(5, 0);
} catch (\DivisionByZeroError $ex) {
    // visualización del mensaje de error
    print "Error 6: " . $ex->getMessage() . "\n";
}

try {
    // división entre 0
    intdiv(5, 0);
} catch (\ArithmeticError $ex) {
    // visualización del mensaje de error
    print "Error 7: " . $ex->getMessage() . "\n";
}

try {
    // división entre 0
    intdiv(5, 0);
} catch (\Error $ex) {
    // visualización del mensaje de error
    print "Error 8: " . $ex->getMessage() . "\n";
}

try {
    // división entre 0
    intdiv(5, 0);
} catch (\Exception $ex) {
    // visualización del mensaje de error
    print "Error 9: " . $ex->getMessage() . "\n";
}

Comentarios

  • Líneas 11–41: cuatro formas distintas de manejar la excepción generada por el uso de un índice incorrecto con la clase [\SplFixedArray]. La ejecución muestra que este error genera una excepción de tipo [OutOfBoundsException] (línea 2 de los resultados). En el curso de PHP 7 (y todavía en PHP 8.3), era una excepción [RuntimeException]. El cambio no rompió el código existente, ya que la clase [OutOfBoundsException] deriva de la clase [RuntimeException];
    • línea 15: maneja un error de tipo [\Throwable]. Esto es válido porque el tipo [OutOfBoundsException] deriva del tipo [\Exception], que implementa la interfaz [\Throwable];
    • línea 23: maneja un error de tipo [\Exception]. Esto es válido porque el tipo [OutOfBoundsException] deriva del tipo [\Exception];
    • línea 31: maneja un error de tipo [\RuntimeException]. Esto es válido porque el tipo [OutOfBoundsException] deriva del tipo [\RuntimeException]. Es una buena elección: el código funciona independientemente de la versión de PHP;
    • línea 39: maneja el tipo exacto de la excepción generada;
  • líneas 46–81: 5 formas distintas de manejar el error generado por la función [intdiv] cuando se le pasa un divisor igual a 0. La función [intdiv(int $dividend, int $divisor): int] realiza la división entera [$dividend / $divisor]. Cuando el divisor es cero, se lanza el error [\DivisionByZeroError] ;
    • línea 47: se captura cualquier error que implemente la interfaz [\Throwable]. Esto es válido;
    • línea 55: se intercepta el tipo exacto del error; este es el método recomendado;
    • línea 63: se captura el tipo [\ArithmeticError]. Esto es válido ya que la clase [DivisionByZeroError] extiende la clase [ArithmeticError];
    • Línea 71: se intercepta el tipo [\Error]. Esto es válido porque la clase [DivisionByZeroError] deriva de la clase [Error];
    • Línea 79: se intercepta el tipo [\Exception]. Esto no es válido porque la clase [DivisionByZeroError] no tiene ninguna relación con la clase [\Exception].

Resultados:

> php exceptions-03.php
Error 1: Index invalid or out of range (OutOfBoundsException)
Error 2: Index invalid or out of range
Error 3: Index invalid or out of range
Error 4: Index invalid or out of range
Error 5: Division by zero (DivisionByZeroError)
Error 6: Division by zero
Error 7: Division by zero
Error 8: Division by zero

Fatal error: Uncaught DivisionByZeroError: Division by zero in .../php8-oct-2026/scripts-console/exceptions/exceptions-03.php:78
Stack trace:
#0 .../php8-oct-2026/scripts-console/exceptions/exceptions-03.php(78): intdiv(5, 0)
#1 {main}
  thrown in .../php8-oct-2026/scripts-console/exceptions/exceptions-03.php on line 78

Las líneas 11–15 de los resultados muestran que el error [DivisionByZeroError] no fue capturado por la última cláusula [catch (\Exception $ex)]: se trata de un error fatal.

7.7. La cláusula [finally]

La estructura [try / catch] puede tener un tercer elemento y convertirse en una estructura [try / catch / finally]. El código de la cláusula [finally] se ejecuta en los dos casos siguientes:

  • la cláusula [try] no lanza ninguna excepción. Se ejecuta entonces por completo y, a continuación, la ejecución pasa a la cláusula [finally], que se ejecuta por completo;
  • la cláusula [try] lanza una excepción. Se ejecuta entonces hasta la instrucción que lanza la excepción. La ejecución pasa luego a la cláusula [catch], que se ejecuta por completo. Después, la ejecución pasa a la cláusula [finally], que se ejecuta por completo.

Por último, el código de la cláusula [finally] se ejecuta de todos modos. Este escenario es útil en el siguiente caso:

  • en la cláusula [try], el código ha adquirido recursos (archivos, bases de datos, conexiones de red, colas). Estos recursos suelen ser costosos. Por lo tanto, deben liberarse (lo que más a menudo se denomina “cerrar”) lo antes posible;
  • si los recursos se adquirieron en [try], su liberación se realizará en [finally]. Esto garantiza que, en todos los casos (ocurra o no un error), los recursos adquiridos se devuelvan al sistema.

El siguiente script, [exceptions-04.php], demuestra cómo funciona la cláusula [finally] en diversas situaciones:

<?php

// respeto estricto de los tipos declarados de los parámetros de las funciones
declare(strict_types=1);

// creamos una instancia de excepción
$e = new \Exception("Error...");

// primera prueba
try {
    print "First test\n";
    throw $e;
} catch (\Exception $ex1) {
    print $ex1->getMessage() . "\n";
} finally {
    print "Done\n";
}

// segunda prueba
try {
    print "Second test\n";
} catch (\Exception $ex1) {
    print $ex1->getMessage() . "\n";
} finally {
    print "Done\n";
}

// tercera prueba
try {
    print "Third test\n";
    return;
} catch (\Exception $ex1) {
    print $ex1->getMessage() . "\n";
} finally {
    print "Done\n";
}

Comentarios del código

  • Línea 7: [$e] es una instancia de la clase predefinida [\Exception]. La instanciaremos en distintos lugares;
  • Líneas 11–12: la excepción [$e] se lanza en [try] mediante la instrucción [throw];
  • línea 13: se captura la excepción [\Exception] y su mensaje de error se escribe en la consola;
  • Líneas 15–16: la cláusula [finally] escribe un mensaje. Según lo explicado antes, este mensaje debería escribirse siempre, haya o no un error en [try];
  • línea 21: no hay ningún error en [try]. Aquí también el programa debería pasar a [finally];
  • Línea 31: hay una instrucción [return] en la cláusula [try] y no hay ningún error. Esto plantea la pregunta de si el script pasará a la cláusula [finally]. La ejecución muestra que así es. Cuando se usa fuera de una función, la instrucción [return] termina el script.

Resultados:

1
2
3
4
5
6
7
8
> php exceptions-04.php
First test
Error...
Done
Second test
Done
Third test
Done

Examinemos otro caso, [exceptions-05.php]:

<?php

// respeto estricto de los tipos declarados de los parámetros de las funciones
declare(strict_types=1);

// cuarta prueba
try {
    print "Fourth test\n";
    exit;
} finally {
    print "Done\n";
}

Comentarios

  • Línea 9: la instrucción [exit] termina de inmediato la ejecución del script: la cláusula [finally] no se ejecuta;
  • Líneas 7–12: un ejemplo de [try / finally] sin la cláusula [catch]. Esto es posible.

Resultados:

> php exceptions-05.php
Fourth test

7.8. Creación de clases de excepción propias

En un proyecto de cierto tamaño, es útil diferenciar los distintos errores encapsulándolos en diferentes clases de excepción. En los scripts anteriores vimos que cualquier excepción podía capturarse con una cláusula [catch (\Throwable $ex)]. Esto es recomendable si no se tiene idea de cuál es el error interceptado y el tratamiento es el mismo para todos los errores. A veces es así, pero con frecuencia es necesario adaptar el tratamiento al tipo exacto de error. En ese caso, hay que distinguir entre los diferentes errores.

Examinemos el siguiente script [exceptions-06.php]:

<?php

// respeto estricto de los tipos declarados de los parámetros de las funciones
declare(strict_types=1);

// definimos nuestra propia familia de excepciones
class Exception1 extends \RuntimeException
{
}

class Exception2 extends \RuntimeException
{
}

// usamos nuestras excepciones
$e1 = new Exception1("Error1...");
var_dump($e1);
$e2 = new Exception2("Error2...", 2);

// primera prueba
print "first test\n";
try {
    // lanzamos una excepción de tipo Exception1
    throw $e1;
} catch (Exception1 $ex1) {
    print "Exception 1\n";
    print $ex1->getMessage() . "\n";
} catch (Exception2 $ex2) {
    print "Exception 2\n";
    print $ex2->getMessage() . "\n";
}

// segunda prueba
print "second test\n";
try {
    // lanzamos una excepción de tipo Exception2
    throw $e2;
} catch (Exception1 $ex1) {
    print "Exception 1\n";
    print $ex1->getMessage() . "\n";
} catch (Exception2 $ex2) {
    print "Exception 2\n";
    print $ex2->getMessage() . "\n";
}

// tercera prueba
print "third test\n";
try {
    // lanzamos una excepción de tipo Exception1
    throw $e1;
} catch (Exception1 | Exception2 $ex) {
    print "Exception 1 or 2\n";
    print $ex->getMessage() . "\n";
}

// cuarta prueba
print "fourth test\n";
try {
    // lanzamos una excepción de tipo Exception2
    throw $e2;
} catch (Exception1 | Exception2 $ex) {
    print "Exception 1 or 2: " . $ex::class . "\n";
    // la información que lleva la excepción
    print "message: " . $ex->getMessage() . "\n";
    print "code: " . $ex->getCode() . "\n";
    print "file: " . basename($ex->getFile()) . "\n";
    print "line: " . $ex->getLine() . "\n";
}

Comentarios

  • Líneas 7–9: definimos dos clases, *[Exception1] y *[Exception2], ambas derivadas de la clase predefinida ***[\\RuntimeException]***. El cuerpo de estas clases está vacío. En otras palabras, se usan únicamente por sus tipos: precisamente porque tienen tipos diferentes podremos distinguir estas dos excepciones en las cláusulas [catch];
  • líneas 16–18: definimos dos variables, [$e1] y [$e2], que tienen los tipos [Exception1] y [Exception2], respectivamente. El constructor utilizado es el de la clase [Exception], cuya firma es [__construct(string $message = "", int $code = 0, ?Throwable $previous = null)]. Para [$e2], se especificó un código de error;
  • líneas 21–31: hay una estructura [try / catch / catch]. Esta permite manejar diferentes tipos de excepciones con distintas cláusulas [catch]. Se ejecuta la primera cláusula cuyo tipo coincide; las demás se ignoran;
  • línea 25: intercepta las excepciones de tipo [Exception1];
  • línea 28: intercepta las excepciones de tipo [Exception2];
  • línea 51: intercepta las excepciones de tipo [Exception1] o ([|]) [Exception2]. Esta sintaxis está disponible desde PHP 7.1;
  • línea 62: el nombre de la clase de la excepción interceptada;
  • líneas 64–67: la información contenida en la excepción, obtenida mediante los métodos de la interfaz [Throwable]. La función [basename] devuelve el nombre de un archivo sin la ruta de la carpeta.

Resultados:

> php exceptions-06.php
object(Exception1)#1 (7) {
  ["message":protected]=>
  string(9) "Error1..."
  ["string":"Exception":private]=>
  string(0) ""
  ["code":protected]=>
  int(0)
  ["file":protected]=>
  string(76) ".../php8-oct-2026/scripts-console/exceptions/exceptions-06.php"
  ["line":protected]=>
  int(16)
  ["trace":"Exception":private]=>
  array(0) {
  }
  ["previous":"Exception":private]=>
  NULL
}
first test
Exception 1
Error1...
second test
Exception 2
Error2...
third test
Exception 1 or 2
Error1...
fourth test
Exception 1 or 2: Exception2
message: Error2...
code: 2
file: exceptions-06.php
line: 18

Comentarios sobre los resultados

  • Líneas 2–18: el “contenido” de una excepción, mostrado por [var_dump]:
    • líneas 3–4: el mensaje de error;
    • líneas 7–8: el código de error;
    • líneas 9–10: el nombre del archivo en el que se produjo la excepción. La longitud indicada (string(76)) es la de la ruta completa del archivo: depende de la carpeta en la que se encuentre el script;
    • líneas 11–12: la línea donde se produjo la excepción;
    • líneas 13–15: la pila de llamadas en el momento en que se produjo la excepción. Aquí está vacía porque la excepción se produjo en el script principal y no dentro de una función;
    • líneas 16–17: la excepción anterior. Una excepción puede encapsular otra excepción, definiendo así una pila de excepciones. El atributo [previous] permite analizar esta pila;
  • líneas 29–33: observe que el archivo y el número de línea de la excepción son los de su creación mediante [new] (línea 18) y no los de su lanzamiento mediante [throw].

7.9. Relanzar una excepción

Una excepción puede lanzarse varias veces, como muestra el siguiente script, [exceptions-07.php]:

<?php

// respeto estricto de los tipos declarados de los parámetros de las funciones
declare(strict_types=1);

try {
    try {
        // lanzamos una excepción
        throw new \Exception("test");
    } catch (\Exception $ex) {
        // relanzamos la excepción capturada
        throw $ex;
    } finally {
        // sí pasamos por el finally
        print "finally 1\n";
    }
} catch (\Exception $ex2) {
    // sí recuperamos la excepción inicial
    print $ex2->getMessage() . " in outer try / catch / finally\n";
} finally {
    // sí pasamos por el finally
    print "finally 2\n";
}

Comentarios

  • línea 9: se lanza una excepción;
  • línea 10: se captura la excepción;
  • línea 12: se relanza la excepción. Pasa entonces a la estructura [try / catch / finally] del nivel superior. Este escenario es frecuente: el código intercepta una excepción para realizar un tratamiento local (escribir un registro, revertir una transacción, etc.) y luego la relanza para que el código que lo llama también sea notificado;
  • línea 17: se intercepta de nuevo;
  • Líneas 13–15: la ejecución muestra que, incluso después del [throw] de la línea 12, el programa pasa efectivamente a la cláusula [finally] de la estructura interna [try / catch / finally].

Resultados:

1
2
3
4
> php exceptions-07.php
finally 1
test in outer try / catch / finally
finally 2

7.10. Manejo de una pila de excepciones

Una excepción puede encapsular otra excepción, que a su vez puede encapsular otra más, formando finalmente una pila de excepciones. Veamos un ejemplo: [exceptions-08.php]:

<?php

// respeto estricto de los tipos declarados de los parámetros de las funciones
declare(strict_types=1);

// definimos nuestra propia familia de excepciones
class Exception1 extends \RuntimeException
{
}

class Exception2 extends \RuntimeException
{
}

class Exception3 extends \RuntimeException
{
}

// usamos nuestras excepciones
$e1 = new Exception1("Error 1...", 1, new Exception2("Error 2...", 2, new Exception3("Error 3...")));
var_dump($e1);
// uso de la pila de excepciones
$e = $e1;
do {
    // mensaje de error de la excepción actual
    print $e::class . ": " . $e->getMessage() . "\n";
    // pasamos a la excepción anterior (null si no hay ninguna)
    $e = $e->getPrevious();
} while ($e !== null);

Comentarios

  • Líneas 7–15: se definen tres clases de excepción derivadas de la excepción predefinida [RuntimeException];
  • línea 20: una instancia de la clase [Exception3] se encapsula dentro de una instancia de la clase [Exception2], que a su vez se encapsula dentro de una instancia de la clase [Exception1]. El constructor utilizado aquí es el de la clase [Exception]: [__construct(string $message = "", int $code = 0, ?Throwable $previous = null)]. El tercer parámetro del constructor permite encapsular una excepción. Esto puede ser útil en el siguiente escenario:
    • se define un método M que puede lanzar una excepción de tipo [Exception1], y solo de ese tipo, por razones de compatibilidad, por ejemplo con una interfaz;
    • sin embargo, dentro del método M pueden ocurrir otros tipos de excepciones. Para propagar un error al código que llama al método M, estas excepciones se encapsulan entonces en el tipo [Exception1], que luego se lanza. Así se garantiza que la información contenida en la excepción encapsulada, que fue la causa original del error, no se pierda;
  • Líneas 24–29: muestran cómo recorrer la pila de excepciones anidadas dentro de una excepción. El método [getPrevious] devuelve la excepción encapsulada o [null] si no hay ninguna. El bucle [do ... while] ejecuta su cuerpo al menos una vez y luego continúa mientras la condición sea verdadera.

Resultados:

> php exceptions-08.php
object(Exception1)#1 (7) {
  ["message":protected]=>
  string(10) "Error 1..."
  ["string":"Exception":private]=>
  string(0) ""
  ["code":protected]=>
  int(1)
  ["file":protected]=>
  string(76) ".../php8-oct-2026/scripts-console/exceptions/exceptions-08.php"
  ["line":protected]=>
  int(20)
  ["trace":"Exception":private]=>
  array(0) {
  }
  ["previous":"Exception":private]=>
  object(Exception2)#2 (7) {
    ["message":protected]=>
    string(10) "Error 2..."
    ["string":"Exception":private]=>
    string(0) ""
    ["code":protected]=>
    int(2)
    ["file":protected]=>
    string(76) ".../php8-oct-2026/scripts-console/exceptions/exceptions-08.php"
    ["line":protected]=>
    int(20)
    ["trace":"Exception":private]=>
    array(0) {
    }
    ["previous":"Exception":private]=>
    object(Exception3)#3 (7) {
      ["message":protected]=>
      string(10) "Error 3..."
      ["string":"Exception":private]=>
      string(0) ""
      ["code":protected]=>
      int(0)
      ["file":protected]=>
      string(76) ".../php8-oct-2026/scripts-console/exceptions/exceptions-08.php"
      ["line":protected]=>
      int(20)
      ["trace":"Exception":private]=>
      array(0) {
      }
      ["previous":"Exception":private]=>
      NULL
    }
  }
}
Exception1: Error 1...
Exception2: Error 2...
Exception3: Error 3...
  • líneas 2–50: la excepción [$e1] contiene, en su atributo [previous], la excepción [Exception2] (líneas 17–49), que a su vez contiene la excepción [Exception3] (líneas 32–48);
  • líneas 51–53: la pila de llamadas de la excepción.

7.11. Advertencias de PHP 7 que se convirtieron en errores en PHP 8

Hemos visto que la división por cero, que producía una advertencia en PHP 7, genera un error en PHP 8. No es un caso aislado: PHP 8 convirtió muchas advertencias, que antes permitían continuar la ejecución con un resultado falso, en errores. El script [exceptions-09.php] ilustra algunos de ellos:

<?php

// respeto estricto de los tipos declarados de los parámetros de las funciones
declare(strict_types=1);

// muestra el tipo y el mensaje de un error
function display(int $n, \Throwable $ex): void
{
    print "$n - " . $ex::class . ": " . $ex->getMessage() . "\n";
}

// una función con dos parámetros
function sum(int $a, int $b): int
{
    return $a + $b;
}

// 1 - variable no definida: una simple advertencia (Notice en PHP 7, Warning en PHP 8)
print "1 - [" . $unknown . "]\n";
// 2 - módulo por cero: advertencia + resultado erróneo en PHP 7, error en PHP 8
try {
    print 1 % 0;
} catch (\DivisionByZeroError $ex) {
    display(2, $ex);
}
// 3 - operación aritmética sobre un arreglo
try {
    print [] + 1;
} catch (\TypeError $ex) {
    display(3, $ex);
}
// 4 - operación aritmética sobre una cadena no numérica
try {
    print "abc" * 2;
} catch (\TypeError $ex) {
    display(4, $ex);
}
// 5 - tipo de parámetro incorrecto para una función predefinida
try {
    print strlen([1, 2]);
} catch (\TypeError $ex) {
    display(5, $ex);
}
// 6 - parámetro del tipo correcto pero con un valor inválido
try {
    print_r(array_chunk([1, 2, 3], 0));
} catch (\ValueError $ex) {
    display(6, $ex);
}
// 7 - argumentos insuficientes
try {
    print sum(1);
} catch (\ArgumentCountError $ex) {
    display(7, $ex);
}
// 8 - expresión [match] sin una rama que coincida (PHP 8.0)
try {
    $day = 8;
    print match ($day) {
        6, 7 => "weekend",
        1, 2, 3, 4, 5 => "weekday",
    };
} catch (\UnhandledMatchError $ex) {
    display(8, $ex);
}
// 9 - método llamado sobre null
try {
    $object = null;
    $object->method();
} catch (\Error $ex) {
    display(9, $ex);
}
// 10 - el operador nullsafe ?-> evita el error anterior: el resultado es null
var_dump($object?->method());

Resultados:

> php exceptions-09.php

Warning: Undefined variable $unknown in .../php8-oct-2026/scripts-console/exceptions/exceptions-09.php on line 19
1 - []
2 - DivisionByZeroError: Modulo by zero
3 - TypeError: Unsupported operand types: array + int
4 - TypeError: Unsupported operand types: string * int
5 - TypeError: strlen(): Argument #1 ($string) must be of type string, array given
6 - ValueError: array_chunk(): Argument #2 ($length) must be greater than 0
7 - ArgumentCountError: Too few arguments to function sum(), 1 passed in .../php8-oct-2026/scripts-console/exceptions/exceptions-09.php on line 52 and exactly 2 expected
8 - UnhandledMatchError: Unhandled match case 8
9 - Error: Call to a member function method() on null
NULL

Comentarios

  • Línea 19: el uso de una variable no definida sigue siendo una simple advertencia, pero de nivel [E_WARNING] (en PHP 7 era una nota [E_NOTICE]). La variable toma el valor [null], y el script continúa (líneas 2–4 de los resultados);
  • línea 22: la división por cero genera un error [DivisionByZeroError] (línea 5). Esto ya ocurría en PHP 7: allí solo la división por cero con [/] producía una simple advertencia;
  • línea 28: una operación aritmética sobre un arreglo provoca un error [TypeError] (línea 6);
  • línea 34: en PHP 7, una operación aritmética sobre una cadena no numérica generaba la advertencia “A non-numeric value encountered” y la cadena valía 0. En PHP 8, esto es un error [TypeError] (línea 7). Una cadena numérica (["12" * 2]) se sigue aceptando;
  • línea 40: en PHP 7, pasar un parámetro de tipo incorrecto a una función predefinida generaba una advertencia y la función devolvía [null]. En PHP 8, todas las funciones predefinidas lanzan un error [TypeError], igual que las funciones escritas por el desarrollador (línea 8). El mensaje identifica el parámetro por su número y su nombre;
  • línea 46: el parámetro tiene el tipo correcto ([int]) pero un valor no válido (una longitud debe ser positiva): se trata del error [ValueError], nuevo en PHP 8.0 (línea 9). En PHP 7, esto era una advertencia;
  • línea 52: la función [sum] espera dos argumentos pero recibe solo uno: error [ArgumentCountError] (línea 10);
  • líneas 59–62: la expresión [match] no tiene ninguna rama para el valor 8 y no tiene rama [default]: error [UnhandledMatchError] (línea 11). Esta es una diferencia importante con la instrucción [switch], que no hace nada cuando ningún [case] es adecuado;
  • línea 69: llamar a un método sobre [null] produce un error [Error] (línea 12). Esto ya ocurría en PHP 7;
  • línea 74: el operador null-safe [?->] (PHP 8.0) devuelve [null] si el objeto es [null], en lugar de llamar al método. Esto evita tener que escribir una prueba [if ($object !== null)] (línea 13).

Estos cambios hacen que los programas PHP 8 sean más seguros: un error detiene el procesamiento en lugar de permitir que continúe con datos incorrectos. También obligan al desarrollador a incluir las cláusulas [catch] correspondientes.

7.12. Varias cláusulas [catch], [catch] sin variable y expresión [throw]

El script [exceptions-10.php] presenta tres características de PHP 8 y un uso común del manejo de excepciones:

<?php

// respeto estricto de los tipos declarados de los parámetros de las funciones
declare(strict_types=1);

// [throw] es una expresión desde PHP 8.0: puede usarse después de ?? o en una función flecha
function readAge(array $data): int
{
    $age = $data["age"] ?? throw new \InvalidArgumentException("The age is missing");
    return is_int($age) && $age >= 0 ? $age : throw new \DomainException("Invalid age [$age]");
}

// una función flecha que solo lanza una excepción
$forbidden = fn(string $operation) => throw new \LogicException("Operation [$operation] forbidden");

// datos de prueba
$tests = [["age" => 48], [], ["age" => -4]];
foreach ($tests as $i => $data) {
    try {
        print "test $i: age=" . readAge($data) . "\n";
    } catch (\InvalidArgumentException | \DomainException $ex) {
        // una sola cláusula [catch] para dos tipos de excepciones
        print "test $i: " . $ex::class . ": " . $ex->getMessage() . "\n";
    }
}

try {
    $forbidden("deletion");
} catch (\LogicException) {
    // desde PHP 8.0, la variable de la cláusula [catch] es opcional
    print "the operation was refused\n";
}

// encapsulamiento de una excepción de bajo nivel en una excepción de la aplicación
class DaoException extends \RuntimeException
{
}

function readConfiguration(string $json): array
{
    try {
        return json_decode($json, true, flags: JSON_THROW_ON_ERROR);
    } catch (\JsonException $ex) {
        // la causa original se pasa como 3.er parámetro: no se pierde
        throw new DaoException("Unreadable configuration", 10, $ex);
    }
}

try {
    readConfiguration('{"dsn": "mysql:host=localhost"');
} catch (DaoException $ex) {
    print $ex::class . ": " . $ex->getMessage() . " (code " . $ex->getCode() . ")\n";
    print "cause: " . $ex->getPrevious()::class . ": " . $ex->getPrevious()->getMessage() . "\n";
}

Resultados:

1
2
3
4
5
6
7
> php exceptions-10.php
test 0: age=48
test 1: InvalidArgumentException: The age is missing
test 2: DomainException: Invalid age [-4]
the operation was refused
DaoException: Unreadable configuration (code 10)
cause: JsonException: Syntax error

Comentarios

  • Línea 9: a partir de PHP 8.0, [throw] es una expresión y ya no solo una instrucción. Por lo tanto, puede usarse en cualquier lugar donde se espere un valor: aquí, después del operador [??]. Si la clave [age] no existe, se lanza una excepción; de lo contrario, [$age] recibe su valor;
  • línea 10: [throw] usado en una expresión condicional [? :];
  • línea 14: una función flecha cuyo cuerpo simplemente lanza una excepción. Antes de PHP 8.0 esto no era posible: una función flecha solo puede contener una expresión;
  • línea 21: una sola cláusula [catch] para dos tipos de excepciones (líneas 3–4 de los resultados). Observe que [InvalidArgumentException] y [DomainException] derivan ambas de [LogicException]: un [catch (\LogicException $ex)] habría tenido el mismo efecto;
  • línea 29: a partir de PHP 8.0, la variable de la cláusula [catch] es opcional cuando no se necesita la excepción en sí, sino solo su tipo (línea 5);
  • líneas 35–37: una excepción específica de la aplicación. En los capítulos siguientes escribiremos capas de acceso a datos (DAO, Data Access Object) que lanzarán únicamente este tipo de excepción, sea cual sea el origen del error (archivo, JSON, base de datos);
  • líneas 39–47: la función [readConfiguration] decodifica una cadena JSON. La excepción de bajo nivel [JsonException] se intercepta y se encapsula (línea 45) en una excepción [DaoException]. La causa original se pasa como tercer parámetro al constructor;
  • línea 53: el código que llama solo conoce [DaoException], pero puede recuperar la causa original del error mediante el método [getPrevious] (líneas 6–7 de los resultados).

7.13. Convertir advertencias en excepciones: [ErrorException]

A pesar de las mejoras de PHP 8, ciertas anomalías siguen siendo simples advertencias: clave de arreglo inexistente, variable no definida, archivo que no se puede abrir con [fopen]... Estas advertencias no pueden ser interceptadas por un [try / catch]. Sin embargo, se puede instalar un manejador de errores que las convierta en excepciones [ErrorException]. Esto es lo que hace el script [exceptions-11.php]:

<?php

// respeto estricto de los tipos declarados de los parámetros de las funciones
declare(strict_types=1);

// manejador de errores: convierte las advertencias de PHP en excepciones [ErrorException]
set_error_handler(function (int $level, string $message, string $file, int $line): bool {
    throw new \ErrorException($message, 0, $level, $file, $line);
});

// una clave desconocida ya no provoca una simple advertencia sino una excepción
$person = ["lastName" => "Langevin"];
try {
    print $person["firstName"] . "\n";
} catch (\ErrorException $ex) {
    print "Error: " . $ex->getMessage() . " (line " . $ex->getLine() . ")\n";
    print "level E_WARNING: " . var_export($ex->getSeverity() === E_WARNING, true) . "\n";
}
// lo mismo al abrir un archivo inexistente
try {
    $stream = fopen(__DIR__ . "/nonexistent.txt", "r");
} catch (\ErrorException $ex) {
    print "Error: " . $ex->getMessage() . "\n";
}
// volvemos al manejador de errores de PHP
restore_error_handler();
print "end\n";

Resultados:

1
2
3
4
5
> php exceptions-11.php
Error: Undefined array key "firstName" (line 14)
level E_WARNING: true
Error: fopen(.../php8-oct-2026/scripts-console/exceptions/nonexistent.txt): Failed to open stream: No such file or directory
end

Comentarios

  • Líneas 7–9: la función [set_error_handler] configura un manejador de errores, es decir, una función a la que PHP llamará cada vez que ocurra una advertencia, una nota o una obsolescencia, en lugar de mostrar el mensaje. Recibe el nivel del error, el mensaje de error, el archivo y la línea donde ocurrió. Aquí lanza una excepción [ErrorException] que almacena esta información. El tipo de retorno [bool] es el que especifica la documentación de [set_error_handler]: la función devolvería [false] para que PHP maneje el error normalmente. Aquí nunca devuelve nada porque siempre lanza una excepción;
  • línea 14: la clave [firstName] no existe. En lugar de una advertencia, se lanza una excepción [ErrorException], que es capturada (línea 2 de los resultados);
  • línea 17: el método [getSeverity], propio de la clase [ErrorException], devuelve el nivel del error original (línea 3);
  • línea 21: intentar abrir un archivo inexistente también produce una excepción (línea 4);
  • línea 26: restaura el manejador de errores anterior, en este caso el de PHP.

Esta técnica la utilizan muchos frameworks PHP (Symfony, Laravel): durante el desarrollo, toda advertencia se convierte en una excepción, lo que obliga al desarrollador a corregir el código. La herramienta de pruebas [PHPUnit] que usaremos más adelante funciona de manera similar: puede hacer fallar una prueba si esta produce una advertencia o una obsolescencia.