Service Container - Knowledge of Laravel

什麼是 Service Container

Laravel 的 service container 是管理類別依賴並進行依賴注入的機制。所謂依賴注入，是指透過建構子（或有時透過 setter 方法）將類別所需的依賴「注入」到類別中。看以下例子：

<?php

namespace App\Http\Controllers;

use App\Services\AppleMusic;
use Illuminate\View\View;

class PodcastController extends Controller
{
    /**
     * 建立新的 controller 實例
     */
    public function __construct(
        protected AppleMusic $apple,
    ) {}

    /**
     * 顯示指定 podcast 的資訊
     */
    public function show(string $id): View
    {
        return view('podcasts.show', [
            'podcast' => $this->apple->findPodcast($id)
        ]);
    }
}

此例中，PodcastController 需要從 Apple Music 等資料來源取得 Podcast。因此我們注入能取得 Podcast 的服務。透過注入服務，測試時能輕易換成 AppleMusic 服務的 mock（假實作）。

深入理解 service container 對於建構大型 Laravel 應用不可或缺，也對貢獻 Laravel 核心有所幫助。

零設定解析

若類別只依賴其他具體類別（非介面），無需告訴 container 如何解析。例如在 routes/web.php 寫下：

<?php

class Service
{
    // ...
}

Route::get('/', function (Service $service) {
    dd($service::class);
});

此例在路由檔中定義類別僅為示範。實際應用中，service 類別應定義於 app/Services 目錄。

存取此路由時，Laravel 會自動解析 Service 類別並注入到路由 handler。無需設定檔即可享受依賴注入。 controller、event listener、middleware 等 Laravel 應用中撰寫的多數類別，其依賴都會透過 container 自動注入。

Binding

基本 binding

多數 binding 會在service provider中登記。在 service provider 內可透過 $this->app 屬性存取 container。

bind

用 bind 方法傳入類別或介面名稱與 closure 來登記 binding。

use App\Services\Transistor;
use App\Services\PodcastParser;
use Illuminate\Contracts\Foundation\Application;

$this->app->bind(Transistor::class, function (Application $app) {
    return new Transistor($app->make(PodcastParser::class));
});

Closure 的引數會收到 container 本身。可用它解析子依賴。若要在 service provider 外操作 container，使用 App facade。

use App\Services\Transistor;
use Illuminate\Contracts\Foundation\Application;
use Illuminate\Support\Facades\App;

App::bind(Transistor::class, function (Application $app) {
    // ...
});

不依賴介面的類別不需要 bind 到 container。container 會以 reflection 自動解析這些物件。

singleton

singleton 方法會將類別或介面 bind 為只解析一次。一旦解析出的 singleton 之後每次向 container 呼叫都會回傳同一個實例。

use App\Services\Transistor;
use App\Services\PodcastParser;
use Illuminate\Contracts\Foundation\Application;

$this->app->singleton(Transistor::class, function (Application $app) {
    return new Transistor($app->make(PodcastParser::class));
});

使用 singletonIf 方法可以只在該型別尚未登記 binding 時才登記 singleton binding。

$this->app->singletonIf(Transistor::class, function (Application $app) {
    return new Transistor($app->make(PodcastParser::class));
});

Singleton 屬性

也可以在類別或介面加上 #[Singleton] 屬性，指示 container 只解析一次。

<?php

namespace App\Services;

use Illuminate\Container\Attributes\Singleton;

#[Singleton]
class Transistor
{
    // ...
}

Scoped singleton binding

scoped 方法將類別或介面 bind 為在 Laravel 請求／job 生命週期內只解析一次。與 singleton 類似，但以 scoped 登記的實例會在 Laravel 應用開始新的「生命週期」時被銷毀，例如 Laravel Octane worker 處理新請求，或 queue worker 處理新 job 時。

use App\Services\Transistor;
use App\Services\PodcastParser;
use Illuminate\Contracts\Foundation\Application;

$this->app->scoped(Transistor::class, function (Application $app) {
    return new Transistor($app->make(PodcastParser::class));
});

使用 scopedIf 方法可以只在該型別尚未登記 binding 時才登記 scoped binding。

$this->app->scopedIf(Transistor::class, function (Application $app) {
    return new Transistor($app->make(PodcastParser::class));
});

Scoped 屬性

也可以在類別或介面加上 #[Scoped] 屬性，指示 container 在請求／job 生命週期內只解析一次。

<?php

namespace App\Services;

use Illuminate\Container\Attributes\Scoped;

#[Scoped]
class Transistor
{
    // ...
}

instance

也可用 instance 方法將既有物件實例 bind 到 container。之後每次呼叫 container 都會回傳該實例。

use App\Services\Transistor;
use App\Services\PodcastParser;

$service = new Transistor(new PodcastParser);

$this->app->instance(Transistor::class, $service);

將介面 bind 到實作

service container 強大功能之一是可以將介面 bind 到特定實作。例如有 EventPusher 介面與 RedisEventPusher 實作：

use App\Contracts\EventPusher;
use App\Services\RedisEventPusher;

$this->app->bind(EventPusher::class, RedisEventPusher::class);

如此，container 會為需要 EventPusher 實作的類別注入 RedisEventPusher。之後只需在建構子 type-hint EventPusher 介面即可。

use App\Contracts\EventPusher;

/**
 * 建立新的類別實例
 */
public function __construct(
    protected EventPusher $pusher,
) {}

依賴介面就算換掉實作也不需改動程式碼。使測試與未來變更更容易。

Bind 屬性

Laravel 還提供更方便的 Bind 屬性。在介面加上此屬性，就可以告訴 Laravel 當該介面被要求時要自動注入哪個實作。使用 Bind 屬性時，service provider 中無需再登記。還可以在介面放多個 Bind 屬性，依環境注入不同實作。

<?php

namespace App\Contracts;

use App\Services\FakeEventPusher;
use App\Services\RedisEventPusher;
use Illuminate\Container\Attributes\Bind;

#[Bind(RedisEventPusher::class)]
#[Bind(FakeEventPusher::class, environments: ['local', 'testing'])]
interface EventPusher
{
    // ...
}

依任意條件的 binding，可用 BindWhen 屬性。closure 會收到 container，套用該 binding 時回傳 true。Bind 與 BindWhen 屬性會依宣告順序評估。

use App\Services\BetaEventPusher;
use Illuminate\Container\Attributes\BindWhen;
use Laravel\Pennant\Feature;

#[BindWhen(BetaEventPusher::class, static fn () => Feature::active('beta-events'))]
interface EventPusher
{
    // ...
}

使用 BindWhen 屬性需要 PHP 8.5 以上。

也可與 Singleton 或 Scoped 屬性併用，指定該 container binding 是否只解析一次、或每個請求／job 只解析一次。

use App\Services\RedisEventPusher;
use Illuminate\Container\Attributes\Bind;
use Illuminate\Container\Attributes\Singleton;

#[Bind(RedisEventPusher::class)]
#[Singleton]
interface EventPusher
{
    // ...
}

情境式 binding

有時你會希望對兩個使用相同介面的類別，各自注入不同的實作。例如兩個 controller 分別依賴 Illuminate\Contracts\Filesystem\Filesystem contract 的不同實作。Laravel 提供了簡潔流暢的介面來定義這種行為。

use App\Http\Controllers\PhotoController;
use App\Http\Controllers\UploadController;
use App\Http\Controllers\VideoController;
use Illuminate\Contracts\Filesystem\Filesystem;
use Illuminate\Support\Facades\Storage;

$this->app->when(PhotoController::class)
    ->needs(Filesystem::class)
    ->give(function () {
        return Storage::disk('local');
    });

$this->app->when([VideoController::class, UploadController::class])
    ->needs(Filesystem::class)
    ->give(function () {
        return Storage::disk('s3');
    });

when() 可接受單一類別或類別陣列。以 needs() 指定目標介面、以 give() 指定用於解析的 closure。如此一來，即便同樣型別提示 Filesystem 介面，也能依 controller 注入不同的 disk。

情境式屬性

情境式 binding 常用於注入 driver 或設定值的實作，因此 Laravel 提供了各式情境式 binding 屬性，讓你不必在 service provider 中手動定義情境式 binding。例如可以使用 Storage 屬性注入特定的儲存 disk。

<?php

namespace App\Http\Controllers;

use Illuminate\Container\Attributes\Storage;
use Illuminate\Contracts\Filesystem\Filesystem;

class PhotoController extends Controller
{
    public function __construct(
        #[Storage('local')] protected Filesystem $filesystem
    ) {
        // ...
    }
}

除了 Storage 屬性，Laravel 還提供 Auth、Cache、Config、Context、DB、Give、Log、RequestAttribute、RouteParameter、Tag 屬性。

<?php

namespace App\Http\Controllers;

use App\Contracts\UserRepository;
use App\Models\Organization;
use App\Models\Photo;
use App\Repositories\DatabaseRepository;
use Illuminate\Container\Attributes\Auth;
use Illuminate\Container\Attributes\Cache;
use Illuminate\Container\Attributes\Config;
use Illuminate\Container\Attributes\Context;
use Illuminate\Container\Attributes\DB;
use Illuminate\Container\Attributes\Give;
use Illuminate\Container\Attributes\Log;
use Illuminate\Container\Attributes\RequestAttribute;
use Illuminate\Container\Attributes\RouteParameter;
use Illuminate\Container\Attributes\Tag;
use Illuminate\Contracts\Auth\Guard;
use Illuminate\Contracts\Cache\Repository;
use Illuminate\Database\Connection;
use Psr\Log\LoggerInterface;

class PhotoController extends Controller
{
    public function __construct(
        #[Auth('web')] protected Guard $auth,
        #[Cache('redis')] protected Repository $cache,
        #[Config('app.timezone')] protected string $timezone,
        #[Context('uuid')] protected string $uuid,
        #[Context('ulid', hidden: true)] protected string $ulid,
        #[DB('mysql')] protected Connection $connection,
        #[Give(DatabaseRepository::class)] protected UserRepository $users,
        #[Log('daily')] protected LoggerInterface $log,
        #[RequestAttribute('organization')] protected Organization $organization,
        #[RouteParameter] protected Photo $photo,
        #[Tag('reports')] protected iterable $reports,
    ) {
        // ...
    }
}

RouteParameter 屬性會解析名稱與屬性名稱相符的路由參數。必要時也可以像 #[RouteParameter('photo')] 這樣明確指定路由參數名稱。 RequestAttribute 屬性會解析目前 Request 實例的輸入值。若想參照與屬性名稱不同的 key，請像 #[RequestAttribute('user_organization')] 這樣明確指定。

Give 屬性用於將介面解析為具體類別時，若想指定特定實作而非透過一般型別提示的自動解析，即可使用。

自動解析（以 type-hint 進行 DI）

service container 在解析 controller、event listener、middleware 等類別時，會查看建構子的 type-hint 自動注入依賴。

<?php

namespace App\Http\Controllers;

use App\Repositories\UserRepository;

class UserController extends Controller
{
    /**
     * 建立新的 controller 實例
     */
    public function __construct(
        protected UserRepository $users,
    ) {}
}

若 UserRepository 不依賴介面，就不用登記到 container。只要存取路由，container 就會自動解析依賴並注入到 controller。

從 Container 解析

make 方法

用 make 方法可從 container 解析類別實例。

use App\Services\Transistor;

$transistor = app()->make(Transistor::class);

若類別的依賴無法由 container 解析，也可用 makeWith 方法傳入額外引數。

$transistor = $this->app->makeWith(Transistor::class, ['id' => 1]);

自動注入

實際上，很少直接呼叫 make。只要在 container 會解析的類別（controller、event listener、middleware 等）建構子加上 type-hint，container 就會自動注入。

Facade 與 Container 的關係

Laravel 的 facade 為 container 內的物件提供靜態介面。例如 Cache::get() 內部會從 container 取得 Cache 服務再呼叫。

use Illuminate\Support\Facades\Cache;

// 使用 facade 呼叫
Cache::get('key');

// 直接使用 container 的等效呼叫
app('cache')->get('key');

Facade 是 container 的便利包裝。測試時可將 facade 替換為 mock。

use Illuminate\Support\Facades\Cache;

Cache::shouldReceive('get')
    ->once()
    ->with('key')
    ->andReturn('value');

建構子注入的實務範例

看實際應用中的典型模式：

定義介面

<?php

namespace App\Contracts;

interface PaymentGateway
{
    public function charge(int $amount, string $token): bool;
}

建立實作類別

<?php

namespace App\Services;

use App\Contracts\PaymentGateway;

class StripePaymentGateway implements PaymentGateway
{
    public function charge(int $amount, string $token): bool
    {
        // 使用 Stripe API 的付款處理...
        return true;
    }
}

在 Service Provider bind

use App\Contracts\PaymentGateway;
use App\Services\StripePaymentGateway;

$this->app->singleton(PaymentGateway::class, StripePaymentGateway::class);

在 controller 接收注入

<?php

namespace App\Http\Controllers;

use App\Contracts\PaymentGateway;
use Illuminate\Http\Request;

class OrderController extends Controller
{
    public function __construct(
        protected PaymentGateway $payment,
    ) {}

    public function store(Request $request)
    {
        $this->payment->charge(
            $request->amount,
            $request->payment_token
        );

        // ...
    }
}

透過此模式，即使要把付款服務從 Stripe 換成其他供應商，也只需改一處 binding。

後續步驟

Service Provider

學習使用 service provider 登記 binding 的方式。

​什麼是 Service Container

​零設定解析

​Binding

​基本 binding

​bind

​singleton

​Singleton 屬性

​Scoped singleton binding

​Scoped 屬性

​instance

​將介面 bind 到實作

​Bind 屬性

​情境式 binding

​情境式屬性

​自動解析（以 type-hint 進行 DI）

​從 Container 解析

​make 方法

​自動注入

​Facade 與 Container 的關係

​建構子注入的實務範例

​後續步驟

Service Provider

什麼是 Service Container

零設定解析

Binding

基本 binding

bind

singleton

Singleton 屬性

Scoped singleton binding

Scoped 屬性

instance

將介面 bind 到實作

Bind 屬性

情境式 binding

情境式屬性

自動解析（以 type-hint 進行 DI）

從 Container 解析

make 方法

自動注入

Facade 與 Container 的關係

建構子注入的實務範例

後續步驟