Contract

簡介
- Contracts vs. Facades
When to Use Contracts
How to Use Contracts
Contract 對照表

簡介

Laravel 的「Contract」是一組介面，這些介面定義了框架提供的核心服務。舉例來說，Illuminate\Contracts\Queue\Queue Contract 定義了佇列任務所需要的方法；而 Illuminate\Contracts\Mail\Mailer Contract 則定義了寄送 E-Mail 所需要的方法。

Each contract has a corresponding implementation provided by the framework. For example, Laravel provides a queue implementation with a variety of drivers, and a mailer implementation that is powered by Symfony Mailer.

所有的 Laravel Contract 都放在 Contract 自己的 GitHub 儲存庫內。使用該儲存庫，就可以快速參照到所有的 Contract，並且，在製作使用到 Laravel 服務的套件時，也可以作為一個單一、解藕的套件來使用。

Contracts vs. Facades

使用 Laravel 的 Facade 或輔助函式，就可以在不使用型別提示，或是從 Service Container 中解析 Contract 的情況下輕鬆使用各種 Laravel 服務。在大多數的情況下，各個 Facade 都有其對應的 Contract。

使用 Facade 時，不需要在類別的建構函式內要求這些類別。而與 Contract 與 Facade 不同的是，Contract 可以讓你為類別顯式 (Explicitly) 定義其相依性項目。某些開發人員偏好顯式定義相依性項目，因此他們也偏好使用 Contract；而其他開發人員則比較享受 Facade 帶來的方便性。一般來說，大多數專案在開發期間都可以使用 Facade 而不會遇到問題。

When to Use Contracts

要決定使用 Contract 還是 Facade，取決於個人以及開發團隊的偏好。不論使用 Contract 還是 Facade，在 Laravel 中都可獲得相同的強健性與可測試性。Contract 與 Facade 並非互斥。你可以在專案中某些部分使用 Facade、其他部分則使用 Contract。只要能保持類別的職責專一，使用 Contract 或 Facade 基本上就沒什麼差別。

通常來說，在開發期間，使用 Facade 對於大多數的專案來說都不會遇到什麼問題。不過若你在做的是會整合多個 PHP 框架的套件，則可以使用 illuminate/contracts 套件來定義與 Laravel 服務的整合。不需要在套件的 composer.json 檔中 require 整個 Laravel 的實際 (Concrete) 實作。

How to Use Contracts

那麼，如何取得某個 Contract 的實作呢？其實很簡單。

在 Laravel 中，許多類型的類別都會通過 Service Container 來解析。包含 Controller、Event Listener、Middleware、放入佇列的 Job、甚至是 Route 閉包。因此，若要取得一個 Contract 的實作，只需要在被解析類別的 Contractor 上對介面進行「型別提示 (Type-Hint)」即可。

舉例來說，來看看這個 Event Listner：

 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 a new event handler instance.
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} 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 a new event handler instance.
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}

當 Event Listner 被解析時，Service Container 會讀取該類別中 Constractor 的型別提示，並插入合適的值。要瞭解更多有關如何向 Service Container 註冊東西的資訊，請參考 Service Container 的說明文件。

Contract 對照表

下列表格是所有 Laravel Contract 與其對應 Facade 的對照表：

| Contract | 對應的 Facade | | --- | --- | | [Illuminate\Contracts\Auth\Access\Authorizable](https://github.com/illuminate/contracts/blob/11.x/Auth/Access/Authorizable.php) | | | [Illuminate\Contracts\Auth\Access\Gate](https://github.com/illuminate/contracts/blob/11.x/Auth/Access/Gate.php) | `Gate` | | [Illuminate\Contracts\Auth\Authenticatable](https://github.com/illuminate/contracts/blob/11.x/Auth/Authenticatable.php) | | | [Illuminate\Contracts\Auth\CanResetPassword](https://github.com/illuminate/contracts/blob/11.x/Auth/CanResetPassword.php) | | | [Illuminate\Contracts\Auth\Factory](https://github.com/illuminate/contracts/blob/11.x/Auth/Factory.php) | `Auth` | | [Illuminate\Contracts\Auth\Guard](https://github.com/illuminate/contracts/blob/11.x/Auth/Guard.php) | `Auth::guard()` | | [Illuminate\Contracts\Auth\PasswordBroker](https://github.com/illuminate/contracts/blob/11.x/Auth/PasswordBroker.php) | `Password::broker()` | | [Illuminate\Contracts\Auth\PasswordBrokerFactory](https://github.com/illuminate/contracts/blob/11.x/Auth/PasswordBrokerFactory.php) | `Password` | | [Illuminate\Contracts\Auth\StatefulGuard](https://github.com/illuminate/contracts/blob/11.x/Auth/StatefulGuard.php) | | | [Illuminate\Contracts\Auth\SupportsBasicAuth](https://github.com/illuminate/contracts/blob/11.x/Auth/SupportsBasicAuth.php) | | | [Illuminate\Contracts\Auth\UserProvider](https://github.com/illuminate/contracts/blob/11.x/Auth/UserProvider.php) | | | [Illuminate\Contracts\Broadcasting\Broadcaster](https://github.com/illuminate/contracts/blob/11.x/Broadcasting/Broadcaster.php) | `Broadcast::connection()` | | [Illuminate\Contracts\Broadcasting\Factory](https://github.com/illuminate/contracts/blob/11.x/Broadcasting/Factory.php) | `Broadcast` | | [Illuminate\Contracts\Broadcasting\ShouldBroadcast](https://github.com/illuminate/contracts/blob/11.x/Broadcasting/ShouldBroadcast.php) | | | [Illuminate\Contracts\Broadcasting\ShouldBroadcastNow](https://github.com/illuminate/contracts/blob/11.x/Broadcasting/ShouldBroadcastNow.php) | | | [Illuminate\Contracts\Bus\Dispatcher](https://github.com/illuminate/contracts/blob/11.x/Bus/Dispatcher.php) | `Bus` | | [Illuminate\Contracts\Bus\QueueingDispatcher](https://github.com/illuminate/contracts/blob/11.x/Bus/QueueingDispatcher.php) | `Bus::dispatchToQueue()` | | [Illuminate\Contracts\Cache\Factory](https://github.com/illuminate/contracts/blob/11.x/Cache/Factory.php) | `Cache` | | [Illuminate\Contracts\Cache\Lock](https://github.com/illuminate/contracts/blob/11.x/Cache/Lock.php) | | | [Illuminate\Contracts\Cache\LockProvider](https://github.com/illuminate/contracts/blob/11.x/Cache/LockProvider.php) | | | [Illuminate\Contracts\Cache\Repository](https://github.com/illuminate/contracts/blob/11.x/Cache/Repository.php) | `Cache::driver()` | | [Illuminate\Contracts\Cache\Store](https://github.com/illuminate/contracts/blob/11.x/Cache/Store.php) | | | [Illuminate\Contracts\Config\Repository](https://github.com/illuminate/contracts/blob/11.x/Config/Repository.php) | `Config` | | [Illuminate\Contracts\Console\Application](https://github.com/illuminate/contracts/blob/11.x/Console/Application.php) | | | [Illuminate\Contracts\Console\Kernel](https://github.com/illuminate/contracts/blob/11.x/Console/Kernel.php) | `Artisan` | | [Illuminate\Contracts\Container\Container](https://github.com/illuminate/contracts/blob/11.x/Container/Container.php) | `App` | | [Illuminate\Contracts\Cookie\Factory](https://github.com/illuminate/contracts/blob/11.x/Cookie/Factory.php) | `Cookie` | | [Illuminate\Contracts\Cookie\QueueingFactory](https://github.com/illuminate/contracts/blob/11.x/Cookie/QueueingFactory.php) | `Cookie::queue()` | | [Illuminate\Contracts\Database\ModelIdentifier](https://github.com/illuminate/contracts/blob/11.x/Database/ModelIdentifier.php) | | | [Illuminate\Contracts\Debug\ExceptionHandler](https://github.com/illuminate/contracts/blob/11.x/Debug/ExceptionHandler.php) | | | [Illuminate\Contracts\Encryption\Encrypter](https://github.com/illuminate/contracts/blob/11.x/Encryption/Encrypter.php) | `Crypt` | | [Illuminate\Contracts\Events\Dispatcher](https://github.com/illuminate/contracts/blob/11.x/Events/Dispatcher.php) | `Event` | | [Illuminate\Contracts\Filesystem\Cloud](https://github.com/illuminate/contracts/blob/11.x/Filesystem/Cloud.php) | `Storage::cloud()` | | [Illuminate\Contracts\Filesystem\Factory](https://github.com/illuminate/contracts/blob/11.x/Filesystem/Factory.php) | `Storage` | | [Illuminate\Contracts\Filesystem\Filesystem](https://github.com/illuminate/contracts/blob/11.x/Filesystem/Filesystem.php) | `Storage::disk()` | | [Illuminate\Contracts\Foundation\Application](https://github.com/illuminate/contracts/blob/11.x/Foundation/Application.php) | `App` | | [Illuminate\Contracts\Hashing\Hasher](https://github.com/illuminate/contracts/blob/11.x/Hashing/Hasher.php) | `Hash` | | [Illuminate\Contracts\Http\Kernel](https://github.com/illuminate/contracts/blob/11.x/Http/Kernel.php) | | | [Illuminate\Contracts\Mail\Mailable](https://github.com/illuminate/contracts/blob/11.x/Mail/Mailable.php) | | | [Illuminate\Contracts\Mail\Mailer](https://github.com/illuminate/contracts/blob/11.x/Mail/Mailer.php) | `Mail` | | [Illuminate\Contracts\Mail\MailQueue](https://github.com/illuminate/contracts/blob/11.x/Mail/MailQueue.php) | `Mail::queue()` | | [Illuminate\Contracts\Notifications\Dispatcher](https://github.com/illuminate/contracts/blob/11.x/Notifications/Dispatcher.php) | `Notification` | | [Illuminate\Contracts\Notifications\Factory](https://github.com/illuminate/contracts/blob/11.x/Notifications/Factory.php) | `Notification` | | [Illuminate\Contracts\Pagination\LengthAwarePaginator](https://github.com/illuminate/contracts/blob/11.x/Pagination/LengthAwarePaginator.php) | | | [Illuminate\Contracts\Pagination\Paginator](https://github.com/illuminate/contracts/blob/11.x/Pagination/Paginator.php) | | | [Illuminate\Contracts\Pipeline\Hub](https://github.com/illuminate/contracts/blob/11.x/Pipeline/Hub.php) | | | [Illuminate\Contracts\Pipeline\Pipeline](https://github.com/illuminate/contracts/blob/11.x/Pipeline/Pipeline.php) | `Pipeline` | | [Illuminate\Contracts\Queue\EntityResolver](https://github.com/illuminate/contracts/blob/11.x/Queue/EntityResolver.php) | | | [Illuminate\Contracts\Queue\Factory](https://github.com/illuminate/contracts/blob/11.x/Queue/Factory.php) | `Queue` | | [Illuminate\Contracts\Queue\Job](https://github.com/illuminate/contracts/blob/11.x/Queue/Job.php) | | | [Illuminate\Contracts\Queue\Monitor](https://github.com/illuminate/contracts/blob/11.x/Queue/Monitor.php) | `Queue` | | [Illuminate\Contracts\Queue\Queue](https://github.com/illuminate/contracts/blob/11.x/Queue/Queue.php) | `Queue::connection()` | | [Illuminate\Contracts\Queue\QueueableCollection](https://github.com/illuminate/contracts/blob/11.x/Queue/QueueableCollection.php) | | | [Illuminate\Contracts\Queue\QueueableEntity](https://github.com/illuminate/contracts/blob/11.x/Queue/QueueableEntity.php) | | | [Illuminate\Contracts\Queue\ShouldQueue](https://github.com/illuminate/contracts/blob/11.x/Queue/ShouldQueue.php) | | | [Illuminate\Contracts\Redis\Factory](https://github.com/illuminate/contracts/blob/11.x/Redis/Factory.php) | `Redis` | | [Illuminate\Contracts\Routing\BindingRegistrar](https://github.com/illuminate/contracts/blob/11.x/Routing/BindingRegistrar.php) | `Route` | | [Illuminate\Contracts\Routing\Registrar](https://github.com/illuminate/contracts/blob/11.x/Routing/Registrar.php) | `Route` | | [Illuminate\Contracts\Routing\ResponseFactory](https://github.com/illuminate/contracts/blob/11.x/Routing/ResponseFactory.php) | `Response` | | [Illuminate\Contracts\Routing\UrlGenerator](https://github.com/illuminate/contracts/blob/11.x/Routing/UrlGenerator.php) | `URL` | | [Illuminate\Contracts\Routing\UrlRoutable](https://github.com/illuminate/contracts/blob/11.x/Routing/UrlRoutable.php) | | | [Illuminate\Contracts\Session\Session](https://github.com/illuminate/contracts/blob/11.x/Session/Session.php) | `Session::driver()` | | [Illuminate\Contracts\Support\Arrayable](https://github.com/illuminate/contracts/blob/11.x/Support/Arrayable.php) | | | [Illuminate\Contracts\Support\Htmlable](https://github.com/illuminate/contracts/blob/11.x/Support/Htmlable.php) | | | [Illuminate\Contracts\Support\Jsonable](https://github.com/illuminate/contracts/blob/11.x/Support/Jsonable.php) | | | [Illuminate\Contracts\Support\MessageBag](https://github.com/illuminate/contracts/blob/11.x/Support/MessageBag.php) | | | [Illuminate\Contracts\Support\MessageProvider](https://github.com/illuminate/contracts/blob/11.x/Support/MessageProvider.php) | | | [Illuminate\Contracts\Support\Renderable](https://github.com/illuminate/contracts/blob/11.x/Support/Renderable.php) | | | [Illuminate\Contracts\Support\Responsable](https://github.com/illuminate/contracts/blob/11.x/Support/Responsable.php) | | | [Illuminate\Contracts\Translation\Loader](https://github.com/illuminate/contracts/blob/11.x/Translation/Loader.php) | | | [Illuminate\Contracts\Translation\Translator](https://github.com/illuminate/contracts/blob/11.x/Translation/Translator.php) | `Lang` | | [Illuminate\Contracts\Validation\Factory](https://github.com/illuminate/contracts/blob/11.x/Validation/Factory.php) | `Validator` | | [Illuminate\Contracts\Validation\ValidatesWhenResolved](https://github.com/illuminate/contracts/blob/11.x/Validation/ValidatesWhenResolved.php) | | | [Illuminate\Contracts\Validation\ValidationRule](https://github.com/illuminate/contracts/blob/11.x/Validation/ValidationRule.php) | | | [Illuminate\Contracts\Validation\Validator](https://github.com/illuminate/contracts/blob/11.x/Validation/Validator.php) | `Validator::make()` | | [Illuminate\Contracts\View\Engine](https://github.com/illuminate/contracts/blob/11.x/View/Engine.php) | | | [Illuminate\Contracts\View\Factory](https://github.com/illuminate/contracts/blob/11.x/View/Factory.php) | `View` | | [Illuminate\Contracts\View\View](https://github.com/illuminate/contracts/blob/11.x/View/View.php) | `View::make()` |

Contract

簡介

Contracts vs. Facades

When to Use Contracts

How to Use Contracts

Contract 對照表

留言