契约 (Contracts)

• 简介
  • 契约与外观 (Facades)
• 何时使用契约
• 如何使用契约
• 契约参考

简介

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

每个契约都有框架提供的相应实现。例如，Laravel 提供了一个包含多种驱动程序的队列实现，以及一个由 Symfony Mailer 驱动的邮件发送实现。

所有的 Laravel 契约都位于 它们自己的 GitHub 仓库 中。这为所有可用的契约提供了一个快速参考点，同时作为一个独立、解耦的包，可以在构建与 Laravel 服务交互的扩展包时使用。

契约与外观 (Facades)

Laravel 的 外观（Facades） 和辅助函数提供了一种简单的方法来使用 Laravel 服务，而无需在服务容器中对契约进行类型提示（type-hint）和解析。在大多数情况下，每个外观都有一个对应的契约。

与不需要在类构造函数中引入的外观不同，契约允许你为类定义显式依赖。一些开发者喜欢以这种方式显式定义依赖，因此更倾向于使用契约；而另一些开发者则喜欢外观带来的便利。通常情况下，大多数应用程序在开发过程中使用外观不会有任何问题。

何时使用契约

使用契约还是外观的决定取决于个人偏好以及你的开发团队的口味。契约和外观都可以用来创建健壮、经过充分测试的 Laravel 应用程序。契约和外观并不是互斥的。你应用程序的某些部分可以使用外观，而另一些部分则依赖于契约。只要你保持类职责的单一，你会发现使用契约和外观之间的实际差异非常小。

通常情况下，大多数应用程序在开发过程中使用外观不会有任何问题。如果你正在构建一个集成了多个 PHP 框架的扩展包，你可能希望使用 illuminate/contracts 包来定义你与 Laravel 服务的集成，而无需在扩展包的 composer.json 文件中引入 Laravel 的具体实现。

如何使用契约

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

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

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

 1<?php
 2 
 3namespace App\Listeners;
 4 
 5use App\Events\OrderWasPlaced;
 6use App\Models\User;
 7use Illuminate\Contracts\Redis\Factory;
 8 
 9class CacheOrderInformation
10{
11    /**
12     * Create the event listener.
13     */
14    public function __construct(
15        protected Factory $redis,
16    ) {}
17 
18    /**
19     * Handle the event.
20     */
21    public function handle(OrderWasPlaced $event): void
22    {
23        // ...
24    }
25}

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

契约参考

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