Illuminate\Support\Manager — Driver 系統解剖

什麼是 Manager

Illuminate\Support\Manager 是自 Laravel 4.0 以來就存在的抽象類別。它提供簡易的基礎，用來建構可切換多個「Driver」使用的系統，例如 Cache、Session、Mail。「Driver」是指擁有相同介面但內部實作不同的後端。舉例來說，Session 有 file、cookie、database、redis 等 Driver，可透過設定檔的 driver 鍵切換。

框架內的使用狀況

即便名稱含有 Manager，仍有並未繼承 Illuminate\Support\Manager 的類別存在。

類別	是否繼承 `Manager`
`Illuminate\Session\SessionManager`	✅ 有繼承
`Illuminate\Cache\CacheManager`	❌ 未繼承（自行實作）
`Illuminate\Queue\QueueManager`	❌ 未繼承（自行實作）
`Laravel\Socialite\SocialiteManager`	✅ 有繼承

未繼承者，其「以 extend() 擴充」的基本觀念是相同的。因此理解 Manager 模式即等於理解框架整體運作。

基本機制

driver() — 取得 Driver

呼叫 driver() 時，會依下列順序解析 Driver。觀察實際原始碼可看到，從 Driver 名稱以 Str::studly() 組成方法名稱。

// 出自 Illuminate\Support\Manager::createDriver()
protected function createDriver($driver)
{
    if (isset($this->customCreators[$driver])) {
        return $this->callCustomCreator($driver);
    }

    $method = 'create'.Str::studly($driver).'Driver';

    if (method_exists($this, $method)) {
        return $this->$method();
    }

    throw new InvalidArgumentException("Driver [$driver] not supported.");
}

也就是說，file Driver 會呼叫 createFileDriver()，my-custom Driver 則會呼叫 createMyCustomDriver()。

extend() — 註冊自訂 Driver

透過 extend() 傳入 Driver 名稱與 closure，即可註冊自訂 Driver。closure 的引數為容器實例。

use Illuminate\Support\Facades\Session;

Session::extend('redis-cluster', function ($app) {
    return new RedisClusterSessionHandler(
        $app->make('redis'),
        $app['config']['session'],
    );
});

extend() 會將 closure 綁定至 $this，因此可在 closure 中存取 Manager 的屬性與方法。

// 出自 Illuminate\Support\Manager::extend()
public function extend($driver, Closure $callback)
{
    try {
        $callback = $callback->bindTo($this, static::class) ?? throw new RuntimeException;
    } catch (Throwable) {
        $callback = $callback->bindTo(null, static::class);
    }

    $this->customCreators[$driver] = $callback;

    return $this;
}

__call — 委派至預設 Driver

Manager 類別實作了 __call，Manager 本身不存在的方法呼叫會自動委派給預設 Driver。

public function __call($method, $parameters)
{
    return $this->driver()->$method(...$parameters);
}

如此可實現「像 SessionManager::get('key') 一樣直接使用 Manager，實際處理則交給 Driver」的流程。

SessionManager 的實作範例

觀察 Illuminate\Session\SessionManager 可以具體了解 Manager 的使用方式。

namespace Illuminate\Session;

use Illuminate\Support\Manager;

class SessionManager extends Manager
{
    // 必要：回傳預設 Driver
    public function getDefaultDriver()
    {
        return $this->config->get('session.driver');
    }

    // file Driver 的產生
    protected function createFileDriver()
    {
        return $this->createNativeDriver();
    }

    // database Driver 的產生
    protected function createDatabaseDriver()
    {
        $table = $this->config->get('session.table');
        $lifetime = $this->config->get('session.lifetime');

        return $this->buildSession(new DatabaseSessionHandler(
            $this->getDatabaseConnection(), $table, $lifetime, $this->container
        ));
    }

    // redis Driver 的產生
    protected function createRedisDriver()
    {
        $handler = $this->createCacheHandler('redis');
        // ...
        return $this->buildSession($handler);
    }
}

於自製套件中使用 Manager

基本實作

以通知服務為例，建立繼承 Manager 的自訂類別。

建立繼承 Manager 的類別

namespace App\Notifications;

use Illuminate\Support\Manager;

class NotificationManager extends Manager
{
    public function getDefaultDriver(): string
    {
        return $this->config->get('notifications.driver', 'slack');
    }

    protected function createSlackDriver(): SlackNotifier
    {
        return new SlackNotifier(
            $this->config->get('notifications.slack'),
        );
    }

    protected function createEmailDriver(): EmailNotifier
    {
        return new EmailNotifier(
            $this->config->get('notifications.email'),
        );
    }

    protected function createLogDriver(): LogNotifier
    {
        return new LogNotifier(
            $this->container->make('log'),
        );
    }
}

於服務提供者註冊

namespace App\Providers;

use App\Notifications\NotificationManager;
use Illuminate\Support\ServiceProvider;

class NotificationServiceProvider extends ServiceProvider
{
    public function register(): void
    {
        $this->app->singleton(NotificationManager::class, function ($app) {
            return new NotificationManager($app);
        });
    }
}

新增自訂 Driver

// 於 AppServiceProvider::boot() 等

$manager = app(NotificationManager::class);

$manager->extend('teams', function ($app) {
    return new TeamsNotifier(
        $app['config']['notifications.teams'],
    );
});

使用

$manager = app(NotificationManager::class);

// 使用預設 Driver
$manager->send('訊息');

// 指定特定 Driver
$manager->driver('email')->send('訊息');

// 已解析過的 Driver 會被快取
$manager->driver('slack'); // 回傳同一實例

MultipleInstanceManager

Illuminate\Support\MultipleInstanceManager 是 Laravel 10 新增的類別。相對於 Manager 管理 Driver 的「種類」，MultipleInstanceManager 可管理多個具名的「實例」。

與 Manager 的差異

	`Manager`	`MultipleInstanceManager`
管理單位	Driver 種類（`file`, `redis` 等）	具名實例（`mailer1`, `mailer2` 等）
設定持有方式	一個預設 Driver	各實例各持設定
主要用途	Session、Cache 等	Mail、Log 等需要多個連線者
取得方法	`driver()`	`instance()`

必要方法

若要繼承 MultipleInstanceManager，需實作 3 個方法。

// 出自原始碼
abstract public function getDefaultInstance();
abstract public function setDefaultInstance($name);
abstract public function getInstanceConfig($name);

getInstanceConfig() 回傳對應名稱的設定陣列。設定中必定要包含 driver（或以 $driverKey 指定的 key）。

解析流程

自製套件的實作範例

以同時對應多個 SMS Gateway 的套件為例。

namespace App\Sms;

use Illuminate\Support\MultipleInstanceManager;

class SmsManager extends MultipleInstanceManager
{
    // 預設實例名稱
    public function getDefaultInstance(): string
    {
        return $this->config->get('sms.default', 'primary');
    }

    public function setDefaultInstance($name): void
    {
        $this->config->set('sms.default', $name);
    }

    // 回傳對應實例名稱的設定
    public function getInstanceConfig($name): array
    {
        return $this->config->get("sms.gateways.{$name}");
    }

    // twilio Driver 的產生（傳入設定陣列）
    protected function createTwilioDriver(array $config): TwilioSmsGateway
    {
        return new TwilioSmsGateway(
            $config['account_sid'],
            $config['auth_token'],
        );
    }

    // vonage Driver 的產生
    protected function createVonageDriver(array $config): VonageSmsGateway
    {
        return new VonageSmsGateway(
            $config['api_key'],
            $config['api_secret'],
        );
    }
}

對應的設定檔：

// config/sms.php
return [
    'default' => 'primary',

    'gateways' => [
        'primary' => [
            'driver' => 'twilio',
            'account_sid' => env('TWILIO_ACCOUNT_SID'),
            'auth_token' => env('TWILIO_AUTH_TOKEN'),
        ],
        'backup' => [
            'driver' => 'vonage',
            'api_key' => env('VONAGE_API_KEY'),
            'api_secret' => env('VONAGE_API_SECRET'),
        ],
        'marketing' => [
            'driver' => 'twilio',
            'account_sid' => env('TWILIO_MARKETING_SID'),
            'auth_token' => env('TWILIO_MARKETING_TOKEN'),
        ],
    ],
];

使用時以 instance() 指定名稱。

$sms = app(SmsManager::class);

// 使用預設實例（primary = twilio）
$sms->send('+886901234xxx', '驗證碼：123456');

// 以名稱指定實例
$sms->instance('backup')->send('+886901234xxx', '驗證碼：123456');

// 使用行銷用實例
$sms->instance('marketing')->send('+886901234xxx', '活動通知');

MultipleInstanceManager 與 Manager 相同，可以 extend() 加入自訂 Driver。亦實作了 __call，實例本身不存在的方法會委派給預設實例。

Driver 快取的管理

Manager 的快取操作

// 取得所有 Driver
$drivers = $manager->getDrivers();

// 清除所有 Driver 的快取
$manager->forgetDrivers();

MultipleInstanceManager 的快取操作

// 刪除特定實例
$manager->forgetInstance('backup');

// 刪除預設實例
$manager->forgetInstance();

// 一次刪除多個實例
$manager->forgetInstance(['primary', 'backup']);

// 刪除實例並清除快取
$manager->purge('backup');

總結

Manager 管理 Driver 的「種類」。實作 createXxxDriver() 方法，並以 extend() 擴充
MultipleInstanceManager 依名稱管理 Driver 的「實例」。適合需要多個連線設定的套件
名為 Manager 的類別並非全部繼承 Illuminate\Support\Manager。CacheManager 與 QueueManager 為自行實作

Macroable trait

學習為既有類別新增自訂方法的 Macroable trait 的用法。

AI 開發

設計模式

套件開發

應用程式結構

Laravel 13 新功能

Eloquent 深入探索

驗證擴充

認證擴充

安全性

佇列

測試

Illuminate\Support\Manager — Driver 系統解剖

什麼是 Manager

框架內的使用狀況

基本機制

driver() — 取得 Driver

extend() — 註冊自訂 Driver

__call — 委派至預設 Driver

SessionManager 的實作範例

於自製套件中使用 Manager

基本實作

MultipleInstanceManager

與 Manager 的差異

必要方法

解析流程

自製套件的實作範例

Driver 快取的管理

Manager 的快取操作

MultipleInstanceManager 的快取操作

總結

Macroable trait

​什麼是 Manager

​框架內的使用狀況

​基本機制

​driver() — 取得 Driver

​extend() — 註冊自訂 Driver

​__call — 委派至預設 Driver

​SessionManager 的實作範例

​於自製套件中使用 Manager

​基本實作

​MultipleInstanceManager

​與 Manager 的差異

​必要方法

​解析流程

​自製套件的實作範例

​Driver 快取的管理

​Manager 的快取操作

​MultipleInstanceManager 的快取操作

​總結

Macroable trait

什麼是 Manager

框架內的使用狀況

基本機制

driver() — 取得 Driver

extend() — 註冊自訂 Driver

__call — 委派至預設 Driver

SessionManager 的實作範例

於自製套件中使用 Manager

基本實作

MultipleInstanceManager

與 Manager 的差異

必要方法

解析流程

自製套件的實作範例

Driver 快取的管理

Manager 的快取操作

MultipleInstanceManager 的快取操作

總結