PHP Academy · Aula

Criação de exceções personalizadas

Estenda a classe Exception para criar tipos de erro específicos do domínio.

Criação de exceções personalizadas é uma aula grátis de PHP Academy no CoddyKit. Esta é a aula 3 de 4. Você pode ler a aula completa abaixo gratuitamente — depois pratica ao vivo no navegador com um editor de código integrado e um tutor de IA 24/7. Faz parte do caminho de aprendizado de PHP Academy, e seu progresso é sincronizado entre a web e o app CoddyKit. O curso de PHP Academy inclui 4 aulas no total.

Por que usar exceções personalizadas?

As exceções personalizadas permitem:

Distinguir os erros da sua aplicação dos erros genéricos do PHP
Transportar dados específicos do domínio (ID do pedido, ID do usuário etc.)
Capturar tipos específicos de erro em diferentes camadas
Criar hierarquias de erros significativas e autoexplicativas

Estendendo Exception

Crie uma exceção personalizada estendendo a classe 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;
    }
}

Usando uma exceção personalizada

Lance e capture sua exceção 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;
    }
}

Projeto da hierarquia de exceções

Projete uma hierarquia para seu domínio:

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

Capturando pela hierarquia

Capture uma classe base para tratar todas as exceções 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);
}

Adicionando contexto às exceções

Enriqueça as exceções com dados adicionais para depuração:

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

Exemplo de exceção HTTP

Usando a exceção HTTP em uma aplicação 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()]);
}

Exceções baseadas em interface

Use interfaces para agrupar classes de exceção não 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();
}

Padrão de construtor nomeado

Use métodos de fábrica estáticos para cenários comuns de exceção:

<?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);

Serializando exceções

Converta os dados da exceção em uma matriz para registros ou respostas da 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,
    ];
}

Boas práticas para exceções personalizadas

Diretrizes para projetar exceções personalizadas:

Estenda RuntimeException para condições inesperadas
Estenda LogicException para erros do programador (argumentos inválidos)
Não crie uma classe de exceção para cada mensagem possível — use códigos
Mantenha os nomes das classes de exceção em PascalCase, terminando em Exception
Documente quais exceções cada método pode lançar

Verificação rápida

Qual classe base do PHP deve ser estendida para criar uma exceção personalizada que represente um erro lógico no seu código?

Recapitulação: exceções personalizadas

Resumo das exceções personalizadas:

Estenda Exception ou uma subclasse
Adicione propriedades e métodos específicos do domínio
Projete hierarquias — capture o pai para capturar todos os filhos
Use interfaces para agrupar exceções não relacionadas
Use construtores nomeados estáticos para obter clareza
Sempre chame parent::__construct()

Perguntas Frequentes

A aula “Criação de exceções personalizadas” é grátis?

Sim — o texto completo de “Criação de exceções personalizadas” é grátis para ler aqui na web. Para praticá-la interativamente (um editor de código integrado e um tutor de IA 24/7) e desbloquear o restante do curso de PHP Academy, atualize para CoddyKit PRO. O curso de PHP Academy inclui 4 aulas no total.

O que vou aprender em “Criação de exceções personalizadas”?

Estenda a classe Exception para criar tipos de erro específicos do domínio. Você pratica PHP Academy com código prático que executa diretamente no navegador, e um tutor de IA 24/7 responde suas dúvidas enquanto trabalha na aula.

Preciso ter experiência prévia para começar PHP Academy?

Nenhuma experiência prévia é necessária. PHP Academy no CoddyKit é estruturado para alunos iniciantes até avançados, então você pode começar aqui ou desde o início e aprender no seu ritmo. Esta é a aula 3 de 4.

Quanto tempo leva a aula “Criação de exceções personalizadas”?

A maioria das aulas CoddyKit leva cerca de 5–10 minutos. Cada uma é compacta e interativa, então você faz progresso constante e retoma exatamente de onde parou entre web e app.

Posso escrever e executar código nesta aula de PHP Academy?

Sim. Cada aula de PHP Academy inclui um editor de código integrado, então você escreve e executa código real direto no navegador e recebe feedback de IA instantaneamente — nenhuma configuração local necessária.

Todas as aulas deste curso

← Voltar para PHP Academy