Contracts

介绍

Laravel 的契约是一组由框架提供，定义了核心服务的 interface 集合。比如， Illuminate\Contracts\Queue\Queue 契约定义了队列任务所需方法，而 Illuminate\Contracts\Mail\Mailer 契约定义了发送邮件所需方法。

每个契约都拥有相应的框架提供的实现。比如，Laravel 提供了多种驱动的队列实现，并且使用 SwiftMailer 实现了邮件契约。

所有 Laravel 契约都在 它们各自的 GitHub 仓库。这为所有可用的契约以及扩展包开发者们可能用到的单个、解耦的包，提供了一个快速参考入口。

契约 Vs. Facades

Laravel 的 Facades 和辅助函数提供了一种简便方式来使用 Laravel 服务而无需用到类型提示，也可在服务容器外部解析契约。多数情况下，每个 Facade 都有一个等效的契约。

和 Facades （不须要在你类中的构造函数去引用依赖）不同的是，契约允许你给自己的类定义明确的依赖。一些开发者更喜欢依赖被明确地定义出来，所以更倾向于使用契约，而其他开发者则享受于 Facades 带来的方便。

{tip} 在大多数应用中，无论你更喜欢 Facades 还是契约，都是没问题的。然而如果你在搭建扩展包，那你应该强烈考虑使用契约，因为他们更便于在包的上下文中做测试。

何时使用契约

综上所述，使用契约还是 Facades 很大程度上取决于你个人或者团队的喜好。契约和 Facades 均可以用来构建健壮的、充分测试过的 Laravel 应用。只要你保持类的职责单一，你会发现使用契约和 Facades 的实际差别是非常小的。

然而，你以也许仍有许多关于契约的问题。比方说，为啥都用 interface ？用 interface 不是更复杂吗？让我们在接下来的内容（「低耦合」与「简明性」）中，提炼出原因。

低耦合

首先，让我们来看一些缓存实现的高耦合代码。假设有下面代码：

<?php
namespace App\Orders;
class Repository
{
    /**
     * 缓存实例.
     */
    protected $cache;
    /**
     * 创建一个新的仓库实例.
     *
     * @param  \SomePackage\Cache\Memcached  $cache
     * @return void
     */
    public function __construct(\SomePackage\Cache\Memcached $cache)
    {
        $this->cache = $cache;
    }
    /**
     * 根据 ID 获取订单.
     *
     * @param  int  $id
     * @return Order
     */
    public function find($id)
    {
        if ($this->cache->has($id))    {
            //
        }
    }
}

在这个类中，代码与给定的缓存实现形成高度耦合。它的高度耦合是因为我们依赖了一个扩展包中具体的缓存类。如果该扩展包的 API 变了，那么我们的代码也将必须做出修改。

同理，如果我们想要将底层的缓存技术 （ Memcached ） 替换成另一种缓存技术 （ Redis ），我们得再次修改我们的代码库。我们的代码库并不需要知道是谁提供的数据或者数据是怎么提供的。

我们可以通过依赖一个简单的与扩展包无关的 interface 来改进我们的代码，来替代之前的实现方式：

<?php
namespace App\Orders;
use Illuminate\Contracts\Cache\Repository as Cache;
class Repository
{
    /**
     * 缓存实例.
     */
    protected $cache;
    /**
     * 创建一个新的仓库实例.
     *
     * @param  Cache  $cache
     * @return void
     */
    public function __construct(Cache $cache)
    {
        $this->cache = $cache;
    }
}

现在的代码不与任何特定的扩展包耦合了，甚至与 Laravel 都是无关的。由于契约扩展包不包含任何实现和依赖，你可以轻松地为给定的契约编写替代实现的代码，从而可以在不修改任何缓存代码的情况下替换缓存的实现。

简单

当 Laravel 的所有服务都在简单的接口中整齐定义时，很容易通过给定的服务确定提供的功能。契约充当框架功能的简洁性文档。

此外，当你依赖简单的接口时，你的代码更容易理解和维护。你可以参考一个简单，干净的接口，而不是在大型复杂的的类中跟踪哪些方法是可用的。

如何使用契约

因此，你如何去实现一个契约呢？它实际上很简单。

Laravel 中的许多类型的类通过 服务容器 来解析，包括控制器，事件侦听，中间件，队列作业，甚至路由闭包等。因此，要获取一个合同的实现，你只需在解析的类的构造方法中键入『类型提示』的接口。

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

<?php
namespace App\Listeners;
use App\User;
use App\Events\OrderWasPlaced;
use Illuminate\Contracts\Redis\Factory;
class CacheOrderInformation
{
    /**
     * Redis 工厂实现。
     */
    protected $redis;
    /**
     * 创建一个新的事件处理器实例。
     *
     * @param  Factory  $redis
     * @return void
     */
    public function __construct(Factory $redis)
    {
        $this->redis = $redis;
    }
    /**
     * 处理事件。
     *
     * @param  OrderWasPlaced  $event
     * @return void
     */
    public function handle(OrderWasPlaced $event)
    {
        //
    }
}

当事件侦听器被解析时，服务容器将读取类的构造方法上的类型提示，并注入合适的值。要了解更多有关在服务容器中注册的内容，查看 服务容器文档。

合约参考

此表提供了所有 Laravel 契约及其等效 facades 的一个快速参考：

1.