Skip to content

Latest commit

 

History

History
159 lines (133 loc) · 14.3 KB

contracts.md

File metadata and controls

159 lines (133 loc) · 14.3 KB

合約

簡介

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 都可以用於創建堅固、經過良好測試的 Laravel 應用程式。合約和 facades 不是互斥的。應用程式的某些部分可能使用 facades,而其他部分依賴於合約。只要保持類別的責任專注,您將會注意到在使用合約和 facades 之間幾乎沒有實際差異。

一般來說,大多數應用程式在開發過程中可以毫無問題地使用 Facedes。如果您正在建立一個與多個 PHP 框架集成的套件,您可能希望使用 illuminate/contracts 套件來定義與 Laravel 服務的集成,而無需在您的套件的 composer.json 檔案中需要 Laravel 的具體實現。

如何使用 Contracts

那麼,如何獲取合約的實現?其實非常簡單。

在 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 合約及其對應 Facedes 的快速參考:

合約 參考 Facedes
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\Broadcasting\Broadcaster Broadcast::connection()
Illuminate\Contracts\Broadcasting\Factory Broadcast
Illuminate\Contracts\Broadcasting\ShouldBroadcast  
Illuminate\Contracts\Broadcasting\ShouldBroadcastNow  
Illuminate\Contracts\Bus\Dispatcher Bus
Illuminate\Contracts\Bus\QueueingDispatcher Bus::dispatchToQueue()
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\Mailable  
Illuminate\Contracts\Mail\Mailer Mail
Illuminate\Contracts\Mail\MailQueue Mail::queue()
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 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\ValidatesWhenResolved  
Illuminate\Contracts\Validation\ValidationRule  
Illuminate\Contracts\Validation\Validator Validator::make()
Illuminate\Contracts\View\Engine  
Illuminate\Contracts\View\Factory View
Illuminate\Contracts\View\View View::make()