Ignition Contracts Laravel Package

Getting Started

Start by requiring the package in your Laravel project:

composer require facade/ignition-contracts

This package is not meant to be used directly by end users—it’s for package authors and advanced developers extending Ignition. Your first use case is likely building a custom solution (e.g., auto-fix for a specific exception). To get started, implement the SolutionProviderContract interface and return a class implementing HasSolutionsContract on your exception. Check src/SolutionProviders/ in the Ignition repo for real examples, and read the SolutionProviderContract docblock for expected behavior.

Implementation Patterns

• Custom Solutions: Implement SolutionProviderContract in a provider class that inspects exceptions (e.g., QueryException) and returns relevant Solution instances. Each Solution must implement CanResolveContract, and typically extends SolutionProvider’s make() or getSolutionDescriptionFor() helpers.
• Exception Binding: Bind your solution provider in Ignition::registerSolutionProvider(YourSolutionProvider::class) (available via facade/laravel-ignition’s service provider).
• Decoupled Package Design: Use contracts like HasSolutionsContract, SolutionProviderContract, and SolutionContract to accept solutions without tight coupling to Ignition’s concrete classes. This ensures your package works across Ignition versions.
• Testing: Mock SolutionProviderContract and assert your exception classes return expected solutions—no need to boot the full Ignition stack.

Gotchas and Tips

• ⚠️ No Implementation Here: This package only contains interfaces. You’ll still need facade/laravel-ignition (or your own implementation) to actually render the error page and execute solutions.
• ⚠️ Version Skew: The last release is from 2020. While stable, newer Laravel versions (v9+) may use newer contracts internally. Always match ignition-contracts version with your Laravel + Ignition combo (e.g., ^2.0 for Laravel 8, ^2.5 for Laravel 9). Check composer.lock of laravel/laravel for authoritative version specs.
• 🔍 Debugging Tip: When solutions don’t appear, dump the exception type and verify your canResolveForException() method returns true. A common pitfall is canResolveForException() rejecting exceptions with subtle differences (e.g., subclasses or namespaced exceptions).
• 🛠 Extension Points: You’re not limited to exceptions—any class implementing HasSolutionsContract can offer solutions. Use Ignition::registerSolutionProvider() to register multiple providers.
• 📦 Dependency Tip: Add "require-dev": {"facade/ignition-contracts": "^2.0"} to keep it light in production. Use it only in your solution-building packages, not in app-level code.