延遲服務提供者

Laravel 啟動時註冊的服務提供者，即便在請求過程中一次都沒使用其功能，仍會每次被載入。延遲服務提供者（Deferred Service Provider）能解決此問題，將載入延後至服務實際被使用為止。

本頁以套件開發基礎的知識為前提。建議先理解服務提供者的基本機制後再閱讀。

為什麼需要延遲提供者

一般的服務提供者於每次請求都會呼叫 register() 與 boot()。像郵件、Queue、Cache 等並非每個頁面都使用的功能也都要每次初始化實屬浪費。

// 此提供者於每個請求都會呼叫 register()
class ReportServiceProvider extends ServiceProvider
{
    public function register(): void
    {
        // 每次都綁定沉重的報表服務
        $this->app->singleton(ReportGenerator::class, function ($app) {
            return new ReportGenerator(
                $app->make(PdfRenderer::class),
                $app->make(ChartRenderer::class),
                $app->make(DataExporter::class),
            );
        });
    }
}

將此提供者延遲化後，僅在實際產生報表的請求時才會被初始化。

DeferrableProvider 介面

Illuminate\Contracts\Support\DeferrableProvider 是僅具備 provides() 方法的簡單介面。

namespace Illuminate\Contracts\Support;

interface DeferrableProvider
{
    public function provides();
}

僅需實作此介面，提供者便會進入延遲模式。

基本實作

延遲提供者的實作分為 3 個步驟。

implements DeferrableProvider

use Illuminate\Contracts\Support\DeferrableProvider;
use Illuminate\Support\ServiceProvider;

class ReportServiceProvider extends ServiceProvider implements DeferrableProvider
{
    // ...
}

於 register() 綁定服務

與一般提供者相同，於 register() 撰寫綁定。

public function register(): void
{
    $this->app->singleton(ReportGenerator::class, function ($app) {
        return new ReportGenerator(
            $app->make(PdfRenderer::class),
            $app->make(ChartRenderer::class),
            $app->make(DataExporter::class),
        );
    });

    $this->app->singleton(ReportRepository::class, function ($app) {
        return new ReportRepository($app->make('db'));
    });
}

於 provides() 回傳所註冊的服務

provides() 必須回傳於 register() 綁定的所有服務。Laravel 會依此清單判斷「當要求哪些服務時要載入此提供者」。

public function provides(): array
{
    return [
        ReportGenerator::class,
        ReportRepository::class,
    ];
}

Service Manifest 的機制

Laravel 於啟動時會產生一個 bootstrap/cache/services.php 的 manifest 檔。此檔案中儲存了延遲提供者所提供的服務清單。

// bootstrap/cache/services.php 範例（自動產生）
return [
    'providers' => [
        // 與 bootstrap/providers.php 相同的清單
    ],
    'eager' => [
        // 立即載入的提供者
        App\Providers\AppServiceProvider::class,
    ],
    'deferred' => [
        // 服務名稱 => 提供者類別 的對應
        'App\Services\ReportGenerator' => ReportServiceProvider::class,
        'App\Repositories\ReportRepository' => ReportServiceProvider::class,
        'cache'     => Illuminate\Cache\CacheServiceProvider::class,
        'cache.store' => Illuminate\Cache\CacheServiceProvider::class,
        'queue'     => Illuminate\Queue\QueueServiceProvider::class,
    ],
    'when' => [],
];

透過此 manifest，Laravel 無需讀取檔案便能掌握「此服務由哪個提供者提供」。實際的提供者僅會在對應服務首次被解析時才會載入。

若新增或變更提供者，請重新產生 manifest。

php artisan optimize:clear
# 或
php artisan clear-compiled

內部運作流程

provides() 方法的重要性

若 provides() 中有遺漏，該服務將永遠無法被解析。

public function register(): void
{
    $this->app->singleton(ReportGenerator::class, fn ($app) => new ReportGenerator());

    // 新增的綁定
    $this->app->singleton('report', fn ($app) => $app->make(ReportGenerator::class));
}

public function provides(): array
{
    return [
        ReportGenerator::class,
        'report',  // ← 以字串 key 綁定的也不要忘了記載
    ];
}

使用 $bindings / $singletons 屬性時，也同樣要納入 provides()。

class AnalyticsServiceProvider extends ServiceProvider implements DeferrableProvider
{
    public $singletons = [
        AnalyticsClient::class => DefaultAnalyticsClient::class,
    ];

    public function provides(): array
    {
        // 回傳 $singletons 列舉的所有 key
        return [
            AnalyticsClient::class,
        ];
    }
}

延遲提供者的限制

延遲提供者適合於僅以向 Container 註冊綁定為目的的提供者。以下這類在 boot() 中進行的作業，其提供者無法延遲化。

限制	原因
路由註冊	路由於應用程式啟動時解析，延遲則無法運作
全域中介層註冊	需於請求處理前完成註冊
事件監聽器註冊（常時需要者）	事件觸發前若未註冊則無法運作
新增 Blade 指令	需於視圖編譯前註冊

可以在延遲提供者中撰寫 boot() 方法，但其內容在服務被解析前不會執行。若將「總是需要的處理」如路由或中介層寫在 boot()，將導致預期外的行為。

when() 方法 — 由事件觸發的註冊

使用 when() 方法，可在特定事件觸發時載入提供者。適用於 Job 處理系統等僅在特定情境下需要的提供者。

class ReportServiceProvider extends ServiceProvider implements DeferrableProvider
{
    public function register(): void
    {
        $this->app->singleton(ReportGenerator::class, fn () => new ReportGenerator());
    }

    public function provides(): array
    {
        return [ReportGenerator::class];
    }

    /**
     * 除了服務的綁定解析外，
     * 指定的事件觸發時也會載入提供者。
     */
    public function when(): array
    {
        return [
            \App\Events\ReportRequested::class,
        ];
    }
}

當 when() 中回傳的事件觸發時，即便服務未直接被解析，提供者也會被載入。

套件開發的活用

當作為第三方套件發布時，延遲提供者對使用者應用程式的效能也有幫助。

建議的模式

namespace Acme\Analytics;

use Illuminate\Contracts\Support\DeferrableProvider;
use Illuminate\Support\ServiceProvider;

class AnalyticsServiceProvider extends ServiceProvider implements DeferrableProvider
{
    public function register(): void
    {
        $this->mergeConfigFrom(__DIR__.'/../config/analytics.php', 'analytics');

        $this->app->singleton(AnalyticsManager::class, function ($app) {
            return new AnalyticsManager($app->make('config')->get('analytics'));
        });

        $this->app->singleton('analytics', fn ($app) => $app->make(AnalyticsManager::class));
    }

    public function boot(): void
    {
        // boot() 僅用於註冊 publishes
        if ($this->app->runningInConsole()) {
            $this->publishes([
                __DIR__.'/../config/analytics.php' => config_path('analytics.php'),
            ], 'analytics-config');
        }
    }

    public function provides(): array
    {
        return [
            AnalyticsManager::class,
            'analytics',
        ];
    }
}

mergeConfigFrom() 內部會檢查設定是否已快取，因此於延遲提供者的 register() 中呼叫也是安全的。但若設定已被快取則不會執行任何事。

以 `runningInConsole()` 分離 Artisan 指令註冊

因為指令註冊僅在 Artisan 啟動時需要，可以透過 runningInConsole() 進行條件判斷。但若要延遲提供指令的提供者，需將指令類別也納入 provides()，或另外準備專用於指令的提供者。

public function boot(): void
{
    if ($this->app->runningInConsole()) {
        $this->commands([
            AnalyticsFlushCommand::class,
        ]);
    }
}

Laravel Core 中的使用範例

Laravel Core 提供者中許多都是延遲提供者。這是為了不將每次請求不會用到的所有服務都立即載入的設計。

提供者	提供的服務
`CacheServiceProvider`	`cache`, `cache.store`, `RateLimiter`
`QueueServiceProvider`	`queue`, `queue.worker`, `queue.failer`
`MailServiceProvider`	`mail.manager`, `mailer`
`RedisServiceProvider`	`redis`, `redis.connection`
`HashServiceProvider`	`hash`, `hash.driver`
`ValidationServiceProvider`	`validator`, `validation.presence`
`TranslationServiceProvider`	`translator`
`BroadcastServiceProvider`	`Broadcast`

於僅有 API 端點的應用程式中，MailServiceProvider 或 BroadcastServiceProvider 也可能在請求過程中一次都不被載入。

是否應延遲化的判斷基準

適合延遲化的服務

並非在所有請求中使用的服務（郵件、報表、外部 API Client 等）
初始化時需要外部連線或讀取檔案的服務
具有龐大物件圖的服務
提供僅於 CLI 使用之指令的提供者

不適合延遲化的服務

註冊路由的提供者（如 loadRoutesFrom 等）
註冊常時運作的中介層或例外處理器的提供者
註冊 Eloquent Global Scope 或 Observer 的提供者
於大多數請求都會被使用的輕量服務（延遲的額外負擔反而更大時）

套件開發基礎

解說以服務提供者為核心的 Laravel 套件開發方式。

套件的版本相容性管理

解說對應 Laravel 與 PHP 主版本更新的套件維護策略。

AI 開發

設計模式

套件開發

應用程式結構

Laravel 13 新功能

Eloquent 深入探索

驗證擴充

認證擴充

安全性

佇列

測試

即時通訊

為什麼需要延遲提供者

DeferrableProvider 介面

基本實作

Service Manifest 的機制

內部運作流程

provides() 方法的重要性

延遲提供者的限制

when() 方法 — 由事件觸發的註冊

套件開發的活用

建議的模式

以 `runningInConsole()` 分離 Artisan 指令註冊

Laravel Core 中的使用範例

是否應延遲化的判斷基準

相關頁面

套件開發基礎

套件的版本相容性管理

​為什麼需要延遲提供者

​DeferrableProvider 介面

​基本實作

​Service Manifest 的機制

​內部運作流程

​provides() 方法的重要性

​延遲提供者的限制

​when() 方法 — 由事件觸發的註冊

​套件開發的活用

​建議的模式

​以 runningInConsole() 分離 Artisan 指令註冊

​Laravel Core 中的使用範例

​是否應延遲化的判斷基準

​相關頁面

套件開發基礎

套件的版本相容性管理

為什麼需要延遲提供者

DeferrableProvider 介面

基本實作

Service Manifest 的機制

內部運作流程

provides() 方法的重要性

延遲提供者的限制

when() 方法 — 由事件觸發的註冊

套件開發的活用

建議的模式

以 `runningInConsole()` 分離 Artisan 指令註冊

Laravel Core 中的使用範例

是否應延遲化的判斷基準

相關頁面