Ignition Contracts Laravel Package

Product Decisions This Supports

• Developer experience (DX) as a product surface. This package defines the contracts (Solution, RunnableSolution, HasSolutionsForThrowable, SolutionRepository, SolutionProviderRepository) that let an error page render a suggested fix alongside a stack trace — "run this command," "set this env var," "publish this config." If DX is a differentiator, error-page remediation is a user-facing feature, and this contract is the seam to build against.
• Build vs. buy for error remediation. You are not buying functionality here — you are buying a standard shape. Deciding to implement a SolutionProvider and register it with Ignition, versus writing a bespoke exception renderer, is a real build-vs-buy call. Adopting the contract is nearly free; reinventing it means owning discovery, rendering, and the safety of runnable actions yourself.
• Roadmap input for self-healing onboarding. Misconfigured webhooks, missing API keys, stale migrations — each can become a RunnableSolution with a copy-paste or one-click fix. That's a legitimate roadmap item to size against support-ticket volume, not a nice-to-have.
• Support-cost reduction as an investment thesis. If onboarding/config errors drive a meaningful share of tickets, the pitch is measurable: fewer human-hours per misconfiguration, shorter time-to-first-success. The contract is the cheap part; authoring solutions for your top 20 failure modes is the real cost and should be scoped as such.
• Dependency and abstraction-risk assessment. In practice this arrives transitively via Ignition. The PM-relevant decision is not "should we adopt it" but "do we care that our error UX depends on a Spatie contract that is effectively in maintenance mode and has moved into Ignition's own namespace in v2+?" Plan the migration; don't build a deep dependency on the exact FQCNs.

When to Consider This Package

Consider it when:

• You are on Laravel with Ignition and want your app or package to contribute solutions to the error page rather than bare traces.
• You maintain a library and want "here's how to fix it" guidance surfaced automatically for your users — arguably the highest-value case, since it scales your docs into the failure moment.
• You want to prototype whether your custom exception hierarchy can carry remediation metadata with negligible coupling.

Look elsewhere / do not adopt directly when:

• You are tempted to composer require it explicitly. In nearly all cases it arrives transitively; a direct dependency is a smell that you're reaching one layer too low. Check composer why spatie/ignition-contracts first.
• You need rich error reporting, tracing, or alerting — that's Sentry, Flare, Bugsnag, or OpenTelemetry, not this.
• You want UI-level control over the error page. That's Ignition itself; these contracts only describe the payload.
• You are on a newer Ignition where the contracts live under Spatie\Ignition\Contracts — target that namespace and skip the standalone package.
• Your team has no appetite to maintain solution content. Stale solutions ("run php artisan x" after the command was renamed) are worse than none and erode trust in the error page.

How to Pitch It (Stakeholders)

For executives (one paragraph): This is a small, free, open-source interface package that Laravel's error page already pulls in. It doesn't add a feature by itself — it defines the standard way to attach an actionable fix ("run this command," "set this key") to an error. The opportunity is on our side: we can turn our most common setup and configuration failures into self-service fixes, reducing support load and shortening time-to-first-success for new customers. Cost to adopt is near zero; the real investment is writing and maintaining the fix content for our top failure modes, scoped and measured against current ticket volume. Risk is low but non-zero — it's a maintenance-mode dependency controlled by a third party, so we keep our usage thin, version-pin it, and treat the namespace as an adapter boundary.

For engineering (the operative version):

• Implement a SolutionProvider (registered via SolutionProviderRepository / container binding) returning BaseSolution subclasses for our known failure modes; keep our own RemediationAdvice value objects internal and map to the Spatie interfaces at the boundary so a namespace move doesn't ripple.
• Prefer RunnableSolution only for genuinely safe, idempotent actions. An error page that can execute commands is a security boundary — gate it to local/dev or require explicit confirmation.
• Verify the resolved Ignition version before writing imports; newer versions vendor these contracts under Spatie\Ignition\Contracts, and a class can satisfy one interface and not the other, producing a silently non-rendering solution.
• Add a smoke test asserting that a known throwable renders its solution, so silent failures are caught.
• Instrument which solutions render and get used; if nobody clicks them, the content budget was spent for nothing.

Bottom line: Not a product decision on its own — a cheap, low-risk enabler for a DX bet. Approve a thin integration behind an adapter, budget for content maintenance, and judge it later on ticket deflection, not on the dependency itself.