Laravel Pennant 實務案例

基本使用方式請參考指南頁面。本頁介紹官方文件中未提及的實務模式。

多租戶 SaaS 的團隊 Scope

若要以團隊（tenant）而非個人使用者為單位管理旗標，可將預設 scope 改為團隊。

// AppServiceProvider
Feature::resolveScopeUsing(fn () => Auth::user()?->currentTeam);

僅此一步 Feature::active('billing-v2') 就會自動以目前團隊為對象。只要屬於同一團隊，不論成員是誰結果都相同，UI 一致性因此得以保持。以下是依團隊註冊日期進行漸進式發佈的範例。

use App\Models\Team;
use Illuminate\Support\Carbon;
use Illuminate\Support\Lottery;
use Laravel\Pennant\Feature;

Feature::define('new-billing', function (Team $team) {
    // 2024 年以後註冊的團隊立即啟用
    if ($team->created_at->isAfter(new Carbon('2024-01-01'))) {
        return true;
    }

    // 2022〜2023 年註冊的以 10% 為單位發佈
    if ($team->created_at->isAfter(new Carbon('2022-01-01'))) {
        return Lottery::odds(1 / 10);
    }

    // 更舊的團隊謹慎地從 1% 開始
    return Lottery::odds(1 / 100);
});

若只想為特定團隊啟用（例如為企業客戶提早提供）：

// 部署後手動只對特定團隊啟用
Feature::for($earlyAccessTeam)->activate('new-billing');

緊急 Kill Switch（活用 `before` 方法）

正式環境發生錯誤時，可不回滾程式碼即刻停用該功能。在類別型 feature 加上 before 方法後，會先於儲存值進行檢查。

<?php

namespace App\Features;

use App\Models\User;
use Illuminate\Support\Facades\Config;

class NewCheckout
{
    /**
     * 於正式環境發生錯誤時可用 config 立即停用的緊急開關
     */
    public function before(User $user): mixed
    {
        // 由 config/features.php 的值或 env 控制
        if (Config::boolean('features.new_checkout_disabled', false)) {
            return false; // 對所有人立即停用
        }

        // 管理者永遠啟用（為了除錯）
        if ($user->isAdmin()) {
            return true;
        }

        return null; // 回傳 null 則走一般 resolve()
    }

    public function resolve(User $user): mixed
    {
        return $user->isPremium() || Lottery::odds(1 / 5);
    }
}

只要設定環境變數 FEATURES_NEW_CHECKOUT_DISABLED=true，就能不動 DB 即停用該功能。是不需部署的 kill switch。

before 回傳 null 時會執行 resolve()。回傳 false 則立即被視為未啟用。除緊急時以外請保持回傳 null。

排程式發佈

想在特定日期時間自動全面公開的情境，可用 before 方法實作。

public function before(User $user): mixed
{
    $rolloutDate = Config::get('features.new_api.rollout_date');

    if ($rolloutDate && Carbon::parse($rolloutDate)->isPast()) {
        return true; // 過發佈日期後對所有人公開
    }

    return null; // 尚未到期則走一般 resolve()
}

public function resolve(User $user): mixed
{
    // 發佈前僅內部成員可見
    return $user->isInternalTeamMember();
}

# .env
FEATURES_NEW_API_ROLLOUT_DATE=2025-04-01

只要一過 2025-04-01 就會自動對所有使用者公開。無須部署、無須 DB、無須 Artisan 指令即可自動化。

Dark Launch（Shadow Mode）

不讓使用者看見新邏輯，但以正式環境資料執行並與舊邏輯比較結果的模式。若無問題只要打開旗標即可完成發佈。

class RecommendationController
{
    public function index(Request $request)
    {
        $legacyResult = $this->getLegacyRecommendations($request->user());

        // shadow 模式下執行新演算法並比較，但顯示的是舊邏輯結果
        if (Feature::for($request->user())->active('recommendation-v2-shadow')) {
            try {
                $newResult = $this->getNewRecommendations($request->user());

                // 記錄差異到 log（不顯示給使用者）
                if ($legacyResult !== $newResult) {
                    Log::channel('shadow_mode')->info('recommendation diff', [
                        'user_id' => $request->user()->id,
                        'legacy'  => $legacyResult,
                        'new'     => $newResult,
                    ]);
                }
            } catch (\Throwable $e) {
                Log::error('shadow mode error', ['error' => $e->getMessage()]);
            }
        }

        // 回應永遠是舊邏輯的結果
        return response()->json($legacyResult);
    }
}

確認 log 沒有差異後，只要把旗標切為 recommendation-v2 即可。

用事件收集 A/B 測試結果

官方文件雖有提到 FeatureRetrieved 事件，但沒有實際的 A/B 測試彙整模式。 FeatureResolved 事件只有在 feature 的值首次被解析時才會觸發。可用它記錄使用者被分派的變體。

use Laravel\Pennant\Events\FeatureResolved;
use Illuminate\Support\Facades\Event;

// 於 AppServiceProvider 或 EventServiceProvider 註冊
Event::listen(function (FeatureResolved $event) {
    if ($event->feature !== 'purchase-button') {
        return;
    }

    // 於使用者被分派變體的時點記錄
    analytics()->identify($event->scope?->id, [
        'ab_purchase_button' => $event->value,
    ]);
});

若在轉換發生時另外記錄，就能算出每個變體的轉換率。

// 購買完成時
Event::dispatch(new PurchaseCompleted($user, $product));

// PurchaseCompleted listener
analytics()->track('purchase_completed', [
    'user_id'              => $user->id,
    'ab_purchase_button'   => Feature::for($user)->value('purchase-button'),
]);

FeatureResolved 與 FeatureRetrieved 的差異：FeatureResolved 只在首次評估時觸發，FeatureRetrieved 則在每次檢查時都觸發。分派紀錄用 FeatureResolved，頁面瀏覽追蹤用 FeatureRetrieved 較合適。

佇列 Job 中的 scope

佇列 Job 中沒有認證使用者，因此 feature 檢查可能行為出乎意料。請讓 Job 明確帶著 scope。

class SendWeeklyDigest implements ShouldQueue
{
    public function __construct(
        private readonly User $user
    ) {}

    public function handle(): void
    {
        // NG：無認證使用者，總會回傳 false
        // if (Feature::active('new-digest-layout')) { ... }

        // OK：明確傳入使用者
        if (Feature::for($this->user)->active('new-digest-layout')) {
            $this->sendNewLayout($this->user);
        } else {
            $this->sendLegacyLayout($this->user);
        }
    }
}

也可以在 Job dispatch 時就評估旗標並傳給 Job。

// 於 Controller 評估後傳給 Job
$useNewLayout = Feature::for($user)->active('new-digest-layout');

SendWeeklyDigest::dispatch($user, $useNewLayout);

用 Artisan 指令做管理 UI

只要建立一個簡單的 Artisan 指令，就能無須部署地操作正式環境旗標。

<?php

namespace App\Console\Commands;

use Illuminate\Console\Command;
use Laravel\Pennant\Feature;

class ManageFeatureFlag extends Command
{
    protected $signature = 'feature {action : activate|deactivate|status} {feature : Feature name}';
    protected $description = '管理功能旗標';

    public function handle(): void
    {
        $feature = $this->argument('feature');

        match ($this->argument('action')) {
            'activate'   => $this->activate($feature),
            'deactivate' => $this->deactivate($feature),
            'status'     => $this->status($feature),
            default      => $this->error('未知的動作'),
        };
    }

    private function activate(string $feature): void
    {
        Feature::activateForEveryone($feature);
        $this->info("✓ 已對所有使用者啟用 {$feature}");
    }

    private function deactivate(string $feature): void
    {
        Feature::deactivateForEveryone($feature);
        $this->info("✓ 已對所有使用者停用 {$feature}");
    }

    private function status(string $feature): void
    {
        $count = \DB::table('features')
            ->where('name', $feature)
            ->where('value', json_encode(true))
            ->count();

        $this->line("{$feature}：於 {$count} 個 scope 中啟用");
    }
}

php artisan feature activate new-checkout
php artisan feature deactivate new-checkout
php artisan feature status new-checkout

安全地重構 feature 名稱（`Name` 屬性）

重新命名類別型 feature 時，若 DB 中儲存的旗標名稱一起改變，所有使用者的旗標會被重置。可用 Name 屬性固定儲存名稱。

use Laravel\Pennant\Attributes\Name;

// 舊類別名：CheckoutV2 → 新類別名：NewCheckoutExperience
// 但 DB 一律以 'checkout-v2' 儲存
#[Name('checkout-v2')]
class NewCheckoutExperience
{
    public function resolve(User $user): mixed
    {
        return $user->isPremium();
    }
}

如此一來，即便自由重構類別名稱，DB 資料仍可維持不變。

總結

掌握官方文件的基本後，以下模式能真正發揮 Pennant 的價值。

模式	適用情境
團隊 Scope	多租戶 SaaS
`before` Kill Switch	正式環境問題緊急處理
排程發佈	指定日期時間的自動發佈
Dark Launch	安全地在正式環境驗證新演算法
`FeatureResolved` 事件	正確收集 A/B 測試結果
Job 明確 scope	佇列環境下的正確旗標評估
管理用 Artisan 指令	不需部署的正式旗標操作
`Name` 屬性	安全的類別重構

Laravel Pennant 指南

安裝到基本用法請參考指南頁面。

更新日誌

Laravel 13

產品

套件介紹

新版存放庫調查

升級指南

認證

前端

環境建置

多租戶 SaaS 的團隊 Scope

緊急 Kill Switch（活用 `before` 方法）

排程式發佈

Dark Launch（Shadow Mode）

用事件收集 A/B 測試結果

佇列 Job 中的 scope

用 Artisan 指令做管理 UI

安全地重構 feature 名稱（`Name` 屬性）

總結

Laravel Pennant 指南

​多租戶 SaaS 的團隊 Scope

​緊急 Kill Switch（活用 before 方法）

​排程式發佈

​Dark Launch（Shadow Mode）

​用事件收集 A/B 測試結果

​佇列 Job 中的 scope

​用 Artisan 指令做管理 UI

​安全地重構 feature 名稱（Name 屬性）

​總結

Laravel Pennant 指南

多租戶 SaaS 的團隊 Scope

緊急 Kill Switch（活用 `before` 方法）

排程式發佈

Dark Launch（Shadow Mode）

用事件收集 A/B 測試結果

佇列 Job 中的 scope

用 Artisan 指令做管理 UI

安全地重構 feature 名稱（`Name` 屬性）

總結