Contracts · Laravel 5.6 中文文檔

* * * * * [TOC] ## 簡介 Laravel 的契約是一組定義框架提供的核心服務的接口。例如，`Illuminate\Contracts\Queue\Queue`?契約定義了隊列任務所需的方法，而?`Illuminate\Contracts\Mail\Mailer`?契約定義了發送電子郵件所需的方法。框架對每個契約都提供了相應的實現。例如，Laravel 提供了具有各種驅動的隊列實現和由?[SwiftMailer](https://swiftmailer.symfony.com/)?提供支持的郵件驅動實現。所有的 Laravel 契約都有?[他們自己的 GitHub 庫](https://github.com/illuminate/contracts)。這為所有可用的契約提供了一個快速參考指南，同時也可單獨作為低耦合的擴展包給其他包開發者使用。 ### 契約 VS Facades Laravel?[Facades](http://www.hmoore.net/tonyyu/laravel_5_6/786058)?和輔助函數提供了一種使用 Laravel 服務的簡單方法，即不需要通過類型提示并從服務容器中解析契約。在大多數情況下，每個 Facades 都有一個等效的契約。不像 Facades，不需要你在類的構造函數中類型提示，契約則需要你在類中明顯地定義依賴項。一些開發者傾向于以契約這種方式明確地定義它們的依賴項，而其它開發者則更喜歡 Facades 帶來的便捷。 > {tip} 對于大多數應用程序來說不管是使用 facades 還是契約都可以。但是，如果你正在構建一個擴展包，為了方便測試，你應該強烈考慮契約。 ## 何時使用契約綜上所述，使用契約或是 Facades 很大程度上歸結于個人或者開發團隊的喜好。不管是契約還是 Facades 都可以創建出健壯的、易測試的 Laravel 應用程序。如果你長期關注類的單一職責，你會注意到使用契約還是 Facades 其實沒多少實際意義上的區別。然而，你可能還是會有幾個關于契約的問題。例如，為什么要使用接口？不使用接口會比較復雜嗎？下面讓我們談下使用接口的原因：低耦合和簡單性。 ### 低耦合首先，讓我們來看一些高耦合緩存實現的代碼。如下: ~~~ <?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 ），那又得再次修改這個 Repository 類。而 Repository 類不應該了解太多關于誰提供了這些數據或是如何提供的等等。 **比起上面的做法，我們可以使用一個簡單的、與擴展包無關的接口來改進我們的代碼：** ~~~ <?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 中的許多類型的類都是通過?[服務容器](http://www.hmoore.net/tonyyu/laravel_5_6/786056)?解析出來的，包括控制器、事件監聽器、中間件、任務隊列，甚至路由閉包。所以說，要獲得一個契約的實現，你只需要被解析的類的構造函數中添加「類型提示」即可。例如，看看這個事件監聽器： ~~~ <?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) { // } } ~~~ 當事件監聽器被解析時，服務容器會讀取類的構造函數上的類型提示，并注入對應的值。想了解更多關于服務容器的注冊，請查看?[這個文檔](http://www.hmoore.net/tonyyu/laravel_5_6/786056)。 ## 契約參考下表提供了所有 Laravel 契約及其對應的 Facades： | 契約 | 參考 Facade | | --- | --- | | [Illuminate\Contracts\Auth\Access\Authorizable](https://github.com/illuminate/contracts/blob/laravel/5.6/Auth/Access/Authorizable.php) | ?? | | [Illuminate\Contracts\Auth\Access\Gate](https://github.com/illuminate/contracts/blob/laravel/5.6/Auth/Access/Gate.php) | `Gate` | | [Illuminate\Contracts\Auth\Authenticatable](https://github.com/illuminate/contracts/blob/laravel/5.6/Auth/Authenticatable.php) | ?? | | [Illuminate\Contracts\Auth\CanResetPassword](https://github.com/illuminate/contracts/blob/laravel/5.6/Auth/CanResetPassword.php) | ? | | [Illuminate\Contracts\Auth\Factory](https://github.com/illuminate/contracts/blob/laravel/5.6/Auth/Factory.php) | `Auth` | | [Illuminate\Contracts\Auth\Guard](https://github.com/illuminate/contracts/blob/laravel/5.6/Auth/Guard.php) | `Auth::guard()` | | [Illuminate\Contracts\Auth\PasswordBroker](https://github.com/illuminate/contracts/blob/laravel/5.6/Auth/PasswordBroker.php) | `Password::broker()` | | [Illuminate\Contracts\Auth\PasswordBrokerFactory](https://github.com/illuminate/contracts/blob/laravel/5.6/Auth/PasswordBrokerFactory.php) | `Password` | | [Illuminate\Contracts\Auth\StatefulGuard](https://github.com/illuminate/contracts/blob/laravel/5.6/Auth/StatefulGuard.php) | ? | | [Illuminate\Contracts\Auth\SupportsBasicAuth](https://github.com/illuminate/contracts/blob/laravel/5.6/Auth/SupportsBasicAuth.php) | ? | | [Illuminate\Contracts\Auth\UserProvider](https://github.com/illuminate/contracts/blob/laravel/5.6/Auth/UserProvider.php) | ? | | [Illuminate\Contracts\Bus\Dispatcher](https://github.com/illuminate/contracts/blob/laravel/5.6/Bus/Dispatcher.php) | `Bus` | | [Illuminate\Contracts\Bus\QueueingDispatcher](https://github.com/illuminate/contracts/blob/laravel/5.6/Bus/QueueingDispatcher.php) | `Bus::dispatchToQueue()` | | [Illuminate\Contracts\Broadcasting\Factory](https://github.com/illuminate/contracts/blob/laravel/5.6/Broadcasting/Factory.php) | `Broadcast` | | [Illuminate\Contracts\Broadcasting\Broadcaster](https://github.com/illuminate/contracts/blob/laravel/5.6/Broadcasting/Broadcaster.php) | `Broadcast::connection()` | | [Illuminate\Contracts\Broadcasting\ShouldBroadcast](https://github.com/illuminate/contracts/blob/laravel/5.6/Broadcasting/ShouldBroadcast.php) | ? | | [Illuminate\Contracts\Broadcasting\ShouldBroadcastNow](https://github.com/illuminate/contracts/blob/laravel/5.6/Broadcasting/ShouldBroadcastNow.php) | ? | | [Illuminate\Contracts\Cache\Factory](https://github.com/illuminate/contracts/blob/laravel/5.6/Cache/Factory.php) | `Cache` | | [Illuminate\Contracts\Cache\Lock](https://github.com/illuminate/contracts/blob/laravel/5.6/Cache/Lock.php) | ? | | [Illuminate\Contracts\Cache\LockProvider](https://github.com/illuminate/contracts/blob/laravel/5.6/Cache/LockProvider.php) | ? | | [Illuminate\Contracts\Cache\Repository](https://github.com/illuminate/contracts/blob/laravel/5.6/Cache/Repository.php) | `Cache::driver()` | | [Illuminate\Contracts\Cache\Store](https://github.com/illuminate/contracts/blob/laravel/5.6/Cache/Store.php) | ? | | [Illuminate\Contracts\Config\Repository](https://github.com/illuminate/contracts/blob/laravel/5.6/Config/Repository.php) | `Config` | | [Illuminate\Contracts\Console\Application](https://github.com/illuminate/contracts/blob/laravel/5.6/Console/Application.php) | ? | | [Illuminate\Contracts\Console\Kernel](https://github.com/illuminate/contracts/blob/laravel/5.6/Console/Kernel.php) | `Artisan` | | [Illuminate\Contracts\Container\Container](https://github.com/illuminate/contracts/blob/laravel/5.6/Container/Container.php) | `App` | | [Illuminate\Contracts\Cookie\Factory](https://github.com/illuminate/contracts/blob/laravel/5.6/Cookie/Factory.php) | `Cookie` | | [Illuminate\Contracts\Cookie\QueueingFactory](https://github.com/illuminate/contracts/blob/laravel/5.6/Cookie/QueueingFactory.php) | `Cookie::queue()` | | [Illuminate\Contracts\Database\ModelIdentifier](https://github.com/illuminate/contracts/blob/laravel/5.6/Database/ModelIdentifier.php) | ? | | [Illuminate\Contracts\Debug\ExceptionHandler](https://github.com/illuminate/contracts/blob/laravel/5.6/Debug/ExceptionHandler.php) | ? | | [Illuminate\Contracts\Encryption\Encrypter](https://github.com/illuminate/contracts/blob/laravel/5.6/Encryption/Encrypter.php) | `Crypt` | | [Illuminate\Contracts\Events\Dispatcher](https://github.com/illuminate/contracts/blob/laravel/5.6/Events/Dispatcher.php) | `Event` | | [Illuminate\Contracts\Filesystem\Cloud](https://github.com/illuminate/contracts/blob/laravel/5.6/Filesystem/Cloud.php) | `Storage::cloud()` | | [Illuminate\Contracts\Filesystem\Factory](https://github.com/illuminate/contracts/blob/laravel/5.6/Filesystem/Factory.php) | `Storage` | | [Illuminate\Contracts\Filesystem\Filesystem](https://github.com/illuminate/contracts/blob/laravel/5.6/Filesystem/Filesystem.php) | `Storage::disk()` | | [Illuminate\Contracts\Foundation\Application](https://github.com/illuminate/contracts/blob/laravel/5.6/Foundation/Application.php) | `App` | | [Illuminate\Contracts\Hashing\Hasher](https://github.com/illuminate/contracts/blob/laravel/5.6/Hashing/Hasher.php) | `Hash` | | [Illuminate\Contracts\Http\Kernel](https://github.com/illuminate/contracts/blob/laravel/5.6/Http/Kernel.php) | ? | | [Illuminate\Contracts\Logging\Log](https://github.com/illuminate/contracts/blob/laravel/5.6/Logging/Log.php) | `Log` | | [Illuminate\Contracts\Mail\MailQueue](https://github.com/illuminate/contracts/blob/laravel/5.6/Mail/MailQueue.php) | `Mail::queue()` | | [Illuminate\Contracts\Mail\Mailable](https://github.com/illuminate/contracts/blob/laravel/5.6/Mail/Mailable.php) | ? | | [Illuminate\Contracts\Mail\Mailer](https://github.com/illuminate/contracts/blob/laravel/5.6/Mail/Mailer.php) | `Mail` | | [Illuminate\Contracts\Notifications\Dispatcher](https://github.com/illuminate/contracts/blob/laravel/5.6/Notifications/Dispatcher.php) | `Notification` | | [Illuminate\Contracts\Notifications\Factory](https://github.com/illuminate/contracts/blob/laravel/5.6/Notifications/Factory.php) | `Notification` | | [Illuminate\Contracts\Pagination\LengthAwarePaginator](https://github.com/illuminate/contracts/blob/laravel/5.6/Pagination/LengthAwarePaginator.php) | ? | | [Illuminate\Contracts\Pagination\Paginator](https://github.com/illuminate/contracts/blob/laravel/5.6/Pagination/Paginator.php) | ? | | [Illuminate\Contracts\Pipeline\Hub](https://github.com/illuminate/contracts/blob/laravel/5.6/Pipeline/Hub.php) | ? | | [Illuminate\Contracts\Pipeline\Pipeline](https://github.com/illuminate/contracts/blob/laravel/5.6/Pipeline/Pipeline.php) | ? | | [Illuminate\Contracts\Queue\EntityResolver](https://github.com/illuminate/contracts/blob/laravel/5.6/Queue/EntityResolver.php) | ? | | [Illuminate\Contracts\Queue\Factory](https://github.com/illuminate/contracts/blob/laravel/5.6/Queue/Factory.php) | `Queue` | | [Illuminate\Contracts\Queue\Job](https://github.com/illuminate/contracts/blob/laravel/5.6/Queue/Job.php) | ? | | [Illuminate\Contracts\Queue\Monitor](https://github.com/illuminate/contracts/blob/laravel/5.6/Queue/Monitor.php) | `Queue` | | [Illuminate\Contracts\Queue\Queue](https://github.com/illuminate/contracts/blob/laravel/5.6/Queue/Queue.php) | `Queue::connection()` | | [Illuminate\Contracts\Queue\QueueableCollection](https://github.com/illuminate/contracts/blob/laravel/5.6/Queue/QueueableCollection.php) | ? | | [Illuminate\Contracts\Queue\QueueableEntity](https://github.com/illuminate/contracts/blob/laravel/5.6/Queue/QueueableEntity.php) | ? | | [Illuminate\Contracts\Queue\ShouldQueue](https://github.com/illuminate/contracts/blob/laravel/5.6/Queue/ShouldQueue.php) | ? | | [Illuminate\Contracts\Redis\Factory](https://github.com/illuminate/contracts/blob/laravel/5.6/Redis/Factory.php) | `Redis` | | [Illuminate\Contracts\Routing\BindingRegistrar](https://github.com/illuminate/contracts/blob/laravel/5.6/Routing/BindingRegistrar.php) | `Route` | | [Illuminate\Contracts\Routing\Registrar](https://github.com/illuminate/contracts/blob/laravel/5.6/Routing/Registrar.php) | `Route` | | [Illuminate\Contracts\Routing\ResponseFactory](https://github.com/illuminate/contracts/blob/laravel/5.6/Routing/ResponseFactory.php) | `Response` | | [Illuminate\Contracts\Routing\UrlGenerator](https://github.com/illuminate/contracts/blob/laravel/5.6/Routing/UrlGenerator.php) | `URL` | | [Illuminate\Contracts\Routing\UrlRoutable](https://github.com/illuminate/contracts/blob/laravel/5.6/Routing/UrlRoutable.php) | ? | | [Illuminate\Contracts\Session\Session](https://github.com/illuminate/contracts/blob/laravel/5.6/Session/Session.php) | `Session::driver()` | | [Illuminate\Contracts\Support\Arrayable](https://github.com/illuminate/contracts/blob/laravel/5.6/Support/Arrayable.php) | ? | | [Illuminate\Contracts\Support\Htmlable](https://github.com/illuminate/contracts/blob/laravel/5.6/Support/Htmlable.php) | ? | | [Illuminate\Contracts\Support\Jsonable](https://github.com/illuminate/contracts/blob/laravel/5.6/Support/Jsonable.php) | ? | | [Illuminate\Contracts\Support\MessageBag](https://github.com/illuminate/contracts/blob/laravel/5.6/Support/MessageBag.php) | ? | | [Illuminate\Contracts\Support\MessageProvider](https://github.com/illuminate/contracts/blob/laravel/5.6/Support/MessageProvider.php) | ? | | [Illuminate\Contracts\Support\Renderable](https://github.com/illuminate/contracts/blob/laravel/5.6/Support/Renderable.php) | ? | | [Illuminate\Contracts\Support\Responsable](https://github.com/illuminate/contracts/blob/laravel/5.6/Support/Responsable.php) | ? | | [Illuminate\Contracts\Translation\Loader](https://github.com/illuminate/contracts/blob/laravel/5.6/Translation/Loader.php) | ? | | [Illuminate\Contracts\Translation\Translator](https://github.com/illuminate/contracts/blob/laravel/5.6/Translation/Translator.php) | `Lang` | | [Illuminate\Contracts\Validation\Factory](https://github.com/illuminate/contracts/blob/laravel/5.6/Validation/Factory.php) | `Validator` | | [Illuminate\Contracts\Validation\ImplicitRule](https://github.com/illuminate/contracts/blob/laravel/5.6/Validation/ImplicitRule.php) | ? | | [Illuminate\Contracts\Validation\Rule](https://github.com/illuminate/contracts/blob/laravel/5.6/Validation/Rule.php) | ? | | [Illuminate\Contracts\Validation\ValidatesWhenResolved](https://github.com/illuminate/contracts/blob/laravel/5.6/Validation/ValidatesWhenResolved.php) | ? | | [Illuminate\Contracts\Validation\Validator](https://github.com/illuminate/contracts/blob/laravel/5.6/Validation/Validator.php) | `Validator::make()` | | [Illuminate\Contracts\View\Engine](https://github.com/illuminate/contracts/blob/laravel/5.6/View/Engine.php) | ? | | [Illuminate\Contracts\View\Factory](https://github.com/illuminate/contracts/blob/laravel/5.6/View/Factory.php) | `View` | | [Illuminate\Contracts\View\View](https://github.com/illuminate/contracts/blob/laravel/5.6/View/View.php) | `View::make()` |