Skip to content

Contracts

簡介

Laravel 的「contracts」是一組定義框架所提供的核心服務的介面。舉例來說,Illuminate\Contracts\Queue\Queue contract 定義了排隊處理任務所需的方法,而 Illuminate\Contracts\Mail\Mailer contract 則定義了寄送電子郵件所需的方法。

每個 contract 都具備框架所提供的相應實作。例如,Laravel 提供了一個具有多種驅動器的佇列實作,以及一個由 Symfony Mailer 驅動的郵件實作。

所有 Laravel 的 contracts 都位於 它們自己的 GitHub 儲存庫 中。這為所有可用的 contracts 提供了一個快速參考點,也是一個單一、解耦的套件,可用於建立與 Laravel 服務互動的套件。

Contracts 與 Facades

Laravel 的 Facades 和輔助函式提供了一種簡單的方式來利用 Laravel 的服務,而無需在服務容器中進行型別提示並解析 contracts。在大多數情況下,每個 Facade 都會有一個對應的 contract。

不同於 Facades 不需要您在類別的建構函式中引入它們,contracts 允許您為類別定義明確的依賴關係。有些開發者偏好以這種方式明確定義他們的依賴關係,因此偏好使用 contracts;而其他開發者則喜歡 Facades 的便利性。通常,大多數應用程式在開發期間使用 Facades 都不會有問題。

何時使用 Contracts

使用 contracts 或 Facades 的決定取決於個人偏好以及您的開發團隊的品味。Contracts 和 Facades 都可以用於建立健壯、經過良好測試的 Laravel 應用程式。Contracts 和 Facades 並非互斥。您的應用程式的某些部分可能使用 Facades,而其他部分則依賴於 contracts。只要您讓類別的職責保持專注,您會發現使用 contracts 和 Facades 之間實際差異甚微。

通常,大多數應用程式在開發期間使用 Facades 都不會有問題。如果您正在建立一個與多個 PHP 框架整合的套件,您可能希望使用 illuminate/contracts 套件來定義您與 Laravel 服務的整合,而無需在套件的 composer.json 檔案中引入 Laravel 的具體實作。

如何使用 Contracts

那麼,您如何取得 contract 的實作呢?其實很簡單。

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

例如,請看這個事件監聽器:

<?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
    {
        // ...
    }
}

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

Contracts 參考

此表格提供所有 Laravel contracts 及其等效 facades 的快速參考:

Contract參考 Facade
Illuminate\Contracts\Auth\Access\Authorizable 
Illuminate\Contracts\Auth\Access\GateGate
Illuminate\Contracts\Auth\Authenticatable 
Illuminate\Contracts\Auth\CanResetPassword 
Illuminate\Contracts\Auth\FactoryAuth
Illuminate\Contracts\Auth\GuardAuth::guard()
Illuminate\Contracts\Auth\PasswordBrokerPassword::broker()
Illuminate\Contracts\Auth\PasswordBrokerFactoryPassword
Illuminate\Contracts\Auth\StatefulGuard 
Illuminate\Contracts\Auth\SupportsBasicAuth 
Illuminate\Contracts\Auth\UserProvider 
Illuminate\Contracts\Broadcasting\BroadcasterBroadcast::connection()
Illuminate\Contracts\Broadcasting\FactoryBroadcast
Illuminate\Contracts\Broadcasting\ShouldBroadcast 
Illuminate\Contracts\Broadcasting\ShouldBroadcastNow 
Illuminate\Contracts\Bus\DispatcherBus
Illuminate\Contracts\Bus\QueueingDispatcherBus::dispatchToQueue()
Illuminate\Contracts\Cache\FactoryCache
Illuminate\Contracts\Cache\Lock 
Illuminate\Contracts\Cache\LockProvider 
Illuminate\Contracts\Cache\RepositoryCache::driver()
Illuminate\Contracts\Cache\Store 
Illuminate\Contracts\Config\RepositoryConfig
Illuminate\Contracts\Console\Application 
Illuminate\Contracts\Console\KernelArtisan
Illuminate\Contracts\Container\ContainerApp
Illuminate\Contracts\Cookie\FactoryCookie
Illuminate\Contracts\Cookie\QueueingFactoryCookie::queue()
Illuminate\Contracts\Database\ModelIdentifier 
Illuminate\Contracts\Debug\ExceptionHandler 
Illuminate\Contracts\Encryption\EncrypterCrypt
Illuminate\Contracts\Events\DispatcherEvent
Illuminate\Contracts\Filesystem\CloudStorage::cloud()
Illuminate\Contracts\Filesystem\FactoryStorage
Illuminate\Contracts\Filesystem\FilesystemStorage::disk()
Illuminate\Contracts\Foundation\ApplicationApp
Illuminate\Contracts\Hashing\HasherHash
Illuminate\Contracts\Http\Kernel 
Illuminate\Contracts\Mail\Mailable 
Illuminate\Contracts\Mail\MailerMail
Illuminate\Contracts\Mail\MailQueueMail::queue()
Illuminate\Contracts\Notifications\DispatcherNotification
Illuminate\Contracts\Notifications\FactoryNotification
Illuminate\Contracts\Pagination\LengthAwarePaginator 
Illuminate\Contracts\Pagination\Paginator 
Illuminate\Contracts\Pipeline\Hub 
Illuminate\Contracts\Pipeline\PipelinePipeline
Illuminate\Contracts\Queue\EntityResolver 
Illuminate\Contracts\Queue\FactoryQueue
Illuminate\Contracts\Queue\Job 
Illuminate\Contracts\Queue\MonitorQueue
Illuminate\Contracts\Queue\QueueQueue::connection()
Illuminate\Contracts\Queue\QueueableCollection 
Illuminate\Contracts\Queue\QueueableEntity 
Illuminate\Contracts\Queue\ShouldQueue 
Illuminate\Contracts\Redis\FactoryRedis
Illuminate\Contracts\Routing\BindingRegistrarRoute
Illuminate\Contracts\Routing\RegistrarRoute
Illuminate\Contracts\Routing\ResponseFactoryResponse
Illuminate\Contracts\Routing\UrlGeneratorURL
Illuminate\Contracts\Routing\UrlRoutable 
Illuminate\Contracts\Session\SessionSession::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\TranslatorLang
Illuminate\Contracts\Validation\FactoryValidator
Illuminate\Contracts\Validation\ValidatesWhenResolved 
Illuminate\Contracts\Validation\ValidationRule 
Illuminate\Contracts\Validation\ValidatorValidator::make()
Illuminate\Contracts\View\Engine 
Illuminate\Contracts\View\FactoryView
Illuminate\Contracts\View\ViewView::make()