合約

• 簡介
  • 合約 vs. 門面
• 何時使用合約
• 如何使用合約
• 合約參考

簡介

Laravel 的「合約」是一組定義框架提供的核心服務的介面。例如，Illuminate\Contracts\Queue\Queue 合約定義了佇列工作的必要方法，而 Illuminate\Contracts\Mail\Mailer 合約定義了傳送電子郵件的必要方法。

每個合約都有框架提供的相應實作。例如，Laravel 提供具有各種驅動程式的佇列實作，以及由 Symfony Mailer 提供支援的郵件程式實作。

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

合約 vs. 門面

Laravel 的 門面 和輔助函數提供了一種簡單的方法來使用 Laravel 的服務，而無需在服務容器中進行類型提示和解析合約。在大多數情況下，每個門面都有一個等效的合約。

與門面不同，門面不需要您在類別的建構函式中要求它們，合約允許您為類別定義明確的依賴關係。有些開發人員更喜歡以這種方式明確定義他們的依賴關係，因此更喜歡使用合約，而其他開發人員則喜歡門面的便利性。一般而言，大多數應用程式可以在開發期間毫無問題地使用門面。

何時使用合約

使用合約或門面的決定將取決於個人喜好和您的開發團隊的喜好。合約和門面都可以用來建立強大、經過良好測試的 Laravel 應用程式。合約和門面並非互斥。您的應用程式的某些部分可以使用門面，而其他部分則依賴合約。只要您保持類別的責任集中，您就會注意到使用合約和門面之間幾乎沒有實際差異。

一般而言，大多數應用程式可以在開發期間毫無問題地使用門面。如果您正在建構一個與多個 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 a new event handler instance.
     */
    public function __construct(
        protected Factory $redis,
    ) {}
 
    /**
     * Handle the event.
     */
    public function handle(OrderWasPlaced $event): void
    {
        // ...
    }
}

解析事件監聽器時，服務容器將讀取類別建構函式上的類型提示，並注入適當的值。若要深入瞭解如何在服務容器中註冊事物，請查看其文件。

合約參考

此表格提供了所有 Laravel 合約及其等效門面的快速參考