契約(Contract)

簡介

Laravel 的「契約(Contract)」是一組接口,它們定義由框架提供的核心服務。例如,illuste\Contracts\Queue\Queue Contract 定義了隊列所需的方法,而 illuste\Contracts\Mail\Mailer Contract 定義了發送郵件所需的方法。

每個契約都有由框架提供的相應實現。例如,Laravel 提供了一個支持各種驅動的隊列實現,還有一個由 SwiftMailer 提供支持的郵件程序實現等等。

所有的 Laravel Contract 都存在於它們各自的 GitHub 倉庫。這為所有可用的契約提供了一個快速的參考點,以及一個可以被包開發人員使用的獨立的包。

Contract 對比 Facade

Laravel 的 Facade 和輔助函數提供了一種利用 Laravel 服務的簡單方法,無需類型提示並可以從服務容器中解析 Contract。在大多數情況下,每個 Facade 都有一個等效的 Contract。

和 Facade(不需要在構造函數中引入)不同,Contract 允許你為類定義顯式依賴關系。一些開發者更喜歡以這種方式顯式定義其依賴項,所以更喜歡使用 Contract,而其他開發者則享受 Facade 帶來的便利。通常,大多數應用都可以在開發過程中使用 Facade。

何時使用 Contract

使用 Contract 或 Facades 取決於個人喜好和開發團隊的喜好。Contract 和 Facade 均可用於創建功能強大且經過良好測試的 Laravel 應用。Contract 和 Facade 並不是一道單選題,你可以在同一個應用內同時使用 Contract 和 Facade。只要聚焦在類的職責應該單一上,你會發現 Contract 和 Facade 的實際差異其實很小。

通常情況下,大部分使用 Facade 的應用都不會在開發中遇到問題。但如果你在建立一個可以由多個 PHP 框架使用的擴展包,你可能會希望使用 illuminate/contracts 擴展包來定義該包和 Laravel 集成,而不需要引入完整的 Laravel 實現(不需要在 composer.json 中具體顯式引入 Laravel 框架來實現)。

如何使用 Contract

那麽,如何實現契約呢?它其實很簡單。

Laravel 中的許多類都是通過 服務容器 解析的,包括控制器、事件偵聽器、中間件、隊列任務,甚至路由閉包。因此,要實現契約,你只需要在被解析的類的構造函數中「類型提示」接口。

例如,看看下面的這個事件監聽器:

<?php

namespace App\Listeners;

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

class CacheOrderInformation
{
    /**
     * 創建一個新的事件監聽器實例
     */
    public function __construct(
        protected Factory $redis,
    ) {}

    /**
     * 處理該事件。
     */
    public function handle(OrderWasPlaced $event): void
    {
        // ...
    }
}

當解析事件監聽器時,服務容器將讀取構造函數上的類型提示,並注入適當的值。 要了解更多有關在服務容器中注冊內容的信息,請查看 其文檔

Contract 參考

下表提供了所有 Laravel Contract 及對應的 Facade 的快速參考:

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