PHP Academy · Lección

Creación de excepciones personalizadas

Extienda la clase Exception para crear tipos de error específicos del dominio.

Creación de excepciones personalizadas es una lección gratuita de PHP Academy en CoddyKit. Esta es la lección 3 de 4. Puedes leer la lección completa abajo gratuitamente — luego la practicas en el navegador con un editor de código integrado y un tutor de IA 24/7. Forma parte de la ruta de aprendizaje de PHP Academy, y tu progreso se sincroniza en la web y la app de CoddyKit. El curso de PHP Academy incluye 4 lecciones en total.

¿Por qué utilizar excepciones personalizadas?

Las excepciones personalizadas le permiten:

Distinguir los errores de su aplicación de los errores genéricos de PHP
Transportar datos específicos del dominio (ID del pedido, ID del usuario, etc.)
Capturar tipos de error específicos en distintas capas
Crear jerarquías de errores claras y autoexplicativas

Extender Exception

Cree una excepción personalizada extendiendo la clase base Exception:

<?php
class ValidationException extends \Exception
{
    private array $errors;

    public function __construct(array $errors, string $message = '', int $code = 0)
    {
        $this->errors = $errors;
        parent::__construct($message ?: implode(', ', $errors), $code);
    }

    public function getErrors(): array
    {
        return $this->errors;
    }
}

Usar una excepción personalizada

Lance y capture su excepción personalizada:

<?php
function createUser(array $data): void {
    $errors = [];
    if (empty($data['email'])) $errors[] = 'Email required';
    if (empty($data['name']))  $errors[] = 'Name required';

    if ($errors) {
        throw new ValidationException($errors);
    }
    // save user...
}

try {
    createUser([]);
} catch (ValidationException $e) {
    foreach ($e->getErrors() as $err) {
        echo '- ' . $err . PHP_EOL;
    }
}

Diseño de la jerarquía de excepciones

Diseñe una jerarquía para su dominio:

<?php
// Base exception for your app
class AppException extends \RuntimeException {}

// Domain-specific exceptions
class NotFoundException extends AppException {}
class AuthException extends AppException {}
class PaymentException extends AppException {}

// Specific payment errors
class InsufficientFundsException extends PaymentException {
    public function __construct(public readonly float $balance, public readonly float $required) {
        parent::__construct("Insufficient funds: have $balance, need $required");
    }
}

Capturar por jerarquía

Capture una clase base para gestionar todas las excepciones derivadas:

<?php
try {
    processPayment($order);
} catch (InsufficientFundsException $e) {
    echo 'Low balance: need ' . $e->required;
} catch (PaymentException $e) {
    echo 'Payment failed: ' . $e->getMessage();
} catch (AppException $e) {
    echo 'App error: ' . $e->getMessage();
} catch (\Throwable $e) {
    // Last resort
    error_log($e);
}

Añadir contexto a las excepciones

Enriquezca las excepciones con datos adicionales para facilitar la depuración:

<?php
class HttpException extends \RuntimeException
{
    public function __construct(
        private int    $statusCode,
        string         $message = '',
        ?\Throwable    $previous = null
    ) {
        parent::__construct($message, $statusCode, $previous);
    }

    public function getStatusCode(): int
    {
        return $this->statusCode;
    }
}

Ejemplo de excepción HTTP

Uso de la excepción HTTP en una aplicación web:

<?php
try {
    $user = findUserById($id);
    if (!$user) throw new HttpException(404, 'User not found');
    if (!$user->canAccess($resource)) {
        throw new HttpException(403, 'Access denied');
    }
} catch (HttpException $e) {
    http_response_code($e->getStatusCode());
    echo json_encode(['error' => $e->getMessage()]);
}

Excepciones basadas en interfaces

Utilice interfaces para agrupar clases de excepciones no relacionadas:

<?php
interface UserFacingException
{
    public function getUserMessage(): string;
}

class ValidationException extends \Exception implements UserFacingException
{
    public function getUserMessage(): string
    {
        return 'Please check your input: ' . $this->getMessage();
    }
}

// In controller:
catch (UserFacingException $e) {
    echo $e->getUserMessage();
}

Patrón de constructor con nombre

Utilice métodos de fábrica estáticos para escenarios de excepción habituales:

<?php
class OrderException extends \RuntimeException
{
    public static function notFound(int $id): self
    {
        return new self("Order #$id not found", 404);
    }

    public static function alreadyShipped(int $id): self
    {
        return new self("Order #$id already shipped", 409);
    }
}

throw OrderException::notFound($orderId);

Serializar excepciones

Convierta los datos de una excepción en un array para los registros o las respuestas de la API:

<?php
function exceptionToArray(\Throwable $e): array {
    return [
        'type'    => get_class($e),
        'message' => $e->getMessage(),
        'code'    => $e->getCode(),
        'file'    => $e->getFile(),
        'line'    => $e->getLine(),
        'trace'   => $e->getTraceAsString(),
        'previous' => $e->getPrevious()
            ? exceptionToArray($e->getPrevious())
            : null,
    ];
}

Prácticas recomendadas para excepciones personalizadas

Directrices para diseñar excepciones personalizadas:

Extienda RuntimeException para condiciones inesperadas
Extienda LogicException para errores del programador (argumentos no válidos)
No cree una clase de excepción para cada mensaje posible; utilice códigos en su lugar
Mantenga los nombres de las clases de excepción en PascalCase y terminados en Exception
Documente qué excepciones puede lanzar cada método

Comprobación rápida

¿Qué clase base de PHP debe extender para crear una excepción personalizada que represente un error lógico en su código?

Repaso: excepciones personalizadas

Resumen de las excepciones personalizadas:

Extienda Exception o una subclase
Añada propiedades y métodos específicos del dominio
Diseñe jerarquías: capture la clase principal para capturar todas las derivadas
Utilice interfaces para agrupar excepciones no relacionadas
Utilice constructores estáticos con nombre para mejorar la claridad
Llame siempre a parent::__construct()

Preguntas frecuentes

¿La lección «Creación de excepciones personalizadas» es gratis?

Sí — el texto completo de «Creación de excepciones personalizadas» es gratis para leer aquí en la web. Para practicarla de forma interactiva (editor de código integrado y tutor de IA 24/7) y desbloquear el resto del curso de PHP Academy, actualiza a CoddyKit PRO. El curso de PHP Academy incluye 4 lecciones en total.

¿Qué aprenderé en «Creación de excepciones personalizadas»?

Extienda la clase Exception para crear tipos de error específicos del dominio. Practicas PHP Academy con código real que ejecutas directamente en el navegador, y un tutor de IA 24/7 responde tus preguntas mientras trabajas en la lección.

¿Necesito experiencia previa para empezar PHP Academy?

No se requiere experiencia previa. PHP Academy en CoddyKit está estructurado para principiantes hasta estudiantes avanzados, así que puedes empezar aquí o desde el inicio y avanzar a tu ritmo. Esta es la lección 3 de 4.

¿Cuánto tiempo toma la lección «Creación de excepciones personalizadas»?

La mayoría de las lecciones de CoddyKit toman alrededor de 5–10 minutos. Cada una es compacta e interactiva, así que avanzas constantemente y retomas exactamente por donde dejaste en la web y la app.

¿Puedo escribir y ejecutar código en esta lección de PHP Academy?

Sí. Cada lección de PHP Academy incluye un editor de código integrado, así que escribes y ejecutas código real directamente en tu navegador y obtienes retroalimentación instantánea de IA — sin configuración local necesaria.

Todas las lecciones de este curso

Tipos de errores y generación de informes en PHP
Try, Catch y Finally
Creación de excepciones personalizadas
Registro de errores y prácticas recomendadas

← Volver a PHP Academy