Contracts · Laravel 5.4 完全開發手冊

* * * * * [TOC] ## 簡介 Laravel 的契約(Contracts ) 是一系列框架用來定義核心服務的接口。例如，`Illuminate\Contracts\Queue\Queue`?契約中定義了隊列任務所需的方法，而?`Illuminate\Contracts\Mail\Mailer`?契約中定義了發送電子郵件所需的方法。框架對每個契約都提供了相應的實現。例如，Laravel 為隊列提供了各種驅動的實現，為郵件提供了由?[SwiftMailer](http://swiftmailer.org/)?驅動的實現。所有 Laravel 契約都有相應的?[GitHub 庫](https://github.com/illuminate/contracts)?，這給所有可用的契約提供了一個快速參考指南，同時也可單獨作為低耦合的擴展包給其他包開發者去使用。 ### 契約 (contracts) VS 門面 (facades) [門面 (facades)](Facades.md)?和一些輔助函數提供了一種使用 Laravel 服務的簡單方法，即不再需要通過類型約束和在服務容器之外解析契約。在大多數情況下，每個門面都有一個等效契約。不像門面，門面不需要你在類構造函數中約束什么，契約則是需要你明顯地定義依賴關系。一些開發人員喜歡契約這種方式明顯地去定義它們的依賴關系，而另一些開發人員則更喜歡門面帶來的便捷。 > {tip} 對于大多數應用程序來說不管是使用門面還是契約只要你喜歡都行。但是，如果你正在構建一個擴展包，為了方便測試建議考慮使用契約比較好。 ## 何時使用 contracts 綜上所述，使用契約或者門面很大程度上歸結于個人或者開發團隊的喜好。不管是契約還是門面都可以創建出強大的、容易測試的 Laravel 應用程序。如果你長期關注類的單一職責，你會注意到使用契約和門面其實沒多少實際意義上的區別。然而，你可能還是會有幾個關于契約的問題。像是，為什么要使用接口？使用接口會不會變得更加復雜？下面讓我們簡單闡述一下使用接口的原因：低耦合和簡單性。 ### 低耦合首先，讓我們回顧一些與緩存實現的高耦合代碼。如下： ~~~ <?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 服務都使用簡潔的接口定義，就能夠很容易決定一個服務需要提供的功能。?**可以將契約視為說明框架特色的簡潔文檔。** 除此之外，當依賴的接口足夠簡潔時，代碼的可讀性和可維護性會大大提高。比起搜索一個大型復雜的類里有哪些可用的方法，不如檢索一個簡單、干凈的接口來參考更妥當。 ## 如何使用 contracts 那么，如何獲取一個契約的實現呢？這其實很簡單。 Laravel 中的許多類型的類都是通過?[服務容器](服務容器.md)?解析出來的。包括控制器、事件監聽器、中間件、任務隊列，甚至路由的閉包。所以說，要獲得一個契約的實現，你只需要解析在類的構造函數中相應的類型約束即可。例如，看看這個事件監聽器： ~~~ <?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) { // } } ~~~ 當事件監聽器被解析時，服務容器會從構造函數里讀取到類型約束，并注入對應的值。想了解關于容器的注冊綁定，可以查看?[服務容器](服務容器.md)。 ## Contract 參考下面的表格提供了 Laravel 契約及其對應的門面的參考: | Contract | References Facade | | --- | --- | | [Illuminate\Contracts\Auth\Factory](https://github.com/illuminate/contracts/blob/laravel/5.4/Auth/Factory.php) | Auth | | [Illuminate\Contracts\Auth\PasswordBroker](https://github.com/illuminate/contracts/blob/laravel/5.4/Auth/PasswordBroker.php) | Password | | [Illuminate\Contracts\Bus\Dispatcher](https://github.com/illuminate/contracts/blob/laravel/5.4/Bus/Dispatcher.php) | Bus | | [Illuminate\Contracts\Broadcasting\Broadcaster](https://github.com/illuminate/contracts/blob/laravel/5.4/Broadcasting/Broadcaster.php) | ? | | [Illuminate\Contracts\Cache\Repository](https://github.com/illuminate/contracts/blob/laravel/5.4/Cache/Repository.php) | Cache | | [Illuminate\Contracts\Cache\Factory](https://github.com/illuminate/contracts/blob/laravel/5.4/Cache/Factory.php) | Cache::driver() | | [Illuminate\Contracts\Config\Repository](https://github.com/illuminate/contracts/blob/laravel/5.4/Config/Repository.php) | Config | | [Illuminate\Contracts\Container\Container](https://github.com/illuminate/contracts/blob/laravel/5.4/Container/Container.php) | App | | [Illuminate\Contracts\Cookie\Factory](https://github.com/illuminate/contracts/blob/laravel/5.4/Cookie/Factory.php) | Cookie | | [Illuminate\Contracts\Cookie\QueueingFactory](https://github.com/illuminate/contracts/blob/laravel/5.4/Cookie/QueueingFactory.php) | Cookie::queue() | | [Illuminate\Contracts\Encryption\Encrypter](https://github.com/illuminate/contracts/blob/laravel/5.4/Encryption/Encrypter.php) | Crypt | | [Illuminate\Contracts\Events\Dispatcher](https://github.com/illuminate/contracts/blob/laravel/5.4/Events/Dispatcher.php) | Event | | [Illuminate\Contracts\Filesystem\Cloud](https://github.com/illuminate/contracts/blob/laravel/5.4/Filesystem/Cloud.php) | ? | | [Illuminate\Contracts\Filesystem\Factory](https://github.com/illuminate/contracts/blob/laravel/5.4/Filesystem/Factory.php) | File | | [Illuminate\Contracts\Filesystem\Filesystem](https://github.com/illuminate/contracts/blob/laravel/5.4/Filesystem/Filesystem.php) | File | | [Illuminate\Contracts\Foundation\Application](https://github.com/illuminate/contracts/blob/laravel/5.4/Foundation/Application.php) | App | | [Illuminate\Contracts\Hashing\Hasher](https://github.com/illuminate/contracts/blob/laravel/5.4/Hashing/Hasher.php) | Hash | | [Illuminate\Contracts\Logging\Log](https://github.com/illuminate/contracts/blob/laravel/5.4/Logging/Log.php) | Log | | [Illuminate\Contracts\Mail\MailQueue](https://github.com/illuminate/contracts/blob/laravel/5.4/Mail/MailQueue.php) | Mail::queue() | | [Illuminate\Contracts\Mail\Mailer](https://github.com/illuminate/contracts/blob/laravel/5.4/Mail/Mailer.php) | Mail | | [Illuminate\Contracts\Queue\Factory](https://github.com/illuminate/contracts/blob/laravel/5.4/Queue/Factory.php) | Queue::driver() | | [Illuminate\Contracts\Queue\Queue](https://github.com/illuminate/contracts/blob/laravel/5.4/Queue/Queue.php) | Queue | | [Illuminate\Contracts\Redis\Database](https://github.com/illuminate/contracts/blob/laravel/5.4/Redis/Database.php) | Redis | | [Illuminate\Contracts\Routing\Registrar](https://github.com/illuminate/contracts/blob/laravel/5.4/Routing/Registrar.php) | Route | | [Illuminate\Contracts\Routing\ResponseFactory](https://github.com/illuminate/contracts/blob/laravel/5.4/Routing/ResponseFactory.php) | Response | | [Illuminate\Contracts\Routing\UrlGenerator](https://github.com/illuminate/contracts/blob/laravel/5.4/Routing/UrlGenerator.php) | URL | | [Illuminate\Contracts\Support\Arrayable](https://github.com/illuminate/contracts/blob/laravel/5.4/Support/Arrayable.php) | ? | | [Illuminate\Contracts\Support\Jsonable](https://github.com/illuminate/contracts/blob/laravel/5.4/Support/Jsonable.php) | ? | | [Illuminate\Contracts\Support\Renderable](https://github.com/illuminate/contracts/blob/laravel/5.4/Support/Renderable.php) | ? | | [Illuminate\Contracts\Validation\Factory](https://github.com/illuminate/contracts/blob/laravel/5.4/Validation/Factory.php) | Validator::make() | | [Illuminate\Contracts\Validation\Validator](https://github.com/illuminate/contracts/blob/laravel/5.4/Validation/Validator.php) | ? | | [Illuminate\Contracts\View\Factory](https://github.com/illuminate/contracts/blob/laravel/5.4/View/Factory.php) | View::make() | | [Illuminate\Contracts\View\View](https://github.com/illuminate/contracts/blob/laravel/5.4/View/View.php) ||