Advanced Types Laravel Package

Getting Started

Start by confirming the package’s exception surface, because 0.3.1 changes it:

1. Update dependencies and verify jeckel-lab/contract is installed:

   composer update jeckel-lab/contract
   

2. Inspect composer.json and the package README for the exact namespace of the contract DomainException.
3. Search the codebase for imports/catches of the package’s old exception classes:

   grep -R "PackageException\|DomainException" app tests
   

4. Look first at your Laravel exception handling boundary (bootstrap/app.php withExceptions, app/Exceptions/Handler.php, or API middleware) where package exceptions are converted into HTTP responses.

First use case: throw a contract DomainException from a domain/application action and catch it at the HTTP boundary.

use JeckelLab\Contract\DomainException; // verify exact namespace in the package

final class CancelOrder
{
    public function __invoke(Order $order): void
    {
        if (! $order->canBeCancelled()) {
            throw new DomainException('Order cannot be cancelled', [
                'order_id' => $order->id,
            ]);
        }

        // ...
    }
}

Then map DomainException centrally to a response rather than catching it in every controller.

Implementation Patterns

• Depend on the contract exception, not concrete package exceptions. After 0.3.1, application code should catch the DomainException type from jeckel-lab/contract, not package-specific exception classes.
• Throw domain exceptions from domain/application layers. Use them for business-rule failures such as invalid state transitions, missing permissions, or invariants. Keep Laravel validation exceptions for request validation.
• Centralize rendering. In Laravel 11+ use withExceptions(); in older apps use the exception handler. Map known domain exceptions to status codes and problem-details/API responses.

->withExceptions(function (Exceptions $exceptions) {
    $exceptions->render(function (DomainException $e, Request $request) {
        if ($request->expectsJson()) {
            return response()->json([
                'message' => $e->getMessage(),
                'context' => $e->getContext(), // if exposed by contract
            ], 422);
        }
    });
})

• Treat exceptions as immutable value objects. Pass message/context/code through constructors or named constructors. Do not mutate exception state after construction.
• Wrap infrastructure failures. Do not leak PDO, HTTP client, or filesystem exceptions from package code. Catch them and rethrow as contract DomainException with safe context.
• Test exception type and context. Assert instanceof DomainException, not only the message string. Avoid asserting mutable exception state because 0.3.1 makes exceptions immutable.
• Use named constructors for readability. Prefer OrderAlreadyCancelled::forOrder($id) style factories over ad-hoc messages scattered across services.

Gotchas and Tips

• Breaking change: all package exceptions moved to jeckel-lab/contract. Existing catch blocks, imports, and tests referencing old exception classes will fail or stop matching. Update them to the contract type.
• Catching too broadly can hide bugs. Catching contract DomainException is fine at the boundary, but do not catch it around internal domain logic unless you are intentionally translating it.
• Immutability means no setters. If you previously modified an exception’s message, code, or context after construction, move that data into the constructor or a named constructor.
• Custom exceptions must stay immutable too. If you extend the contract DomainException, avoid adding mutable properties and do not expose setters. Initialize all state in the constructor.
• “Throw only Domain Exception” is a package rule. If you contribute or extend package code, wrap third-party exceptions instead of throwing generic Exception or RuntimeException.
• Check dependency/autoload issues first. If the contract class is “not found,” confirm jeckel-lab/contract is in composer.lock, run composer dump-autoload, and verify the namespace.
• Do not leak sensitive context. Immutable context is convenient for debugging but should not be returned verbatim in production API responses.
• Debugging: inspect the previous exception chain and log domain context separately. A domain exception often wraps an infrastructure failure, so getPrevious() matters.
• Extension point: subclass the contract DomainException for package-specific semantics, but keep the base contract type catchable at application boundaries.