Contracts

Learn about the role of Laravel Contracts, how they differ from facades, how to inject them via type hints, and how to create custom Contracts.

What is a Contract

Laravel’s “Contracts” are a set of interfaces that define the core services provided by the framework. For example, the Illuminate\Contracts\Queue\Queue contract defines the methods needed for queueing jobs, and the Illuminate\Contracts\Mail\Mailer contract defines the methods needed for sending mail.

Each contract has a corresponding implementation provided by the framework. For example, Laravel provides queue implementations for various drivers and a mailer implementation using Symfony Mailer.

All Laravel Contracts live in their own GitHub repository. This provides a quick reference for all available contracts and is a single, decoupled package you can use when building packages that interact with Laravel services.

A contract is just an interface. It works exactly like any other PHP interface. Laravel provides an implementation of the interface and injects it via the service container.

The difference between Contracts and facades

Facades and helper functions provide a simple way to use Laravel’s services without needing to type-hint and resolve contracts from the service container. In most cases, each facade has an equivalent contract.

The main differences between facades and contracts are:

Aspect	Facade	Contract
Declaring dependencies	Not required (can be called from anywhere)	Explicitly declared in the constructor
Testing	Mock with shouldReceive()	Swap out with a standard mocking library
Primary use	Convenient usage inside your application	Package development, explicit dependency management
Code readability	A single import line	Dependencies are visible at a glance in the constructor

Facades do not require you to request them in the class’s constructor, but contracts allow you to define explicit dependencies in the constructor. Some developers prefer this explicit dependency definition and use contracts. Others prefer the convenience of facades. In general, most applications can use facades throughout development without any problems.

When to use Contracts

Whether to use contracts or facades is a matter of personal or team preference. Both contracts and facades can be used to build robust, testable Laravel applications. Contracts and facades are not mutually exclusive. Some parts of your application can use facades while others depend on contracts.

Contracts are particularly useful in the following cases:

• When building a package that integrates with multiple PHP frameworks — By using the illuminate/contracts package to define your integration with Laravel services, you don’t have to require Laravel’s concrete implementation in your composer.json.
• When you want to make dependencies explicit — Just by looking at the constructor, you can see at a glance what a class depends on.
• When you want to swap implementations — It’s easier to swap in a different implementation via the service container.

How to use Contracts

How do you get an implementation of a contract? It’s actually very simple.

Many types of classes in Laravel—including controllers, event listeners, middleware, queued jobs, and even route closures—are resolved via the service container. So to get an implementation of a contract, you just “type-hint” the interface in the constructor of the class being resolved.

For example, look at the following event listener.

<?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 hints on the class’s constructor and injects the appropriate value.

Creating a custom Contract

By creating your own contracts, you can make the dependencies between components in your application explicit.

1. Define the interface

   Create the interface in the app/Contracts directory.

   <?php
   
   namespace App\Contracts;
   
   interface PaymentGateway
   {
       /**
        * Charge the specified amount.
        */
       public function charge(int $amount, string $token): bool;
   
       /**
        * Refund a payment.
        */
       public function refund(string $transactionId): bool;
   }
   
2. Create the implementation

   Create 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
       {
           // Payment processing using the Stripe API...
           return true;
       }
   
       public function refund(string $transactionId): bool
       {
           // Refund processing using the Stripe API...
           return true;
       }
   }
   
3. Bind them in a service provider

   Bind the contract to the implementation in a service provider.

   use App\Contracts\PaymentGateway;
   use App\Services\StripePaymentGateway;
   
   $this->app->singleton(PaymentGateway::class, StripePaymentGateway::class);
   
4. Receive the injection via a type hint

   Type-hint it in the constructor of a controller or other class.

   <?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
           );
   
           // ...
       }
   }
   

With this pattern, if you switch the payment service from Stripe to another provider, you only need to change the binding in one place—the controller code doesn’t need to change.

Key Contracts reference

Here’s a partial mapping of commonly used contracts to their corresponding facades:

Contract	Corresponding facade
Illuminate\Contracts\Auth\Access\Gate	Gate
Illuminate\Contracts\Auth\Factory	Auth
Illuminate\Contracts\Bus\Dispatcher	Bus
Illuminate\Contracts\Cache\Factory	Cache
Illuminate\Contracts\Cache\Repository	Cache::driver()
Illuminate\Contracts\Config\Repository	Config
Illuminate\Contracts\Console\Kernel	Artisan
Illuminate\Contracts\Container\Container	App
Illuminate\Contracts\Encryption\Encrypter	Crypt
Illuminate\Contracts\Events\Dispatcher	Event
Illuminate\Contracts\Filesystem\Factory	Storage
Illuminate\Contracts\Filesystem\Filesystem	Storage::disk()
Illuminate\Contracts\Hashing\Hasher	Hash
Illuminate\Contracts\Mail\Mailer	Mail
Illuminate\Contracts\Notifications\Dispatcher	Notification
Illuminate\Contracts\Queue\Factory	Queue
Illuminate\Contracts\Queue\Queue	Queue::connection()
Illuminate\Contracts\Queue\ShouldQueue	—
Illuminate\Contracts\Redis\Factory	Redis
Illuminate\Contracts\Routing\ResponseFactory	Response
Illuminate\Contracts\Routing\UrlGenerator	URL
Illuminate\Contracts\Session\Session	Session::driver()
Illuminate\Contracts\Translation\Translator	Lang
Illuminate\Contracts\Validation\Factory	Validator
Illuminate\Contracts\View\Factory	View

You can find a complete list of contracts in the illuminate/contracts repository.

Next steps

Facades

Learn how facades work and how to test them.