契約

• 簡介
  • 契約 vs. Facades
• 何時使用契約
• 如何使用契約
• 契約參考

簡介

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

每個契約都有框架提供的對應實作。例如，Laravel 提供了一個具有多種驅動程式的佇列實作，以及一個由 Symfony Mailer 驅動的郵件程式實作。

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

契約 vs. Facades

Laravel 的 facades 和輔助函數提供了一種簡單的方式來使用 Laravel 的服務，而無需類型提示和從服務容器解析契約。在大多數情況下，每個 facade 都有一個對應的契約。

與不需要在類別的建構函數中引入它們的 facades 不同，契約允許您為類別定義明確的依賴項。有些開發者偏好以這種方式明確定義依賴項，因此更喜歡使用契約，而其他開發者則喜歡 facades 的便利性。一般來說，大多數應用程式在開發期間可以毫無問題地使用 facades。

何時使用契約

使用契約還是 facades 的決定將取決於個人喜好和開發團隊的偏好。契約和 facades 都可以用來建立健壯的、經過良好測試的 Laravel 應用程式。契約和 facades 並非互斥的。應用程式的某些部分可能使用 facades，而其他部分則依賴契約。只要您保持類別的職責明確，您會發現使用契約和 facades 之間幾乎沒有實際差異。

一般來說，大多數應用程式在開發期間可以毫無問題地使用 facades。如果您正在建構一個與多個 PHP 框架整合的套件，您可能希望使用 illuminate/contracts 套件來定義與 Laravel 服務的整合，而無需在套件的 composer.json 檔案中要求 Laravel 的具體實作。

如何使用契約

那麼，如何獲得契約的實作呢？實際上非常簡單。

Laravel 中的許多類別類型都是透過服務容器解析的，包括控制器、事件監聽器、中介層、佇列任務，甚至路由閉包。因此，要獲得契約的實作，您只需在被解析的類別的建構函數中「類型提示」該介面即可。

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

<?php

namespace App\Listeners;

use App\Events\OrderWasPlaced;
use App\Models\User;
use Illuminate\Contracts\Redis\Factory;

class CacheOrderInformation
{
    /**
     * Create the event listener.
     */
    public function __construct(
        protected Factory $redis,
    ) {}

    /**
     * Handle the event.
     */
    public function handle(OrderWasPlaced $event): void
    {
        // ...
    }
}

當解析事件監聽器時，服務容器將讀取類別建構函數上的類型提示，並注入適當的值。要了解更多關於在服務容器中註冊的資訊，請查看其文件。

契約參考

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