laravel-exceptions
Custom exceptions with static factories and HTTP responses. Use when working with error handling, custom exceptions, or when user mentions exceptions, custom exception, error handling, HTTP exceptions.
When & Why to Use This Skill
This Claude skill provides a standardized architectural pattern for Laravel error handling using custom exceptions, static factory methods, and HTTP response mapping. It enables developers to create highly readable and maintainable code by encapsulating business logic violations into descriptive, reusable exception classes that automatically interface with Laravel's HTTP layer.
Use Cases
- Standardizing API error responses by mapping domain-specific failures to appropriate HTTP status codes (e.g., 404 for Not Found, 422 for Validation errors).
- Improving code legibility through named static factory methods, replacing generic exception constructors with semantic calls like OrderException::paymentFailed().
- Implementing clean guard clauses within Laravel Actions or Services to enforce business rules and maintain a 'fail-fast' architecture.
- Centralizing exception logic and error messages to ensure consistent API documentation and better debugging experiences for frontend developers.
| name | laravel-exceptions |
|---|---|
| description | Custom exceptions with static factories and HTTP responses. Use when working with error handling, custom exceptions, or when user mentions exceptions, custom exception, error handling, HTTP exceptions. |
Laravel Exceptions
Custom exceptions use static factory methods and implement HttpExceptionInterface.
Related guides:
- Actions - Throwing exceptions in actions
Structure
<?php
declare(strict_types=1);
namespace App\Exceptions;
use App\Exceptions\Concerns\Httpable;
use App\Models\Order;
use Exception;
use Symfony\Component\HttpKernel\Exception\HttpExceptionInterface;
class OrderException extends Exception implements HttpExceptionInterface
{
use Httpable;
public static function notFound(string|int $orderId): self
{
return new self("Order {$orderId} not found.", 404);
}
public static function cannotCancelOrder(Order $order): self
{
return new self(
"Order {$order->uuid} cannot be cancelled in its current state.",
400
);
}
public static function insufficientStock(string $productName): self
{
return new self(
"Insufficient stock for product: {$productName}",
422
);
}
public static function paymentFailed(string $reason): self
{
return new self("Payment failed: {$reason}", 402);
}
}
Httpable Concern
Usage
Throwing Exceptions
// In actions
throw OrderException::notFound($orderId);
throw OrderException::cannotCancelOrder($order);
throw OrderException::insufficientStock($product->name);
With throw_unless/throw_if
class CancelOrderAction
{
public function __invoke(Order $order): Order
{
throw_unless(
$order->canBeCancelled(),
OrderException::cannotCancelOrder($order)
);
// Continue with cancellation
}
}
Guard Methods
class ProcessOrderAction
{
public function __invoke(Order $order): void
{
$this->guard($order);
// Process order
}
private function guard(Order $order): void
{
throw_unless(
$order->isPending(),
OrderException::cannotProcessOrder($order)
);
throw_unless(
$order->hasItems(),
OrderException::orderHasNoItems($order)
);
}
}
Key Patterns
1. Static Factory Methods
Named constructors for specific exceptions:
public static function notFound(string|int $orderId): self
{
return new self("Order {$orderId} not found.", 404);
}
2. HTTP Status Codes
Pass status as second constructor parameter:
new self("Message", 404); // Not Found
new self("Message", 400); // Bad Request
new self("Message", 422); // Unprocessable Entity
new self("Message", 403); // Forbidden
3. Descriptive Messages
Include context in error messages:
"Order {$order->uuid} cannot be cancelled"
"Insufficient stock for product: {$productName}"
4. HttpExceptionInterface
Implement interface for automatic HTTP error responses:
class OrderException extends Exception implements HttpExceptionInterface
{
use Httpable;
}
Common HTTP Status Codes
400- Bad Request (business rule violation)402- Payment Required403- Forbidden (authorization failed)404- Not Found422- Unprocessable Entity (validation failed)500- Internal Server Error
Directory Structure
app/Exceptions/
├── OrderException.php
├── PaymentException.php
├── UserException.php
└── Concerns/
└── Httpable.php
Summary
Exceptions should:
- Use static factory methods
- Implement
HttpExceptionInterface - Include HTTP status codes
- Have descriptive messages with context
- Be named
{Entity}Exception
Use for business rule violations and error conditions.