Service Provider

說明如何使用 Laravel service provider 登記與啟動應用程式的服務。

​

什麼是 Service Provider

Service provider 是 Laravel 應用整體啟動的核心位置。無論是你自己的應用，或 Laravel 所有核心服務，都是透過 service provider 進行啟動。

「啟動」意指登記各種東西：向 service container 登記 binding、event listener、middleware、route 等。Service provider 是設定應用的核心處所。

Laravel 內部使用許多 service provider 啟動 mailer、queue、cache 等核心服務。這些多為「延遲」provider，並非在每次請求時載入，而是實際需要所提供的服務時才載入。

所有使用者定義的 service provider 皆在 bootstrap/providers.php 檔案登記。

想深入了解 Laravel 如何處理請求，請參閱 Request Lifecycle 文件。

​

撰寫 Service Provider

所有 service provider 都繼承 Illuminate\Support\ServiceProvider 類別。多數 provider 會有 register 方法與 boot 方法。

要產生新的 provider，使用 make:provider Artisan 指令。Laravel 會自動將新 provider 登記到 bootstrap/providers.php。

php artisan make:provider RiakServiceProvider

​

register 方法

在 register 方法內，只做service container的 binding。不要在 register 中登記 event listener、路由或其他功能。這可能誤用尚未載入的 service provider 所提供的服務。

<?php

namespace App\Providers;

use App\Services\Riak\Connection;
use Illuminate\Contracts\Foundation\Application;
use Illuminate\Support\ServiceProvider;

class RiakServiceProvider extends ServiceProvider
{
    /**
     * 登記應用服務
     */
    public function register(): void
    {
        $this->app->singleton(Connection::class, function (Application $app) {
            return new Connection(config('riak'));
        });
    }
}

在 service provider 的方法中，都可以透過 $this->app 屬性存取 service container。

​

bindings 屬性與 singletons 屬性

若要登記大量簡單的 binding，除了手動登記每個 binding 外，也可以使用 bindings 屬性與 singletons 屬性。當框架載入 service provider 時，會自動檢查這些屬性並登記 binding。

<?php

namespace App\Providers;

use App\Contracts\DowntimeNotifier;
use App\Contracts\ServerProvider;
use App\Services\DigitalOceanServerProvider;
use App\Services\PingdomDowntimeNotifier;
use App\Services\ServerToolsProvider;
use Illuminate\Support\ServiceProvider;

class AppServiceProvider extends ServiceProvider
{
    /**
     * 所有要登記的 container binding
     *
     * @var array
     */
    public $bindings = [
        ServerProvider::class => DigitalOceanServerProvider::class,
    ];

    /**
     * 所有要登記的 container singleton
     *
     * @var array
     */
    public $singletons = [
        DowntimeNotifier::class => PingdomDowntimeNotifier::class,
        ServerProvider::class => ServerToolsProvider::class,
    ];
}

​

boot 方法

在 service provider 中登記view composer 時，在 boot 方法中處理。此方法會在其他所有 service provider 登記完成後才被呼叫，因此可存取框架所登記的其他所有服務。

<?php

namespace App\Providers;

use Illuminate\Support\Facades\View;
use Illuminate\Support\ServiceProvider;

class ComposerServiceProvider extends ServiceProvider
{
    /**
     * 啟動應用服務
     */
    public function boot(): void
    {
        View::composer('view', function () {
            // ...
        });
    }
}

請勿混淆 register 方法與 boot 方法的職責。register 只登記 binding，boot 用於服務初始化或其他設定。

​

boot 方法的依賴注入

boot 方法也能用 type-hint 注入依賴。service container 會自動注入所需的依賴。

use Illuminate\Contracts\Routing\ResponseFactory;

/**
 * 啟動應用服務
 */
public function boot(ResponseFactory $response): void
{
    $response->macro('serialized', function (mixed $value) {
        // ...
    });
}

​

Service Provider 的登記方式

所有 service provider 都在 bootstrap/providers.php 檔案登記。此檔案回傳一個由應用 service provider 類別名稱組成的陣列。

<?php

return [
    App\Providers\AppServiceProvider::class,
];

在 Laravel 13 中，service provider 在 bootstrap/providers.php 登記，而不再是 config/app.php 的 providers 陣列。使用 make:provider 指令會自動加入。

執行 make:provider Artisan 指令時，Laravel 會自動把 provider 加到檔案中。若手動建立 provider 類別，需自行加入陣列。

<?php

return [
    App\Providers\AppServiceProvider::class,
    App\Providers\ComposerServiceProvider::class,
];

​

建立自訂 Service Provider

實際來建立自訂 service provider：

1. 產生 provider

   以 Artisan 指令產生 service provider。

   php artisan make:provider PaymentServiceProvider
   
2. 在 register 方法中 bind

   在產生的 provider 的 register 方法中撰寫 binding。

   <?php
   
   namespace App\Providers;
   
   use App\Contracts\PaymentGateway;
   use App\Services\StripePaymentGateway;
   use Illuminate\Contracts\Foundation\Application;
   use Illuminate\Support\ServiceProvider;
   
   class PaymentServiceProvider extends ServiceProvider
   {
       /**
        * 登記應用服務
        */
       public function register(): void
       {
           $this->app->singleton(PaymentGateway::class, function (Application $app) {
               return new StripePaymentGateway(
                   config('services.stripe.secret')
               );
           });
       }
   
       /**
        * 啟動應用服務
        */
       public function boot(): void
       {
           // 若有啟動時的處理，寫在這裡
       }
   }
   
3. 登記到 bootstrap/providers.php

   使用 make:provider 時會自動登記。手動時請自行加入。

   <?php
   
   return [
       App\Providers\AppServiceProvider::class,
       App\Providers\PaymentServiceProvider::class,
   ];
   

​

延遲 Provider（Deferred Providers）

若 provider 只登記 service container 的 binding，可將該登記延遲到實際需要時。將這類延遲 provider 的載入延後，可避免每次請求都從檔案系統載入，提升應用效能。

要建立延遲 provider，實作 \Illuminate\Contracts\Support\DeferrableProvider 介面並定義 provides 方法。provides 方法回傳 provider 所登記的 service container binding。

<?php

namespace App\Providers;

use App\Services\Riak\Connection;
use Illuminate\Contracts\Foundation\Application;
use Illuminate\Contracts\Support\DeferrableProvider;
use Illuminate\Support\ServiceProvider;

class RiakServiceProvider extends ServiceProvider implements DeferrableProvider
{
    /**
     * 登記應用服務
     */
    public function register(): void
    {
        $this->app->singleton(Connection::class, function (Application $app) {
                return new Connection(config('riak'));
            });
    }

    /**
     * 取得 provider 所提供的服務
     *
     * @return array<int, string>
     */
    public function provides(): array
    {
        return [Connection::class];
    }
}

延遲 provider 適合只在特定功能而非整個應用使用的服務。可避免載入不必要的服務、最佳化效能。

​

後續步驟

Service Container

確認 service container 機制與 binding 細節。