laravel-exceptions
Domain exceptions are one class per entity with named static factories; those that can reach a client carry their own status code and reporting rule. Use when throwing from an action guard, adding an exception factory, or deciding how an exception renders and reports.
How do I install this agent skill?
npx skills add https://github.com/leeovery/agentic-skills --skill laravel-exceptionsIs this agent skill safe to install?
- Gen Agent Trust Hubpass
This skill provides documentation and code templates for implementing custom Laravel exceptions. It does not contain any executable scripts, external dependencies, or network operations. No security risks were identified.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
- ZeroLeakspass
Score: 93/100 · 2 sections analyzed
What does this agent skill do?
Laravel Exceptions
A broken business rule is a domain exception, thrown by the action that owns the rule. Each entity has one exception class whose static factories name every way its operations can fail. An exception that can surface from a request implements Symfony's HttpExceptionInterface through the Httpable concern, so it carries its own status code and decides its own reporting, and the exception handler needs no wiring for it.
Rules
- One class per entity, a named factory per failure.
{Entity}Exceptioninapp/Exceptions/. Factories read as the failure:cannot{Verb}()for a business rule (cannotCancel()),failedTo{Verb}()for an operation that went wrong,{thing}NotFound()for something missing that isn't a model. Callers nevernewthe exception or pass it a message. - Guards throw the factory.
throw_unless($condition, OrderException::cannotCancel())in the action'sguard(). laravel-actions owns guards. - Exceptions that can surface from a request implement
HttpExceptionInterfaceand useHttpable. Laravel then renders them with their own status, headers and message. - Every HTTP factory passes its status code. Pick the code that fits the failure; there's no fixed table. The concern falls back to 500 for a missing code, which turns an expected failure into a server error.
- Write the message for the client. Laravel sends an
HttpExceptionInterfaceexception's message to the client even withAPP_DEBUGoff, 5xx included; every other exception becomesServer Error. Give a sentence the caller can act on, with public identifiers only: a fixed sentence, orsprintfwith an(ulid: %s)suffix. Never a path, a query, a provider's raw error or the cause's message. - Chain the cause. A factory that wraps a caught exception takes
Throwable $previousand passes it as the third constructor argument. The report keeps the original trace; the client sees only your message. - Client errors aren't reported during a request; server errors always are. A 4xx during a request is expected: the client has been told and nothing is broken. A 5xx means something is broken whoever called. In a job or scheduled task there's no client, so every failure needs attention.
Httpable::report()does this, and it must returntrueto skip reporting: Laravel treats any return value exceptfalseas "handled" and skips its own reporting, the error tracker's hook included. - Control-flow exceptions aren't HTTP. An exception thrown and caught inside a job to choose a path extends
Exceptionwith no interface and no concern. It never reaches a client. - Let the framework map its own failures. A missing model is
findOrFail()or route binding (404), a denied policy isAuthorizationException(403), invalid input is a Form Request (422). Don't write factories that duplicate them. - Nothing per exception in the
ExceptionBooter. It holds the error tracker's hook; the interface and the concern do the mapping, so norender()orreport()callbacks for domain exceptions. laravel-providers owns booters.
Example
<?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;
use Throwable;
class OrderException extends Exception implements HttpExceptionInterface
{
use Httpable;
public static function cannotCancel(): self
{
return new self('This order can no longer be cancelled.', 409);
}
public static function cannotShipWithoutAddress(Order $order): self
{
return new self(
sprintf('This order has no delivery address and cannot be shipped (ulid: %s).', $order->ulid),
422,
);
}
public static function failedToRefund(Order $order, Throwable $previous): self
{
return new self(
sprintf('The refund could not be processed. Please try again later (ulid: %s).', $order->ulid),
502,
$previous,
);
}
}
The Httpable concern
One per project, in app/Exceptions/Concerns/. If the project already has one, use it, but check its report(): one that returns runningInConsole() is inverted, reporting every client error during requests and silencing every failure in queues.
<?php
declare(strict_types=1);
namespace App\Exceptions\Concerns;
use Illuminate\Contracts\Foundation\Application;
trait Httpable
{
public function report(Application $app): bool
{
// Any return except false tells Laravel the exception is handled and skips default reporting.
return $this->getStatusCode() < 500 && ! $app->runningInConsole();
}
public function getStatusCode(): int
{
return $this->code ?: 500;
}
/** @return array<string, string> */
public function getHeaders(): array
{
return [];
}
}
The handler resolves report() through the container, so it can take the Application. Use ?: for the status fallback, not ??: Exception::$code is an int that defaults to 0, never null, and Symfony rejects status 0.
Reach for these when the situation calls for it
An action rejects a specific input field. When a rule only the action can check (stock, a combination of records) belongs to one field, subclass ValidationException with factories built on withMessages(). It renders as a 422 with field errors, exactly like a Form Request failure, and isn't reported.
class OrderValidationException extends ValidationException
{
public static function productUnavailable(Product $product): static
{
return static::withMessages([
'items' => sprintf('%s is no longer available.', $product->name),
]);
}
}
Testing
Assert the class and the factory's message, so changing the text doesn't break the test:
test('will not cancel a shipped order', function (): void {
$order = Order::factory()->shipped()->create();
resolve(CancelOrderAction::class)($order);
})->throws(OrderException::class, OrderException::cannotCancel()->getMessage());
In an HTTP test, assert the status and the same message: ->assertConflict()->assertJsonPath('message', OrderException::cannotCancel()->getMessage()). More in laravel-testing.
Anti-patterns
- ❌
return $this->code ?? 500;: the fallback never fires. - ❌
report()returning$app->runningInConsole(). - ❌
abort(409, '...')orabort_if()in an action. It ties the action to HTTP and loses the named failure. - ❌
throw new OrderException('...')at the call site, or a factory that takes the message as an argument. - ❌ A message carrying a file path, an internal id, SQL or
$previous->getMessage(). - ❌ An
OrderException::notFound()doing whatfindOrFail()already does. - ❌
$exceptions->render(fn (OrderException $e) => ...)in theExceptionBooter. - ❌
HttpExceptionInterfaceon an exception that never leaves a job.
Related
- laravel-actions: the guards that throw these exceptions
- laravel-state-machines: state preconditions behind
cannot{Verb}() - laravel-validation: input validation in Form Requests
- laravel-providers: the
ExceptionBooterand the error tracker's hook - laravel-testing: testing style
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/leeovery/agentic-skills/laravel-exceptions">View laravel-exceptions on skillZs</a>