Contracts Laravel Package

Getting Started

Start by understanding that illuminate/contracts is a subtree split of interfaces from laravel/framework — it provides no implementations. In practice, developers use these interfaces in Laravel applications to decouple code from concrete services. The first step is identifying which core contracts are relevant to your use case:

• Illuminate\Contracts\Mail\Mailer for sending emails
• Illuminate\Contracts\Queue\Job or Queue for queueing
• Illuminate\Contracts\Cache\Repository for caching
• Illuminate\Contracts\Http\Kernel for HTTP request lifecycle

In a Laravel app (which already depends on laravel/framework), these interfaces are automatically registered — you can immediately type-hint them in constructors or service method signatures. Start using them by modifying a service (e.g., a job or middleware) to depend on Cache\Repository instead of CacheManager or a facade.

Implementation Patterns

• Bind custom implementations in service providers:

  // AppServiceProvider@boot
  $this->app->bind(\Illuminate\Contracts\Mail\Mailer::class, \App\Mail\CustomMailer::class);
  

  Then inject \Illuminate\Contracts\Mail\Mailer in services — Laravel resolves CustomMailer.

• Implement contract interfaces for extensibility:
  Build a class like class MyQueueJob implements Job to integrate with Laravel’s queue worker. Ensure method signatures match the contract exactly (e.g., fire(), failed()).

• Test in isolation:
  Use mock(\Illuminate\Contracts\Redis\Factory::class) in unit tests to stub Redis without bootstrapping the full app — avoids overhead and external dependencies.

• Package development:
  Require "illuminate/contracts": "^11.0" in your package, type-hint against contracts (e.g., Http\Kernel), and document how consumers should bind their own implementations — making your package framework-agnostic by interface.

Gotchas and Tips

• ⚠️ Never install illuminate/contracts standalone: It lacks implementations and will cause fatal errors. Only install it via laravel/framework. If you see it in composer.lock, it’s there as a transitive dependency — do not pin it directly.
• ⚠️ Version drift breaks things: Laravel 10’s Cache\Repository contract may lack methods added in Laravel 11. Always align illuminate/contracts with your Laravel major version (check laravel/framework’s composer.json for the exact constraint).
• 💡 Use php artisan about to verify installed Laravel version and confirm contract compatibility.
• 💡 Prefer app-specific contracts: Instead of extending core contracts (e.g., Cache\Repository), define App\Contracts\Cache\ExtendedRepository to avoid tightly coupling to Laravel internals and reduce breakage on upgrades.
• 🔧 Troubleshoot binding failures with:

  php artisan route:clear && php artisan config:clear && php artisan cache:clear
  

  Then inspect binding resolution in Tinker:

  >>> app(\Illuminate\Contracts\Auth\Factory::class)