接口

引言

Laravel 的 “契约” 是一组定义框架提供的核心服务的接口。例如，Illuminate\Contracts\Queue\Queue 契约定义了队列任务所需的方法，而 Illuminate\Contracts\Mail\Mailer 契约定义了发送电子邮件所需的方法。

每个契约都有一个框架提供的对应实现。例如，Laravel 提供了一个带有多种驱动的队列实现，以及一个由 【Symfony Mailer】 提供支持的邮件发送实现。

所有 Laravel 契约都存在于其【自己的 GitHub 仓库】中。这为所有可用的契约提供了一个快速参考点，同时也提供了一个单独的、解耦的包，可以在构建与 Laravel 服务交互的包时使用。

契约与外观（Facades）

Laravel 的【外观】（facades）和辅助函数提供了一种简单的方式来使用 Laravel 的服务，而无需在服务容器中进行类型提示和解析契约。在大多数情况下，每个外观都有一个等效的契约。

与外观不同，外观不需要你在类的构造函数中引入它们，而契约允许你为类定义显式的依赖关系。一些开发者更倾向于以这种方式显式定义依赖关系，因此更喜欢使用契约，而其它开发者则喜欢外观的便利性。一般来说，大多数应用程序在开发过程中可以无问题地使用外观。

何时使用契约

是否使用契约（contracts）或门面（facades）最终取决于个人喜好以及开发团队的偏好。契约和门面都可以用来创建健壮、经过良好测试的 Laravel 应用程序。契约和门面并不是互相排斥的，你的应用程序的某些部分可以使用门面，而其他部分则依赖于契约。只要你保持类的职责聚焦，你会发现使用契约和门面之间几乎没有实际的区别。

一般来说，大多数应用程序在开发过程中可以毫无问题地使用门面。如果你正在构建一个与多个 PHP 框架集成的包，你可能希望使用 illuminate/contracts 包来定义与你的 Laravel 服务的集成，而不需要在包的 composer.json 文件中引入 Laravel 的具体实现。

如何使用契约

那么，如何获取契约的实现呢？其实很简单。

Laravel 中的许多类型的类都是通过【服务容器】来解析的，包括控制器、事件监听器、中间件、队列任务，甚至是路由闭包。因此，要获取契约的实现，你只需要在被解析类的构造函数中 “类型提示” 接口。

例如，看看这个事件监听器：

<?php

namespace App\Listeners;

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

class CacheOrderInformation
{
    /**
     * Create a new event handler instance.
     */
    public function __construct(
        protected Factory $redis,
    ) {}

    /**
     * Handle the event.
     */
    public function handle(OrderWasPlaced $event): void
    {
        // ...
    }
}

当事件监听器被解析时，服务容器会读取类构造函数上的类型提示，并注入适当的值。要了解更多关于如何在服务容器中注册内容的信息，请查看其【文档】。

契约参考

此表提供了所有 Laravel 契约及其对应外观（facades）的快速参考：

契约 引用 Facade

Illuminate\Contracts\Auth\Access\Authorizable

Illuminate\Contracts\Auth\Access\Gate

Gate

Illuminate\Contracts\Auth\Authenticatable

Illuminate\Contracts\Auth\CanResetPassword

Illuminate\Contracts\Auth\Factory

Auth

Illuminate\Contracts\Auth\Guard

Auth::guard()

Illuminate\Contracts\Auth\PasswordBroker

Password::broker()

Illuminate\Contracts\Auth\PasswordBrokerFactory

Password

Illuminate\Contracts\Auth\StatefulGuard

Illuminate\Contracts\Auth\SupportsBasicAuth

Illuminate\Contracts\Auth\UserProvider

Illuminate\Contracts\Broadcasting\Broadcaster

Broadcast::connection()

Illuminate\Contracts\Broadcasting\Factory

Broadcast

Illuminate\Contracts\Broadcasting\ShouldBroadcast

Illuminate\Contracts\Broadcasting\ShouldBroadcastNow

Illuminate\Contracts\Bus\Dispatcher

Bus

Illuminate\Contracts\Bus\QueueingDispatcher

Bus::dispatchToQueue()

Illuminate\Contracts\Cache\Factory

Cache

Illuminate\Contracts\Cache\Lock

Illuminate\Contracts\Cache\LockProvider

Illuminate\Contracts\Cache\Repository

Cache::driver()

Illuminate\Contracts\Cache\Store

Illuminate\Contracts\Config\Repository

Config

Illuminate\Contracts\Console\Application

Illuminate\Contracts\Console\Kernel

Artisan

Illuminate\Contracts\Container\Container

App

Illuminate\Contracts\Cookie\Factory

Cookie

Illuminate\Contracts\Cookie\QueueingFactory

Cookie::queue()

Illuminate\Contracts\Database\ModelIdentifier

Illuminate\Contracts\Debug\ExceptionHandler

Illuminate\Contracts\Encryption\Encrypter

Crypt

Illuminate\Contracts\Events\Dispatcher

Event

Illuminate\Contracts\Filesystem\Cloud

Storage::cloud()

Illuminate\Contracts\Filesystem\Factory

Storage

Illuminate\Contracts\Filesystem\Filesystem

Storage::disk()

Illuminate\Contracts\Foundation\Application

App

Illuminate\Contracts\Hashing\Hasher

Hash

Illuminate\Contracts\Http\Kernel

Illuminate\Contracts\Mail\Mailable

Illuminate\Contracts\Mail\Mailer

Mail

Illuminate\Contracts\Mail\MailQueue

Mail::queue()

Illuminate\Contracts\Notifications\Dispatcher

Notification

Illuminate\Contracts\Notifications\Factory

Notification

Illuminate\Contracts\Pagination\LengthAwarePaginator

Illuminate\Contracts\Pagination\Paginator

Illuminate\Contracts\Pipeline\Hub

Illuminate\Contracts\Pipeline\Pipeline

Pipeline

Illuminate\Contracts\Queue\EntityResolver

Illuminate\Contracts\Queue\Factory

Queue

Illuminate\Contracts\Queue\Job

Illuminate\Contracts\Queue\Monitor

Queue

Illuminate\Contracts\Queue\Queue

Queue::connection()

Illuminate\Contracts\Queue\QueueableCollection

Illuminate\Contracts\Queue\QueueableEntity

Illuminate\Contracts\Queue\ShouldQueue

Illuminate\Contracts\Redis\Factory

Redis

Illuminate\Contracts\Routing\BindingRegistrar

Route

Illuminate\Contracts\Routing\Registrar

Route

Illuminate\Contracts\Routing\ResponseFactory

Response

Illuminate\Contracts\Routing\UrlGenerator

URL

Illuminate\Contracts\Routing\UrlRoutable

Illuminate\Contracts\Session\Session

Session::driver()

Illuminate\Contracts\Support\Arrayable

Illuminate\Contracts\Support\Htmlable

Illuminate\Contracts\Support\Jsonable

Illuminate\Contracts\Support\MessageBag

Illuminate\Contracts\Support\MessageProvider

Illuminate\Contracts\Support\Renderable

Illuminate\Contracts\Support\Responsable

Illuminate\Contracts\Translation\Loader

Illuminate\Contracts\Translation\Translator

Lang

Illuminate\Contracts\Validation\Factory

Validator

Illuminate\Contracts\Validation\ValidatesWhenResolved

Illuminate\Contracts\Validation\ValidationRule

Illuminate\Contracts\Validation\Validator

Validator::make()

Illuminate\Contracts\View\Engine

Illuminate\Contracts\View\Factory

View

Illuminate\Contracts\View\View

View::make()