使用 Laravel Manager 類別 - 原理篇

發表於 更新於 Disqus：

今天來聊聊 Laravel 相關的主題，主要是 Manager 的使用方法。

下面將以 Laravel v9.37.0 的原始碼做說明

官方文件並沒有寫到這個類別，不過框架本身有在使用。

首先先來分析原始碼，是一段含註解不到 200 行的抽象類別，裡面依賴了 Container 實例，同時 Container 必須註冊 config，裡面放的是 Config 的實例；而抽象類所要求要實作的方法是 getDefaultDriver()，這裡的 Driver 指的可能是一群行為有相關的「實作」，而這個抽象方法是要取得預設的實作。

abstract class Manager
{
    // Laravel Container
    protected $container;

    // Laravel Config
    protected $config;

    public function __construct(Container $container)
    {
        $this->container = $container;
        $this->config = $container->make('config');
    }

    abstract public function getDefaultDriver();
}

這個抽象類別在框架裡面的實作有三個：

觀察上面官方的這三個實作可以發現，Manager 想要達成的其中一個目標是，要統一管理「建立實例的方法」，而實例的樣貌有三種類型如下：

  1. 相同的類別，但是不同的初始化方法。例如：SessionManager 一律都是回傳 Illuminate\Session\Store，但它建立實體的方法會隨著定義不同而有所不同；
  2. 相同的介面，但是不同的實作。例如： HashManager 產生的都是實作 Illuminate\Contracts\HashingHasher 介面的實體。
  3. 完全不相關的實作。例如：ChannelManager 產生的實體並沒有被任何介面約束，雖然程式裡可以查得到產生出來的實體都有實作 send() 方法，但實際上並沒有實作任何介面。

所以 Manager 是一個實作工廠模式（Factory Pattern）或建造者模式（Builder Pattern）的「管理者」。當不同的實作需要透過同一個實體管理時，Manager 會是一個很好的工具。

Manager 如何產生實體？

繼續看原始碼，首先是取得實體的入口 driver()：

public function driver($driver = null)
{
    // 如果沒有指定要取得哪個實作，則會拿預設的實作
    $driver = $driver ?: $this->getDefaultDriver();

    // 必須要指定，否則就丟例外
    if (is_null($driver)) {
        throw new InvalidArgumentException(sprintf(
            'Unable to resolve NULL driver for [%s].', static::class
        ));
    }

    // 這裡使用了 Registry Singleton Pattern
    // 指定實作若在記憶體有存在，則直接回傳，否則就建一個新的回傳
    if (! isset($this->drivers[$driver])) {
        $this->drivers[$driver] = $this->createDriver($driver);
    }

    return $this->drivers[$driver];
}

這裡可以看到有個 $this->drivers 的屬性，這是要存放已產生過的實體。相同的請求，在第二次進來的時候，會從記憶體直接取得並回傳，這是 Registry of Singleton Pattern 的實作。

再來看 createDriver() 實際建立實體的方法：

protected function createDriver($driver)
{
    // 當有設定自定義建立器的時候，就使用它
    if (isset($this->customCreators[$driver])) {
        return $this->callCustomCreator($driver);
    } else {
        // 如果沒有的話就看有沒有定義建立實體的方法
        // 如 `createSessionDriver()` 是否存在
        $method = 'create'.Str::studly($driver).'Driver';

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

    // 都沒有的話，就丟例外
    throw new InvalidArgumentException("Driver [$driver] not supported.");
}

一般使用 Manager 是為了要管理實體產生的方法，接著需要透過實作方法（指類別的 Method）來讓 Manager 在需要實體的實作來呼叫並產生對應的實體。

從上面這段程式碼裡面的 $method 變數可以知道，這個實作的方法名稱會跟 Driver 的名稱有關。實際的從 Driver 名稱轉換到方法名稱的範例如下：

cache => createCacheDriver
session => createSessionDriver
database => createDatabaseDriver
my_new-class => createMyNewClassDriver

擴充實體生成方法

在實作 Manager 的時候，會先預設好可能的實體生成方法，並先實作完成。例如 SessionManager 這個類別，已經實作好 File、Redis 與 Database 等實體的生成方法。但在兩個情境下，可能需要為實作的 Manager 擴充新的方法：

  1. 有新的實體生成方法，如 HashManager 有新的演算法。
  2. 原有的生成方法不滿意，因此想使用新的方法取代它。

Manager 擴充新的建立實體方法是透過呼叫 extend() 方法來達成：

public function extend($driver, Closure $callback)
{
    $this->customCreators[$driver] = $callback;

    return $this;
}

從行為上來看，這個方法可以透過註冊一個新的建立實體方法在 $this->customCreators 屬性裡。 而在前面呼叫 createDriver() 的時候會先確認 Driver 的名稱有沒有註冊，如果有的話會透過 callCustomCreator() 呼叫：

protected function callCustomCreator($driver)
{
    return $this->customCreators[$driver]($this->container);
}

因此可以想像註冊的方法可能會是像這樣：

$manager->extend('new', function(Container $app) {
    return new Some($app->make(Dep::class));
});

代理模式

Manager 除了當管理實體角色外，它也可以做為 Proxy Pattern 使用，因為它實作了一層可以作為代理的魔術方法（Magic Method）：

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

所有 Manager 不存在的方法，全都會轉去呼叫預設實作（因為 driver() 沒指定會拿到預設實作）的對應方法。

這個實作模式在 Laravel 很常見，像是 LogManager 可以把它當 PSR-3 來使用，實際上它代理了預設 Logger 的實作。

注意事項

前面有提到 Laravel 框架，剛好用在三個不同場景，因此這篇文章就不特別說明完整範例，只說明要注意的重點為何。

實務上在使用時，建議把它作為同一類型的實體產生器，如前面提到的第一個情境，相同類別，不同的初始化方法，或是第二個情境，相同介面不同實作。這就如同把 Manager 作為 Factory Pattern 來使用－－回傳的實體具有一致的介面或行為。

但因為 PHP 沒有泛型，所以有辦法創造出第三種情境－－呼叫 driver() 但回傳不同類型的實體。以我目前的經驗來說，是不建議這麼做的，因為在 Manager 回傳實作不明確時，在使用上就有可能造成非預期的結果。

2022/11/12：實作的部分額外寫一篇參考－－使用 Laravel Manager 類別 - 實戰篇