> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](https://symfony.com/doc/current/mailer.html).

All Laravel Contracts live in [their own GitHub repository](https://github.com/illuminate/contracts). 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.

<Info>
  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.
</Info>

## The difference between Contracts and facades

[Facades](/en/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 |

<Tip>
  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.**
</Tip>

## 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.

```mermaid theme={null}
flowchart LR
    A["Service provider<br>bind(Interface, Impl)"] --> B["Service container<br>Register binding"]
    C["Constructor<br>Type hint: Interface"] --> B
    B --> D["Automatic injection<br>Resolve the Interface implementation"]
    D --> E["Concrete class instance<br>Freely swappable"]
```

For example, look at the following event listener.

```php theme={null}
<?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.

<Steps>
  <Step title="Define the interface">
    Create the interface in the `app/Contracts` directory.

    ```php theme={null}
    <?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;
    }
    ```
  </Step>

  <Step title="Create the implementation">
    Create a class that implements the contract.

    ```php theme={null}
    <?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;
        }
    }
    ```
  </Step>

  <Step title="Bind them in a service provider">
    Bind the contract to the implementation in a [service provider](/en/service-providers).

    ```php theme={null}
    use App\Contracts\PaymentGateway;
    use App\Services\StripePaymentGateway;

    $this->app->singleton(PaymentGateway::class, StripePaymentGateway::class);
    ```
  </Step>

  <Step title="Receive the injection via a type hint">
    Type-hint it in the constructor of a controller or other class.

    ```php theme={null}
    <?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
            );

            // ...
        }
    }
    ```
  </Step>
</Steps>

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](https://github.com/illuminate/contracts) repository.

## Next steps

<Card title="Facades" icon="layer-group" href="/en/facades">
  Learn how facades work and how to test them.
</Card>


## Related topics

- [Support Contracts (Arrayable / Jsonable / Htmlable / Responsable)](/en/advanced/support-contracts.md)
- [Creating a Custom Provider for AI SDK](/en/advanced/ai-sdk-custom-provider.md)
- [Creating a Custom Agent for Boost](/en/advanced/boost-custom-agent.md)
- [Upgrade guide: Laravel 12 to 13](/en/blog/upgrade-12-to-13.md)
- [Upgrading from Laravel 10 to 11](/en/blog/upgrade-10-to-11.md)