契約 (Contracts)

• 簡介
  • 契約與外觀 (Facades)
• 何時使用契約
• 如何使用契約
• 契約參考

簡介

Laravel 的“契約”（Contracts）是一組定義了框架核心服務的介面。例如，Illuminate\Contracts\Queue\Queue 契約定義了佇列任務所需的方法，而 Illuminate\Contracts\Mail\Mailer 契約則定義了傳送電子郵件所需的方法。

每個契約都有框架提供的相應實現。例如，Laravel 提供了一個包含多種驅動程式的佇列實現，以及一個由 Symfony Mailer 驅動的郵件傳送實現。

所有的 Laravel 契約都位於 它們自己的 GitHub 倉庫 中。這為所有可用的契約提供了一個快速參考點，同時作為一個獨立、解耦的包，可以在構建與 Laravel 服務互動的擴充套件包時使用。

契約與外觀 (Facades)

Laravel 的 外觀（Facades） 和輔助函式提供了一種簡單的方法來使用 Laravel 服務，而無需在服務容器中對契約進行型別提示（type-hint）和解析。在大多數情況下，每個外觀都有一個對應的契約。

與不需要在類建構函式中引入的外觀不同，契約允許你為類定義顯式依賴。一些開發者喜歡以這種方式顯式定義依賴，因此更傾向於使用契約；而另一些開發者則喜歡外觀帶來的便利。通常情況下，大多數應用程式在開發過程中使用外觀不會有任何問題。

何時使用契約

使用契約還是外觀的決定取決於個人偏好以及你的開發團隊的口味。契約和外觀都可以用來建立健壯、經過充分測試的 Laravel 應用程式。契約和外觀並不是互斥的。你應用程式的某些部分可以使用外觀，而另一些部分則依賴於契約。只要你保持類職責的單一，你會發現使用契約和外觀之間的實際差異非常小。

通常情況下，大多數應用程式在開發過程中使用外觀不會有任何問題。如果你正在構建一個集成了多個 PHP 框架的擴充套件包，你可能希望使用 illuminate/contracts 包來定義你與 Laravel 服務的整合，而無需在擴充套件包的 composer.json 檔案中引入 Laravel 的具體實現。

如何使用契約

那麼，如何獲取契約的實現呢？其實非常簡單。

Laravel 中的許多類都是透過 服務容器 進行解析的，包括控制器、事件監聽器、中介軟體、佇列任務，甚至是路由閉包。因此，要獲取契約的實現，只需在正在解析的類的建構函式中對介面進行“型別提示”即可。

例如，請看這個事件監聽器：

 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 the event listener.
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}

當事件監聽器被解析時，服務容器會讀取類建構函式上的型別提示，並注入相應的值。要了解更多關於在服務容器中註冊內容的資訊，請檢視相關文件。

契約參考

下表提供了所有 Laravel 契約及其對應外觀的快速參考：