# Contracts
## 简介
Laravel 的契约是指框架提供的一系列定义核心服务的接口。例如`Illuminate\Contracts\Queue\Queue`契约定义了队列任务需要实现的方法，而`Illuminate\Contracts\Mail\Mailer`契约定义了发送邮件所需要实现的方法。
每一个契约都有框架提供相应的实现。例如 Laravel 为队列提供了多个驱动的实现，邮件则由[SwiftMailer](https://swiftmailer.symfony.com/)驱动实现。
所有的契约都有其[对应的 GitHub 仓库](https://github.com/illuminate/contracts)。这为所有可用的契约提供了一个快速入门的指南，同时也可以单独作为低耦合的扩展包被开发者使用。
### 契约 Vs. Facades
Laravel 的[facades](https://laravel-china.org/docs/laravel/5.7/facades)和辅助函数都提供了一种使用 Laravel 服务的简单方法，既不需类型提示，也不需要从服务容器中解析解析契约。大多情况下，每一个 Facades 都有一个等效的契约。
在 Facades 中，你不需要在构造函数中做类型提示，但是契约需要你在类中明确的定义依赖。一些开发者倾向于使用契约这种明确定义依赖的方式，而其他开发者则更喜欢 Facades 带来的便捷。
> {tip} 对于大多数的应用程序而言，不管是使用 Facades 还是契约，都可以。但是如果你在构建一个扩展包，为了方便测试，强烈建议你使用契约
## 何时使用契约
综上所述，使用契约还是 Facades 很大程度上取决于你个人或者团队的喜好。两者都可以使创建强大的、测试友好的 Laravel 应用程序。只要你保持类的职责单一，你会发现使用契约还是 Facades，其实并没有什么实质性的区别。
但是，你可能还是会对契约有些困惑。比如，为什么要全部使用接口？使用接口会不会更复杂？下面让我们从两个方面来聊一聊为什么使用接口：低耦合和简单性。
### 低耦合
首先，让我们来看一些缓存实现的高耦合代码：
~~~php
<?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)，我们得再次修改我们的代码库。但其实是我们的代码库并不需要知道谁提供的数据或者数据是怎么提供的。
**我们可以基于一种简单的、与扩展包无关的接口来优化我们的代码，从而替代上面的那种实现方式：**
~~~php
<?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 中有很多类都是通过[服务容器](https://laravel-china.org/docs/laravel/5.7/container)，进行解析，包括控制器，以及事件监听器、中间件、队列任务，甚至路由闭包。所以，实现一个契约，你只需要在被解析的类的构造函数中添加契约接口即可。
例如，下面这个事件监听器：
~~~php
<?php
namespace App\Listeners;
use App\User;
use App\Events\OrderWasPlaced;
use Illuminate\Contracts\Redis\Database;
class CacheOrderInformation
{
/**
* Redis 数据库实现
*/
protected $redis;
/**
* 创建事件处理器实例
*
* @param Database $redis
* @return void
*/
public function __construct(Database $redis)
{
$this->redis = $redis;
}
/**
* 处理事件
*
* @param OrderWasPlaced $event
* @return void
*/
public function handle(OrderWasPlaced $event)
{
//
}
}
~~~
当事件监听器被解析的时候，服务容器会读取构造函数中的类型提示，并注入相应的值。想要学习更多关于服务容器的注册细节，请参考[其文档](https://laravel-china.org/docs/laravel/5.7/container).
## 契约参考
下表提供了所有 Laravel 契约以及其对应的 Facades ：
| 契约 | 对应的 Facade |
| --- | --- |
| [Illuminate\\Contracts\\Auth\\Access\\Authorizable](https://github.com/illuminate/contracts/blob/laravel/5.7/Auth/Access/Authorizable.php) | |
| [Illuminate\\Contracts\\Auth\\Access\\Gate](https://github.com/illuminate/contracts/blob/laravel/5.7/Auth/Access/Gate.php) | `Gate` |
| [Illuminate\\Contracts\\Auth\\Authenticatable](https://github.com/illuminate/contracts/blob/laravel/5.7/Auth/Authenticatable.php) | |
| [Illuminate\\Contracts\\Auth\\CanResetPassword](https://github.com/illuminate/contracts/blob/laravel/5.7/Auth/CanResetPassword.php) | |
| [Illuminate\\Contracts\\Auth\\Factory](https://github.com/illuminate/contracts/blob/laravel/5.7/Auth/Factory.php) | `Auth` |
| [Illuminate\\Contracts\\Auth\\Guard](https://github.com/illuminate/contracts/blob/laravel/5.7/Auth/Guard.php) | `Auth::guard()` |
| [Illuminate\\Contracts\\Auth\\PasswordBroker](https://github.com/illuminate/contracts/blob/laravel/5.7/Auth/PasswordBroker.php) | `Password::broker()` |
| [Illuminate\\Contracts\\Auth\\PasswordBrokerFactory](https://github.com/illuminate/contracts/blob/laravel/5.7/Auth/PasswordBrokerFactory.php) | `Password` |
| [Illuminate\\Contracts\\Auth\\StatefulGuard](https://github.com/illuminate/contracts/blob/laravel/5.7/Auth/StatefulGuard.php) | |
| [Illuminate\\Contracts\\Auth\\SupportsBasicAuth](https://github.com/illuminate/contracts/blob/laravel/5.7/Auth/SupportsBasicAuth.php) | |
| [Illuminate\\Contracts\\Auth\\UserProvider](https://github.com/illuminate/contracts/blob/laravel/5.7/Auth/UserProvider.php) | |
| [Illuminate\\Contracts\\Bus\\Dispatcher](https://github.com/illuminate/contracts/blob/laravel/5.7/Bus/Dispatcher.php) | `Bus` |
| [Illuminate\\Contracts\\Bus\\QueueingDispatcher](https://github.com/illuminate/contracts/blob/laravel/5.7/Bus/QueueingDispatcher.php) | `Bus::dispatchToQueue()` |
| [Illuminate\\Contracts\\Broadcasting\\Factory](https://github.com/illuminate/contracts/blob/laravel/5.7/Broadcasting/Factory.php) | `Broadcast` |
| [Illuminate\\Contracts\\Broadcasting\\Broadcaster](https://github.com/illuminate/contracts/blob/laravel/5.7/Broadcasting/Broadcaster.php) | `Broadcast::connection()` |
| [Illuminate\\Contracts\\Broadcasting\\ShouldBroadcast](https://github.com/illuminate/contracts/blob/laravel/5.7/Broadcasting/ShouldBroadcast.php) | |
| [Illuminate\\Contracts\\Broadcasting\\ShouldBroadcastNow](https://github.com/illuminate/contracts/blob/laravel/5.7/Broadcasting/ShouldBroadcastNow.php) | |
| [Illuminate\\Contracts\\Cache\\Factory](https://github.com/illuminate/contracts/blob/laravel/5.7/Cache/Factory.php) | `Cache` |
| [Illuminate\\Contracts\\Cache\\Lock](https://github.com/illuminate/contracts/blob/laravel/5.7/Cache/Lock.php) | |
| [Illuminate\\Contracts\\Cache\\LockProvider](https://github.com/illuminate/contracts/blob/laravel/5.7/Cache/LockProvider.php) | |
| [Illuminate\\Contracts\\Cache\\Repository](https://github.com/illuminate/contracts/blob/laravel/5.7/Cache/Repository.php) | `Cache::driver()` |
| [Illuminate\\Contracts\\Cache\\Store](https://github.com/illuminate/contracts/blob/laravel/5.7/Cache/Store.php) | |
| [Illuminate\\Contracts\\Config\\Repository](https://github.com/illuminate/contracts/blob/laravel/5.7/Config/Repository.php) | `Config` |
| [Illuminate\\Contracts\\Console\\Application](https://github.com/illuminate/contracts/blob/laravel/5.7/Console/Application.php) | |
| [Illuminate\\Contracts\\Console\\Kernel](https://github.com/illuminate/contracts/blob/laravel/5.7/Console/Kernel.php) | `Artisan` |
| [Illuminate\\Contracts\\Container\\Container](https://github.com/illuminate/contracts/blob/laravel/5.7/Container/Container.php) | `App` |
| [Illuminate\\Contracts\\Cookie\\Factory](https://github.com/illuminate/contracts/blob/laravel/5.7/Cookie/Factory.php) | `Cookie` |
| [Illuminate\\Contracts\\Cookie\\QueueingFactory](https://github.com/illuminate/contracts/blob/laravel/5.7/Cookie/QueueingFactory.php) | `Cookie::queue()` |
| [Illuminate\\Contracts\\Database\\ModelIdentifier](https://github.com/illuminate/contracts/blob/laravel/5.7/Database/ModelIdentifier.php) | |
| [Illuminate\\Contracts\\Debug\\ExceptionHandler](https://github.com/illuminate/contracts/blob/laravel/5.7/Debug/ExceptionHandler.php) | |
| [Illuminate\\Contracts\\Encryption\\Encrypter](https://github.com/illuminate/contracts/blob/laravel/5.7/Encryption/Encrypter.php) | `Crypt` |
| [Illuminate\\Contracts\\Events\\Dispatcher](https://github.com/illuminate/contracts/blob/laravel/5.7/Events/Dispatcher.php) | `Event` |
| [Illuminate\\Contracts\\Filesystem\\Cloud](https://github.com/illuminate/contracts/blob/laravel/5.7/Filesystem/Cloud.php) | `Storage::cloud()` |
| [Illuminate\\Contracts\\Filesystem\\Factory](https://github.com/illuminate/contracts/blob/laravel/5.7/Filesystem/Factory.php) | `Storage` |
| [Illuminate\\Contracts\\Filesystem\\Filesystem](https://github.com/illuminate/contracts/blob/laravel/5.7/Filesystem/Filesystem.php) | `Storage::disk()` |
| [Illuminate\\Contracts\\Foundation\\Application](https://github.com/illuminate/contracts/blob/laravel/5.7/Foundation/Application.php) | `App` |
| [Illuminate\\Contracts\\Hashing\\Hasher](https://github.com/illuminate/contracts/blob/laravel/5.7/Hashing/Hasher.php) | `Hash` |
| [Illuminate\\Contracts\\Http\\Kernel](https://github.com/illuminate/contracts/blob/laravel/5.7/Http/Kernel.php) | |
| [Illuminate\\Contracts\\Mail\\MailQueue](https://github.com/illuminate/contracts/blob/laravel/5.7/Mail/MailQueue.php) | `Mail::queue()` |
| [Illuminate\\Contracts\\Mail\\Mailable](https://github.com/illuminate/contracts/blob/laravel/5.7/Mail/Mailable.php) | |
| [Illuminate\\Contracts\\Mail\\Mailer](https://github.com/illuminate/contracts/blob/laravel/5.7/Mail/Mailer.php) | `Mail` |
| [Illuminate\\Contracts\\Notifications\\Dispatcher](https://github.com/illuminate/contracts/blob/laravel/5.7/Notifications/Dispatcher.php) | `Notification` |
| [Illuminate\\Contracts\\Notifications\\Factory](https://github.com/illuminate/contracts/blob/laravel/5.7/Notifications/Factory.php) | `Notification` |
| [Illuminate\\Contracts\\Pagination\\LengthAwarePaginator](https://github.com/illuminate/contracts/blob/laravel/5.7/Pagination/LengthAwarePaginator.php) | |
| [Illuminate\\Contracts\\Pagination\\Paginator](https://github.com/illuminate/contracts/blob/laravel/5.7/Pagination/Paginator.php) | |
| [Illuminate\\Contracts\\Pipeline\\Hub](https://github.com/illuminate/contracts/blob/laravel/5.7/Pipeline/Hub.php) | |
| [Illuminate\\Contracts\\Pipeline\\Pipeline](https://github.com/illuminate/contracts/blob/laravel/5.7/Pipeline/Pipeline.php) | |
| [Illuminate\\Contracts\\Queue\\EntityResolver](https://github.com/illuminate/contracts/blob/laravel/5.7/Queue/EntityResolver.php) | |
| [Illuminate\\Contracts\\Queue\\Factory](https://github.com/illuminate/contracts/blob/laravel/5.7/Queue/Factory.php) | `Queue` |
| [Illuminate\\Contracts\\Queue\\Job](https://github.com/illuminate/contracts/blob/laravel/5.7/Queue/Job.php) | |
| [Illuminate\\Contracts\\Queue\\Monitor](https://github.com/illuminate/contracts/blob/laravel/5.7/Queue/Monitor.php) | `Queue` |
| [Illuminate\\Contracts\\Queue\\Queue](https://github.com/illuminate/contracts/blob/laravel/5.7/Queue/Queue.php) | `Queue::connection()` |
| [Illuminate\\Contracts\\Queue\\QueueableCollection](https://github.com/illuminate/contracts/blob/laravel/5.7/Queue/QueueableCollection.php) | |
| [Illuminate\\Contracts\\Queue\\QueueableEntity](https://github.com/illuminate/contracts/blob/laravel/5.7/Queue/QueueableEntity.php) | |
| [Illuminate\\Contracts\\Queue\\ShouldQueue](https://github.com/illuminate/contracts/blob/laravel/5.7/Queue/ShouldQueue.php) | |
| [Illuminate\\Contracts\\Redis\\Factory](https://github.com/illuminate/contracts/blob/laravel/5.7/Redis/Factory.php) | `Redis` |
| [Illuminate\\Contracts\\Routing\\BindingRegistrar](https://github.com/illuminate/contracts/blob/laravel/5.7/Routing/BindingRegistrar.php) | `Route` |
| [Illuminate\\Contracts\\Routing\\Registrar](https://github.com/illuminate/contracts/blob/laravel/5.7/Routing/Registrar.php) | `Route` |
| [Illuminate\\Contracts\\Routing\\ResponseFactory](https://github.com/illuminate/contracts/blob/laravel/5.7/Routing/ResponseFactory.php) | `Response` |
| [Illuminate\\Contracts\\Routing\\UrlGenerator](https://github.com/illuminate/contracts/blob/laravel/5.7/Routing/UrlGenerator.php) | `URL` |
| [Illuminate\\Contracts\\Routing\\UrlRoutable](https://github.com/illuminate/contracts/blob/laravel/5.7/Routing/UrlRoutable.php) | |
| [Illuminate\\Contracts\\Session\\Session](https://github.com/illuminate/contracts/blob/laravel/5.7/Session/Session.php) | `Session::driver()` |
| [Illuminate\\Contracts\\Support\\Arrayable](https://github.com/illuminate/contracts/blob/laravel/5.7/Support/Arrayable.php) | |
| [Illuminate\\Contracts\\Support\\Htmlable](https://github.com/illuminate/contracts/blob/laravel/5.7/Support/Htmlable.php) | |
| [Illuminate\\Contracts\\Support\\Jsonable](https://github.com/illuminate/contracts/blob/laravel/5.7/Support/Jsonable.php) | |
| [Illuminate\\Contracts\\Support\\MessageBag](https://github.com/illuminate/contracts/blob/laravel/5.7/Support/MessageBag.php) | |
| [Illuminate\\Contracts\\Support\\MessageProvider](https://github.com/illuminate/contracts/blob/laravel/5.7/Support/MessageProvider.php) | |
| [Illuminate\\Contracts\\Support\\Renderable](https://github.com/illuminate/contracts/blob/laravel/5.7/Support/Renderable.php) | |
| [Illuminate\\Contracts\\Support\\Responsable](https://github.com/illuminate/contracts/blob/laravel/5.7/Support/Responsable.php) | |
| [Illuminate\\Contracts\\Translation\\Loader](https://github.com/illuminate/contracts/blob/laravel/5.7/Translation/Loader.php) | |
| [Illuminate\\Contracts\\Translation\\Translator](https://github.com/illuminate/contracts/blob/laravel/5.7/Translation/Translator.php) | `Lang` |
| [Illuminate\\Contracts\\Validation\\Factory](https://github.com/illuminate/contracts/blob/laravel/5.7/Validation/Factory.php) | `Validator` |
| [Illuminate\\Contracts\\Validation\\ImplicitRule](https://github.com/illuminate/contracts/blob/laravel/5.7/Validation/ImplicitRule.php) | |
| [Illuminate\\Contracts\\Validation\\Rule](https://github.com/illuminate/contracts/blob/laravel/5.7/Validation/Rule.php) | |
| [Illuminate\\Contracts\\Validation\\ValidatesWhenResolved](https://github.com/illuminate/contracts/blob/laravel/5.7/Validation/ValidatesWhenResolved.php) | |
| [Illuminate\\Contracts\\Validation\\Validator](https://github.com/illuminate/contracts/blob/laravel/5.7/Validation/Validator.php) | `Validator::make()` |
| [Illuminate\\Contracts\\View\\Engine](https://github.com/illuminate/contracts/blob/laravel/5.7/View/Engine.php) | |
| [Illuminate\\Contracts\\View\\Factory](https://github.com/illuminate/contracts/blob/laravel/5.7/View/Factory.php) | `View` |
| [Illuminate\\Contracts\\View\\View](https://github.com/illuminate/contracts/blob/laravel/5.7/View/View.php) |
