Skip to main content

Documentation Index

Fetch the complete documentation index at: https://kawax.biz/llms.txt

Use this file to discover all available pages before exploring further.

​
What are contracts?

Laravel’s “contracts” are a set of interfaces that define the core services provided by the framework. For example, Illuminate\Contracts\Queue\Queue defines the methods needed for queueing jobs, while Illuminate\Contracts\Mail\Mailer defines the methods needed for sending email. Each contract has a corresponding implementation provided by the framework. Laravel ships a queue implementation with a variety of drivers and a mailer implementation powered by Symfony Mailer. All Laravel contracts live in their own GitHub repository, which provides a quick reference for all available contracts and a single, decoupled package you can use when building packages that interact with Laravel services.
Contracts are plain PHP interfaces. Laravel resolves the concrete implementation from the service container and injects it wherever you type-hint the interface.

​
Contracts vs. facades

Facades and helper functions let you use Laravel’s services without type-hinting anything. In most cases, each facade has an equivalent contract.
AspectFacadesContracts
Declaring dependenciesNot required — call from anywhereDeclared explicitly in the constructor
TestingMock via shouldReceive()Swap via any standard mock library
Primary useConvenience inside your applicationPackage development, explicit dependency management
ReadabilityOne import lineDependencies visible in the constructor
Unlike facades, which require no constructor parameter, contracts let you define explicit dependencies. Some developers prefer this explicitness; others prefer the convenience of facades. In general, most applications can use facades without issue during development.

​
When to use contracts

Both contracts and facades produce robust, testable Laravel applications—they are not mutually exclusive. You can use facades in some parts of your application and contracts in others. Contracts are particularly useful when:
  • Building packages that work with multiple PHP frameworks — use illuminate/contracts to define your integration with Laravel services without requiring Laravel’s concrete implementations in your composer.json.
  • You want explicit dependencies — a glance at the constructor tells you exactly what a class depends on.
  • You need to swap implementations — binding a different concrete class in the service container is straightforward when you depend on an interface.

​
How to use contracts

Getting a contract implementation is simple. Laravel resolves controllers, event listeners, middleware, queued jobs, and route closures through the service container. Type-hint the interface in the constructor of the class being resolved, and the container injects the right value automatically. For example, this event listener type-hints the Illuminate\Contracts\Redis\Factory contract: 
<?php

namespace App\Listeners;

use App\Events\OrderWasPlaced;
use App\Models\User;
use Illuminate\Contracts\Redis\Factory;

class CacheOrderInformation
{
    /**
     * Create the event listener.
     */
    public function __construct(
        protected Factory $redis,
    ) {}

    /**
     * Handle the event.
     */
    public function handle(OrderWasPlaced $event): void
    {
        // ...
    }
}
When the event listener is resolved, the service container reads the type-hint and injects the appropriate value.

​
Defining your own contracts

You can define custom contracts to clarify dependencies between components in your application.
1

Define the interface

Create an interface in app/Contracts:
<?php

namespace App\Contracts;

interface PaymentGateway
{
    public function charge(int $amount, string $token): bool;

    public function refund(string $transactionId): bool;
}
2

Create the implementation

Write a class that implements the contract:
<?php

namespace App\Services;

use App\Contracts\PaymentGateway;

class StripePaymentGateway implements PaymentGateway
{
    public function charge(int $amount, string $token): bool
    {
        // Stripe API logic...
        return true;
    }

    public function refund(string $transactionId): bool
    {
        // Stripe API logic...
        return true;
    }
}
3

Bind the contract in a service provider

Register the binding in a service provider:
use App\Contracts\PaymentGateway;
use App\Services\StripePaymentGateway;

$this->app->singleton(PaymentGateway::class, StripePaymentGateway::class);
4

Type-hint in your controller or service

<?php

namespace App\Http\Controllers;

use App\Contracts\PaymentGateway;
use Illuminate\Http\Request;

class OrderController extends Controller
{
    public function __construct(
        protected PaymentGateway $payment,
    ) {}

    public function store(Request $request)
    {
        $this->payment->charge(
            $request->amount,
            $request->payment_token
        );

        // ...
    }
}
This pattern means switching from Stripe to another provider only requires changing the binding in one place—no changes to the controller.

​
Contract reference

A quick reference for the most commonly used contracts and their corresponding facades:
ContractFacade
Illuminate\Contracts\Auth\Access\GateGate
Illuminate\Contracts\Auth\FactoryAuth
Illuminate\Contracts\Bus\DispatcherBus
Illuminate\Contracts\Cache\FactoryCache
Illuminate\Contracts\Cache\RepositoryCache::driver()
Illuminate\Contracts\Config\RepositoryConfig
Illuminate\Contracts\Console\KernelArtisan
Illuminate\Contracts\Container\ContainerApp
Illuminate\Contracts\Encryption\EncrypterCrypt
Illuminate\Contracts\Events\DispatcherEvent
Illuminate\Contracts\Filesystem\FactoryStorage
Illuminate\Contracts\Filesystem\FilesystemStorage::disk()
Illuminate\Contracts\Hashing\HasherHash
Illuminate\Contracts\Mail\MailerMail
Illuminate\Contracts\Notifications\DispatcherNotification
Illuminate\Contracts\Queue\FactoryQueue
Illuminate\Contracts\Queue\QueueQueue::connection()
Illuminate\Contracts\Queue\ShouldQueue—
Illuminate\Contracts\Redis\FactoryRedis
Illuminate\Contracts\Routing\ResponseFactoryResponse
Illuminate\Contracts\Routing\UrlGeneratorURL
Illuminate\Contracts\Session\SessionSession::driver()
Illuminate\Contracts\Translation\TranslatorLang
Illuminate\Contracts\Validation\FactoryValidator
Illuminate\Contracts\View\FactoryView
The full list is available in the illuminate/contracts repository.

Facades

Review how facades work and how they compare to contracts.
Last modified on April 9, 2026