Laravel Pennant - Knowledge of Laravel

什麼是 Laravel Pennant

Laravel Pennant 是簡潔輕量的功能旗標（Feature Flag）套件。功能旗標可用來階段性推出新功能、進行 A/B 測試，或補充 trunk-based 開發。

什麼是功能旗標

透過功能旗標，可以將程式碼的部署與發佈分離。程式碼可先部署到正式環境，再以設定控制功能的開／關。

安裝

安裝套件

使用 Composer 安裝 Pennant。

composer require laravel/pennant

公開設定檔與 migration

使用 vendor:publish Artisan 指令公開檔案。

php artisan vendor:publish --provider="Laravel\Pennant\PennantServiceProvider"

這會在 config/pennant.php 產生設定，並在 database/migrations 產生 migration 檔案。

執行 migration

建立 Pennant 用來儲存 feature flag 值的 features 資料表。

php artisan migrate

設定

可在 config/pennant.php 設定所使用的儲存 driver。Pennant 支援兩種 driver。

Driver	說明
`database`	將值永久儲存到關聯式資料庫（預設）
`array`	儲存於記憶體（適用於測試或暫時使用）

// config/pennant.php
'default' => env('PENNANT_STORE', 'database'),

Feature 的定義

基於 closure 的定義

Feature 以 Feature facade 的 define 方法定義。通常在服務提供者的 boot 方法中定義。closure 會收到「scope」（通常是已認證的使用者）。

<?php

namespace App\Providers;

use App\Models\User;
use Illuminate\Support\Lottery;
use Illuminate\Support\ServiceProvider;
use Laravel\Pennant\Feature;

class AppServiceProvider extends ServiceProvider
{
    public function boot(): void
    {
        Feature::define('new-api', fn (User $user) => match (true) {
            $user->isInternalTeamMember() => true,
            $user->isHighTrafficCustomer() => false,
            default => Lottery::odds(1 / 100),
        });
    }
}

此 feature 的邏輯如下：

內部團隊成員一律 ON
高流量客戶為 OFF
其他人以 1% 機率 ON

feature 首次被檢查時，closure 的結果會存到儲存 driver。之後就會使用已儲存的值。

若定義只回傳 Lottery，可以省略 closure。

Feature::define('site-redesign', Lottery::odds(1, 1000));

基於類別的定義

Pennant 也支援類別式 feature 定義。使用類別方式時不需要在服務提供者中註冊。

php artisan pennant:feature NewApi

產生的類別會放在 app/Features 目錄。只要實作 resolve 方法即可。

<?php

namespace App\Features;

use App\Models\User;
use Illuminate\Support\Lottery;

class NewApi
{
    /**
     * 解析 feature 的初始值
     */
    public function resolve(User $user): mixed
    {
        return match (true) {
            $user->isInternalTeamMember() => true,
            $user->isHighTrafficCustomer() => false,
            default => Lottery::odds(1 / 100),
        };
    }
}

自訂儲存名稱

預設會儲存完整類別名稱。可用 Name 屬性自訂名稱。

use Laravel\Pennant\Attributes\Name;

#[Name('new-api')]
class NewApi
{
    // ...
}

攔截 feature 檢查（`before` 方法）

類別式 feature 可定義 before 方法。這個方法會在從儲存取得值之前於記憶體中執行；若回傳非 null 的值，就會使用該值。

class NewApi
{
    public function before(User $user): mixed
    {
        if (Config::get('features.new-api.disabled')) {
            return $user->isInternalTeamMember();
        }
    }

    public function resolve(User $user): mixed
    {
        // ...
    }
}

before 方法適合在發生 bug 時緊急停用功能，或安排在指定日期時間才進行 rollout 的情境。

Feature 的檢查

`Feature::active()` / `Feature::inactive()`

可用 active 方法確認 feature 是否啟用。預設會對目前已認證的使用者進行檢查。

use Laravel\Pennant\Feature;

if (Feature::active('new-api')) {
    // 使用新 API 的處理
}

若是類別式 feature，傳入類別名稱：

use App\Features\NewApi;

if (Feature::active(NewApi::class)) {
    // ...
}

也提供其他便利方法：

// 所有 feature 是否皆啟用
Feature::allAreActive(['new-api', 'site-redesign']);

// 是否有任一 feature 啟用
Feature::someAreActive(['new-api', 'site-redesign']);

// feature 是否停用
Feature::inactive('new-api');

// 所有 feature 是否皆停用
Feature::allAreInactive(['new-api', 'site-redesign']);

// 是否有任一 feature 停用
Feature::someAreInactive(['new-api', 'site-redesign']);

條件式執行（`when` / `unless`）

使用 when 方法可在 feature 啟用時執行 closure。

return Feature::when(NewApi::class,
    fn () => $this->resolveNewApiResponse($request),
    fn () => $this->resolveLegacyApiResponse($request),
);

unless 為 when 的相反，會在 feature 停用時執行第一個 closure。

return Feature::unless(NewApi::class,
    fn () => $this->resolveLegacyApiResponse($request),
    fn () => $this->resolveNewApiResponse($request),
);

`HasFeatures` trait

在 User model 加入 HasFeatures trait，即可直接從 model 檢查 feature。

use Laravel\Pennant\Concerns\HasFeatures;

class User extends Authenticatable
{
    use HasFeatures;
}

if ($user->features()->active('new-api')) {
    // ...
}

// 取得值
$value = $user->features()->value('purchase-button');

// 條件式執行
$user->features()->when('new-api',
    fn () => /* ... */,
    fn () => /* ... */,
);

Blade 指示詞

在 Blade 樣板中可使用 @feature 指示詞。

@feature('site-redesign')
    {{-- 'site-redesign' 啟用時 --}}
@else
    {{-- 'site-redesign' 停用時 --}}
@endfeature

@featureany(['site-redesign', 'beta'])
    {{-- 有任一啟用時 --}}
@endfeatureany

Middleware

使用 EnsureFeaturesAreActive middleware，可指定路由的存取需要哪些 feature。當 feature 停用時，會回傳 400 Bad Request。

use Laravel\Pennant\Middleware\EnsureFeaturesAreActive;

Route::get('/api/servers', function () {
    // ...
})->middleware(EnsureFeaturesAreActive::using('new-api', 'servers-api'));

要自訂回應，可使用 whenInactive 方法。

EnsureFeaturesAreActive::whenInactive(
    function (Request $request, array $features) {
        return new Response(status: 403);
    }
);

記憶體快取

Pennant 會在單一請求內將 feature 的結果快取到記憶體。即使多次檢查同一個 feature flag，也不會產生額外的 DB 查詢。若需要手動清除快取，可使用 flushCache 方法。

Feature::flushCache();

Scope

指定 scope

預設以已認證的使用者作為 scope，可用 for 方法指定任意 scope。

// 對特定使用者檢查
Feature::for($user)->active('new-api');

// 對團隊檢查
Feature::for($user->team)->active('billing-v2');

依團隊管理 feature 的範例：

Feature::define('billing-v2', function (Team $team) {
    if ($team->created_at->isAfter(new Carbon('1st Jan, 2023'))) {
        return true;
    }

    if ($team->created_at->isAfter(new Carbon('1st Jan, 2019'))) {
        return Lottery::odds(1 / 100);
    }

    return Lottery::odds(1 / 1000);
});

自訂預設 scope

可透過 Feature::resolveScopeUsing 自訂預設 scope。

Feature::resolveScopeUsing(fn ($driver) => Auth::user()?->team);

設定後省略 for 時就會採用預設 scope。

Feature::active('billing-v2');
// 等同於下列
Feature::for($user->team)->active('billing-v2');

可為 null 的 Scope

若 scope 為 null（例如未認證路由、Artisan 指令等），當 feature 定義未支援 null，會自動回傳 false。要處理 null 時，請以 nullable 型別定義。

Feature::define('new-api', fn (User|null $user) => match (true) {
    $user === null => true,
    $user->isInternalTeamMember() => true,
    $user->isHighTrafficCustomer() => false,
    default => Lottery::odds(1 / 100),
});

Rich Feature 值

feature 也可回傳 boolean 以外的值。例如在 A/B 測試中控制按鈕顏色。

Feature::define('purchase-button', fn (User $user) => Arr::random([
    'blue-sapphire',
    'seafoam-green',
    'tart-orange',
]));

使用 value 方法取得值。

$color = Feature::value('purchase-button');

在 Blade 中也能根據值進行條件分支。

@feature('purchase-button', 'blue-sapphire')
    {{-- blue-sapphire 啟用 --}}
@elsefeature('purchase-button', 'seafoam-green')
    {{-- seafoam-green 啟用 --}}
@elsefeature('purchase-button', 'tart-orange')
    {{-- tart-orange 啟用 --}}
@endfeature

使用 rich 值時，除 false 以外的所有值都會被視為啟用。

當 when 方法接收 rich 值時，第一個 closure 會收到該值。

Feature::when('purchase-button',
    fn ($color) => /* $color 內含值 */,
    fn () => /* 停用時 */,
);

取得多個 feature

使用 values 方法可一次取得多個 feature 的值。

Feature::values(['billing-v2', 'purchase-button']);

// [
//     'billing-v2' => false,
//     'purchase-button' => 'blue-sapphire',
// ]

使用 all 方法可取得所有已定義 feature 的值。

Feature::all();

若要將類別式 feature 也納入 all 的結果，在服務提供者呼叫 discover。

Feature::discover();

這會註冊 app/Features 目錄下所有的 feature 類別。

Eager Loading

在迴圈中檢查 feature 時可能會發生效能問題。可用 load 方法預先取得值來解決。

// NG：每次迴圈都會發生 DB 查詢
foreach ($users as $user) {
    if (Feature::for($user)->active('notifications-beta')) {
        $user->notify(new RegistrationSuccess);
    }
}

// OK：預先一次取得
Feature::for($users)->load(['notifications-beta']);

foreach ($users as $user) {
    if (Feature::for($user)->active('notifications-beta')) {
        $user->notify(new RegistrationSuccess);
    }
}

若只想取得尚未取得的值，可用 loadMissing。

Feature::for($users)->loadMissing([
    'new-api',
    'purchase-button',
    'notifications-beta',
]);

更新值

手動更新

可用 activate / deactivate 方法切換 feature 的開／關。

// 以預設 scope 啟用
Feature::activate('new-api');

// 對特定 scope 停用
Feature::for($user->team)->deactivate('billing-v2');

// 設定 rich 值
Feature::activate('purchase-button', 'seafoam-green');

若要忘掉已儲存的值，可用 forget 方法。下次檢查時會由定義重新評估。

Feature::forget('purchase-button');

批次更新

可用 activateForEveryone / deactivateForEveryone 對儲存中的所有 scope 進行批次套用。

Feature::activateForEveryone('new-api');
Feature::activateForEveryone('purchase-button', 'seafoam-green');
Feature::deactivateForEveryone('new-api');

Feature 的清除（purge）

若 feature 已從應用移除或定義有變更，可將值從儲存中清除（purge）。

// 清除單一 feature
Feature::purge('new-api');

// 清除多個 feature
Feature::purge(['new-api', 'purchase-button']);

// 清除所有 feature
Feature::purge();

也可使用 Artisan 指令清除。與部署流程結合會很方便。

php artisan pennant:purge new-api

# 多個指定
php artisan pennant:purge new-api purchase-button

# 清除指定 feature 以外的所有 feature
php artisan pennant:purge --except=new-api --except=purchase-button

# 清除未於服務提供者註冊的 feature
php artisan pennant:purge --except-registered

測試

重新定義 feature

在測試中可用 Feature::define 重新定義 feature，控制其回傳值。

tab=Pest

use Laravel\Pennant\Feature;

test('it can control feature values', function () {
    Feature::define('purchase-button', 'seafoam-green');

    expect(Feature::value('purchase-button'))->toBe('seafoam-green');
});

tab=PHPUnit

use Laravel\Pennant\Feature;

public function test_it_can_control_feature_values(): void
{
    Feature::define('purchase-button', 'seafoam-green');

    $this->assertSame('seafoam-green', Feature::value('purchase-button'));
}

類別式 feature 也可以同樣處理。

tab=Pest

test('it can control feature values', function () {
    Feature::define(NewApi::class, true);

    expect(Feature::value(NewApi::class))->toBeTrue();
});

tab=PHPUnit

use App\Features\NewApi;

public function test_it_can_control_feature_values(): void
{
    Feature::define(NewApi::class, true);

    $this->assertTrue(Feature::value(NewApi::class));
}

測試用 store 設定

可在 phpunit.xml 的環境變數指定測試中使用的 store。

<?xml version="1.0" encoding="UTF-8"?>
<phpunit colors="true">
    <php>
        <env name="PENNANT_STORE" value="array"/>
    </php>
</phpunit>

自訂 Driver

若既有 driver 不符合需求，可以建立自訂 driver。實作 Laravel\Pennant\Contracts\Driver 介面即可。

<?php

namespace App\Extensions;

use Laravel\Pennant\Contracts\Driver;

class RedisFeatureDriver implements Driver
{
    public function define(string $feature, callable $resolver): void {}
    public function defined(): array {}
    public function getAll(array $features): array {}
    public function get(string $feature, mixed $scope): mixed {}
    public function set(string $feature, mixed $scope, mixed $value): void {}
    public function setForAllScopes(string $feature, mixed $value): void {}
    public function delete(string $feature, mixed $scope): void {}
    public function purge(array|null $features): void {}
}

在服務提供者的 boot 方法中呼叫 extend 進行註冊。

Feature::extend('redis', function (Application $app) {
    return new RedisFeatureDriver($app->make('redis'), $app->make('events'), []);
});

註冊後即可在 config/pennant.php 指定 driver。

'stores' => [
    'redis' => [
        'driver' => 'redis',
        'connection' => null,
    ],
],

總結

需求	方法
安裝 feature	`composer require laravel/pennant`
定義 feature	`Feature::define('name', fn ($user) => ...)`
檢查 feature	`Feature::active('name')`
在 Blade 中檢查	`@feature('name') ... @endfeature`
更新值	`Feature::activate('name')` / `deactivate`
對所有 scope 套用	`Feature::activateForEveryone('name')`
於測試中控制	以 `Feature::define('name', true)` 重新定義
從儲存中清除	`Feature::purge('name')`

​什麼是 Laravel Pennant

​什麼是功能旗標

​安裝

​設定

​Feature 的定義

​基於 closure 的定義

​基於類別的定義

​自訂儲存名稱

​攔截 feature 檢查（before 方法）

​Feature 的檢查

​Feature::active() / Feature::inactive()

​條件式執行（when / unless）

​HasFeatures trait

​Blade 指示詞

​Middleware

​記憶體快取

​Scope

​指定 scope

​自訂預設 scope

​可為 null 的 Scope

​Rich Feature 值

​取得多個 feature

​Eager Loading

​更新值

​手動更新

​批次更新

​Feature 的清除（purge）

​測試

​重新定義 feature

​測試用 store 設定

​自訂 Driver

​總結

​後續步驟

除錯與錯誤處理

Laravel Pulse

什麼是 Laravel Pennant

什麼是功能旗標

安裝

設定

Feature 的定義

基於 closure 的定義

基於類別的定義

自訂儲存名稱

攔截 feature 檢查（`before` 方法）

Feature 的檢查

`Feature::active()` / `Feature::inactive()`

條件式執行（`when` / `unless`）

`HasFeatures` trait

Blade 指示詞

Middleware

記憶體快取

Scope

指定 scope

自訂預設 scope

可為 null 的 Scope

Rich Feature 值

取得多個 feature

Eager Loading

更新值

手動更新

批次更新

Feature 的清除（purge）

測試

重新定義 feature

測試用 store 設定

自訂 Driver

總結

後續步驟