Advanced Types Laravel Package

Product Decisions This Supports

• Build vs. buy for domain error handling: This package is positioning a reusable exception layer rather than hand-rolling try/catch taxonomies in every service. The 0.3.1 move of all exceptions into jeckel-lab/contract means the error vocabulary is now a shared, versioned contract — a deliberate "buy/borrow once, enforce everywhere" decision rather than per-team convention.
• Feature boundary enforcement: "Throw only Domain Exception" is an architectural policy, not just a code change. It constrains what can cross a domain boundary, which supports decisions about where framework exceptions (HTTP, validation, DB) are translated and where they must not leak.
• Cross-package and cross-service consistency: Extracting exceptions to a contract package is the enabling step for sharing error semantics between Laravel apps, modules, or sibling packages. This is a roadmap signal toward interoperability and eventually public API stability.
• Immutability as a product constraint: Immutable exceptions make failure states safe to pass across layers, log uniformly, serialize into API responses, and assert on in tests. That supports decisions about error observability and client-facing error contracts.
• Version risk governance: The release is numbered 0.3.1 (patch), yet relocating exception classes and narrowing what can be thrown will break consumer code that catches specific exception types. The PM-level decision this drives is whether to treat the package as an internal spike dependency or a governed dependency with pinned versions and a migration plan.

When to Consider This Package

Consider adoption when:

• You are building a domain-centric or modular Laravel application where exception types are part of the internal contract between layers or modules.
• You already have (or want) a shared contracts package and need a consistent error vocabulary that does not depend on the framework.
• You need failures to be safely passed, logged, and serialized — immutability and a single base domain exception make boundary translation and API error mapping predictable.
• You can absorb pre-1.0 churn: 0.x means the API is explicitly unstable, and 0.3.1 demonstrates that patch numbers here do not guarantee backward compatibility.

Look elsewhere when:

• You need a stable, semver-guaranteed public API — this is not that yet.
• Your application is a straightforward CRUD Laravel app where HttpException and validation exceptions already cover the surface area; the abstraction cost outweighs the benefit.
• You require framework-native HTTP status mapping out of the box, or you depend on catching granular third-party exception classes.
• Your team has no ownership of the contract package's release cadence; adopting it without the ability to pin and upgrade deliberately introduces supply-chain and upgrade risk.

Adoption criteria to gate on: pinned version in composer.json, a test asserting your boundary translation from DomainException to HTTP/problem-details responses, and a documented upgrade path for each 0.x bump.

How to Pitch It (Stakeholders)

Executives: A small, low-cost dependency that standardizes how failures are represented across our Laravel services, so errors stay consistent as we split modules and expose APIs. The trade-off is maturity: the package is pre-1.0 and its 0.3.1 "patch" changes exception types in a way that can break callers, so we should adopt it deliberately with pinned versions rather than treat it as settled infrastructure.

Engineering: 0.3.1 relocates every exception into jeckel-lab/contract, makes them immutable, and enforces that only the contract's DomainException is thrown. Practically: add the contract dependency, catch DomainException at your boundaries instead of concrete classes, translate once to HTTP/problem-details responses, and treat the release as breaking despite the patch number. Upside is a clean, framework-free error contract and immutable failures that are safe to log and serialize; cost is that any catch blocks referencing old exception classes must be migrated now, and we should expect more churn before 1.0.