Laravel Pennant

简介
安装
配置
定义功能
- 基于类的功能
检查功能
作用域
丰富的功能值
检索多个功能
预加载
更新值
- 批量更新
- 清除功能
测试
添加自定义 Pennant 驱动
事件

简介

Laravel Pennant 是一个简单且轻量级的特性标志包——没有多余的东西。特性标志使您能够自信地逐步推出新的应用程序功能，进行 A/B 测试新的界面设计，补充基于主干开发策略，等等。

安装

首先，使用 Composer 包管理器将 Pennant 安装到您的项目中：

shell

composer require laravel/pennant

接下来，您应该使用 vendor:publish Artisan 命令发布 Pennant 的配置和迁移文件：

shell

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

最后，您应该运行应用程序的数据库迁移。这将创建一个 features 表，Pennant 使用该表来驱动其 database 驱动：

shell

php artisan migrate

配置

发布 Pennant 的资源后，其配置文件将位于 config/pennant.php。此配置文件允许您指定 Pennant 用于存储已解析的特性标志值的默认存储机制。

Pennant 支持通过 array 驱动将已解析的特性标志值存储在内存数组中。或者，Pennant 可以通过 database 驱动将已解析的特性标志值持久存储在关系数据库中，这是 Pennant 使用的默认存储机制。

定义功能

要定义一个功能，您可以使用 Feature Facade 提供的 define 方法。您需要为功能提供一个名称，以及一个将在解析功能的初始值时被调用的闭包。

通常，功能在服务提供者中使用 Feature Facade 定义。该闭包将接收功能检查的“作用域”。最常见的作用域是当前已认证的用户。在这个例子中，我们将定义一个功能，用于逐步向我们的应用程序用户推出一个新 API：

php

<?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),
        });
    }
}

如您所见，我们的功能有以下规则：

所有内部团队成员应该使用新 API。
任何高流量客户不应该使用新 API。
否则，该功能应随机分配给用户，活跃概率为 1/100。

对于给定用户，首次检查 new-api 功能时，闭包的结果将由存储驱动存储。下次对同一用户检查该功能时，将从存储中检索该值，并且不会调用闭包。

为方便起见，如果功能定义只返回一个抽奖（lottery），您可以完全省略闭包：

php

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

基于类的功能

Pennant 还允许您定义基于类的功能。与基于闭包的功能定义不同，无需在服务提供者中注册基于类的功能。要创建基于类的功能，您可以调用 pennant:feature Artisan 命令。默认情况下，功能类将放置在您应用程序的 app/Features 目录中：

shell

php artisan pennant:feature NewApi

编写功能类时，您只需要定义一个 resolve 方法，该方法将在为给定作用域解析功能的初始值时被调用。同样，作用域通常是当前已认证的用户：

php

<?php

namespace App\Features;

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

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

如果您想手动解析基于类的功能的实例，您可以调用 Feature Facade 上的 instance 方法：

php

use Illuminate\Support\Facades\Feature;

$instance = Feature::instance(NewApi::class);

NOTE

功能类通过容器解析，因此您可以在需要时向功能类的构造函数中注入依赖项。

自定义存储的功能名称

默认情况下，Pennant 将存储功能类的完全限定类名。如果您希望将存储的功能名称与应用程序的内部结构解耦，您可以在功能类上添加 Name 属性。此属性的值将代替类名存储：

php

<?php

namespace App\Features;

use Laravel\Pennant\Attributes\Name;

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

检查功能

要确定功能是否活跃，您可以使用 Feature Facade 上的 active 方法。默认情况下，功能会针对当前已认证的用户进行检查：

php

<?php

namespace App\Http\Controllers;

use Illuminate\Http\Request;
use Illuminate\Http\Response;
use Laravel\Pennant\Feature;

class PodcastController
{
    /**
     * 显示资源列表。
     */
    public function index(Request $request): Response
    {
        return Feature::active('new-api')
            ? $this->resolveNewApiResponse($request)
            : $this->resolveLegacyApiResponse($request);
    }

    // ...
}

尽管默认情况下功能是针对当前已认证的用户进行检查的，但您可以轻松地针对另一个用户或作用域检查功能。为此，请使用 Feature Facade 提供的 for 方法：

php

return Feature::for($user)->active('new-api')
    ? $this->resolveNewApiResponse($request)
    : $this->resolveLegacyApiResponse($request);

Pennant 还提供了一些额外的便捷方法，在确定功能是否活跃时可能有用：

php

// 确定所有给定的功能是否都活跃...
Feature::allAreActive(['new-api', 'site-redesign']);

// 确定任何给定的功能是否活跃...
Feature::someAreActive(['new-api', 'site-redesign']);

// 确定功能是否不活跃...
Feature::inactive('new-api');

// 确定所有给定的功能是否都不活跃...
Feature::allAreInactive(['new-api', 'site-redesign']);

// 确定任何给定的功能是否不活跃...
Feature::someAreInactive(['new-api', 'site-redesign']);

NOTE

当在 HTTP 上下文之外使用 Pennant 时，例如在 Artisan 命令或队列任务中，您通常应该显式指定功能的作用域。或者，您可以定义一个默认作用域，该作用域同时考虑了已认证的 HTTP 上下文和未认证的上下文。

检查基于类的功能

对于基于类的功能，您应该在检查功能时提供类名：

php

<?php

namespace App\Http\Controllers;

use App\Features\NewApi;
use Illuminate\Http\Request;
use Illuminate\Http\Response;
use Laravel\Pennant\Feature;

class PodcastController
{
    /**
     * 显示资源列表。
     */
    public function index(Request $request): Response
    {
        return Feature::active(NewApi::class)
            ? $this->resolveNewApiResponse($request)
            : $this->resolveLegacyApiResponse($request);
    }

    // ...
}

条件执行

when 方法可用于在功能活跃时流畅地执行给定的闭包。此外，可以提供一个第二个闭包，它将在功能不活跃时执行：

php

<?php

namespace App\Http\Controllers;

use App\Features\NewApi;
use Illuminate\Http\Request;
use Illuminate\Http\Response;
use Laravel\Pennant\Feature;

class PodcastController
{
    /**
     * 显示资源列表。
     */
    public function index(Request $request): Response
    {
        return Feature::when(NewApi::class,
            fn () => $this->resolveNewApiResponse($request),
            fn () => $this->resolveLegacyApiResponse($request),
        );
    }

    // ...
}

unless 方法是 when 方法的反向操作，如果功能不活跃，则执行第一个闭包：

php

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

`HasFeatures` Trait

Pennant 的 HasFeatures trait 可以添加到您的应用程序的 User 模型（或任何其他具有功能的模型）中，以提供一种流畅、便捷的方式直接从模型检查功能：

php

<?php

namespace App\Models;

use Illuminate\Foundation\Auth\User as Authenticatable;
use Laravel\Pennant\Concerns\HasFeatures;

class User extends Authenticatable
{
    use HasFeatures;

    // ...
}

一旦 trait 被添加到您的模型，您就可以通过调用 features 方法轻松检查功能：

php

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

当然，features 方法提供了许多其他与功能交互的便捷方法：

php

// 值...
$value = $user->features()->value('purchase-button')
$values = $user->features()->values(['new-api', 'purchase-button']);

// 状态...
$user->features()->active('new-api');
$user->features()->allAreActive(['new-api', 'server-api']);
$user->features()->someAreActive(['new-api', 'server-api']);

$user->features()->inactive('new-api');
$user->features()->allAreInactive(['new-api', 'server-api']);
$user->features()->someAreInactive(['new-api', 'server-api']);

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

$user->features()->unless('new-api',
    fn () => /* ... */,
    fn () => /* ... */,
);

Blade 指令

为了使在 Blade 中检查功能获得无缝体验，Pennant 提供了 @feature 和 @featureany 指令：

blade

@feature('site-redesign')
    <!-- 'site-redesign' 活跃 -->
@else
    <!-- 'site-redesign' 不活跃 -->
@endfeature

@featureany(['site-redesign', 'beta'])
    <!-- 'site-redesign' 或 'beta' 活跃 -->
@endfeatureany

中间件

Pennant 还包含一个中间件，可用于在路由被调用之前验证当前已认证的用户是否有权访问某个功能。您可以将中间件分配给一个路由，并指定访问该路由所需的功能。如果当前已认证的用户有任何指定的功能不活跃，路由将返回一个 400 Bad Request HTTP 响应。多个功能可以传递给静态的 using 方法。

php

use Illuminate\Support\Facades\Route;
use Laravel\Pennant\Middleware\EnsureFeaturesAreActive;

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

自定义响应

如果您想自定义当列出的功能之一不活跃时中间件返回的响应，您可以使用 EnsureFeaturesAreActive 中间件提供的 whenInactive 方法。通常，此方法应在您的应用程序的某个服务提供者的 boot 方法中调用：

php

use Illuminate\Http\Request;
use Illuminate\Http\Response;
use Laravel\Pennant\Middleware\EnsureFeaturesAreActive;

/**
 * 引导任何应用程序服务。
 */
public function boot(): void
{
    EnsureFeaturesAreActive::whenInactive(
        function (Request $request, array $features) {
            return new Response(status: 403);
        }
    );

    // ...
}

拦截功能检查

有时，在检索给定功能的存储值之前执行一些内存检查可能很有用。想象一下，您正在一个特性标志后面开发一个新 API，并且希望能够在不丢失存储中任何已解析功能值的情况下禁用新 API。如果您在新 API 中发现了一个错误，您可以轻松地为除内部团队成员以外的所有人禁用它，修复错误，然后为以前有权访问该功能的用户重新启用新 API。

您可以通过基于类的功能的 before 方法实现这一点。当存在时，before 方法总是在从存储中检索值之前在内存中运行。如果该方法返回一个非 null 值，它将在请求期间代替该功能的存储值使用：

php

<?php

namespace App\Features;

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

class NewApi
{
    /**
     * 在检索存储值之前运行始终在内存中的检查。
     */
    public function before(User $user): mixed
    {
        if (Config::get('features.new-api.disabled')) {
            return $user->isInternalTeamMember();
        }
    }

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

您还可以使用此功能安排先前处于特性标志之后的功能的全局推出：

php

<?php

namespace App\Features;

use Illuminate\Support\Carbon;
use Illuminate\Support\Facades\Config;

class NewApi
{
    /**
     * 在检索存储值之前运行始终在内存中的检查。
     */
    public function before(User $user): mixed
    {
        if (Config::get('features.new-api.disabled')) {
            return $user->isInternalTeamMember();
        }

        if (Carbon::parse(Config::get('features.new-api.rollout-date'))->isPast()) {
            return true;
        }
    }

    // ...
}

内存缓存

检查功能时，Pennant 将创建结果的内存缓存。如果您使用 database 驱动，这意味着在单个请求中重新检查同一个特性标志不会触发额外的数据库查询。这还确保了功能在请求期间具有一致的结果。

如果您需要手动刷新内存缓存，您可以使用 Feature Facade 提供的 flushCache 方法：

php

Feature::flushCache();

作用域

指定作用域

如前所述，功能通常是针对当前已认证的用户进行检查的。然而，这可能并不总是满足您的需求。因此，可以通过 Feature Facade 的 for 方法指定您想要针对其检查给定功能的作用域：

php

return Feature::for($user)->active('new-api')
    ? $this->resolveNewApiResponse($request)
    : $this->resolveLegacyApiResponse($request);

当然，功能作用域不仅限于“用户”。想象一下，您已经构建了一个新的计费体验，您希望向整个团队而不是单个用户推出。也许您希望较老的团队比新团队拥有更慢的推出速度。您的功能解析闭包可能如下所示：

php

use App\Models\Team;
use Illuminate\Support\Carbon;
use Illuminate\Support\Lottery;
use Laravel\Pennant\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);
});

您会注意到我们定义的闭包期望的不是 User，而是 Team 模型。要确定此功能对于用户的团队是否活跃，您应该将团队传递给 Feature Facade 提供的 for 方法：

php

if (Feature::for($user->team)->active('billing-v2')) {
    return redirect('/billing/v2');
}

// ...

默认作用域

也可以自定义 Pennant 用于检查功能的默认作用域。例如，也许您的所有功能都是针对当前已认证用户的团队而不是用户进行检查的。您不必每次检查功能时都调用 Feature::for($user->team)，而是可以将团队指定为默认作用域。通常，这应该在您的应用程序的某个服务提供者中完成：

php

<?php

namespace App\Providers;

use Illuminate\Support\Facades\Auth;
use Illuminate\Support\ServiceProvider;
use Laravel\Pennant\Feature;

class AppServiceProvider extends ServiceProvider
{
    /**
     * 引导任何应用程序服务。
     */
    public function boot(): void
    {
        Feature::resolveScopeUsing(fn ($driver) => Auth::user()?->team);

        // ...
    }
}

如果没有通过 for 方法显式提供作用域，功能检查现在将使用当前已认证用户的团队作为默认作用域：

php

Feature::active('billing-v2');

// 现在等同于...

Feature::for($user->team)->active('billing-v2');

可空作用域

如果您在检查功能时提供的作用域是 null，并且功能的定义不支持通过可空类型或通过在联合类型中包含 null 来接受 null，Pennant 将自动返回 false 作为功能的结果值。

因此，如果您传递给功能的作用域可能是 null，并且您希望调用功能的值解析器，您应该在功能定义中考虑到这一点。如果您在 Artisan 命令、队列任务或未认证的路由中检查功能，可能会出现 null 作用域。由于在这些上下文中通常没有已认证的用户，默认作用域将是 null。

如果您不总是显式指定您的功能作用域，那么您应该确保作用域的类型是“可空的”，并在您的功能定义逻辑中处理 null 作用域值：

php

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

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

识别作用域

Pennant 内置的 array 和 database 存储驱动知道如何为所有 PHP 数据类型以及 Eloquent 模型正确存储作用域标识符。但是，如果您的应用程序使用了第三方 Pennant 驱动，该驱动可能不知道如何为 Eloquent 模型或应用程序中的其他自定义类型正确存储标识符。

鉴于此，Pennant 允许您通过在用作 Pennant 作用域的应用程序中的对象上实现 FeatureScopeable 契约来格式化要存储的作用域值。

例如，假设您在单个应用程序中使用了两个不同的功能驱动：内置的 database 驱动和一个第三方的 "Flag Rocket" 驱动。"Flag Rocket" 驱动不知道如何正确存储 Eloquent 模型。相反，它需要一个 FlagRocketUser 实例。通过实现 FeatureScopeable 契约定义的 toFeatureIdentifier 方法，我们可以自定义提供给应用程序使用的每个驱动的可存储作用域值：

php

<?php

namespace App\Models;

use FlagRocket\FlagRocketUser;
use Illuminate\Database\Eloquent\Model;
use Laravel\Pennant\Contracts\FeatureScopeable;

class User extends Model implements FeatureScopeable
{
    /**
     * 将对象转换为给定驱动的功能作用域标识符。
     */
    public function toFeatureIdentifier(string $driver): mixed
    {
        return match($driver) {
            'database' => $this,
            'flag-rocket' => FlagRocketUser::fromId($this->flag_rocket_id),
        };
    }
}

序列化作用域

默认情况下，Pennant 在存储与 Eloquent 模型关联的功能时将使用完全限定的类名。如果您已经在使用 Eloquent 多态映射，您可以选择让 Pennant 也使用多态映射，以将存储的功能与您的应用程序结构解耦。

为此，在服务提供者中定义好 Eloquent 多态映射后，您可以调用 Feature Facade 的 useMorphMap 方法：

php

use Illuminate\Database\Eloquent\Relations\Relation;
use Laravel\Pennant\Feature;

Relation::enforceMorphMap([
    'post' => 'App\Models\Post',
    'video' => 'App\Models\Video',
]);

Feature::useMorphMap();

丰富的功能值

到目前为止，我们主要展示了功能处于二元状态，意味着它们要么“活跃”要么“不活跃”，但 Pennant 也允许您存储丰富的值。

例如，假设您正在为应用程序的“立即购买”按钮测试三种新颜色。您可以在功能定义中返回一个字符串，而不是返回 true 或 false：

php

use Illuminate\Support\Arr;
use Laravel\Pennant\Feature;

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

您可以使用 value 方法检索 purchase-button 功能的值：

php

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

Pennant 包含的 Blade 指令还可以轻松地根据功能的当前值有条件地渲染内容：

blade

@feature('purchase-button', 'blue-sapphire')
    <!-- 'blue-sapphire' 活跃 -->
@elsefeature('purchase-button', 'seafoam-green')
    <!-- 'seafoam-green' 活跃 -->
@elsefeature('purchase-button', 'tart-orange')
    <!-- 'tart-orange' 活跃 -->
@endfeature

NOTE

当使用丰富的值时，重要的是要知道，当功能具有除 false 之外的任何值时，它被认为是“活跃”的。

当调用条件 when 方法时，功能的丰富值将提供给第一个闭包：

php

Feature::when('purchase-button',
    fn ($color) => /* ... */,
    fn () => /* ... */,
);

同样，当调用条件 unless 方法时，功能的丰富值将提供给可选的第二个闭包：

php

Feature::unless('purchase-button',
    fn () => /* ... */,
    fn ($color) => /* ... */,
);

检索多个功能

values 方法允许检索给定作用域的多个功能：

php

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

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

或者，您可以使用 all 方法来检索给定作用域的所有已定义功能的值：

php

Feature::all();

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

但是，基于类的功能是动态注册的，并且直到它们被显式检查时 Pennant 才知道它们。这意味着，如果在当前请求期间尚未检查您的应用程序的基于类的功能，它们可能不会出现在 all 方法返回的结果中。

如果您想确保在使用 all 方法时始终包含功能类，您可以使用 Pennant 的功能发现能力。首先，在您的某个应用程序服务提供者中调用 discover 方法：

php

<?php

namespace App\Providers;

use Illuminate\Support\ServiceProvider;
use Laravel\Pennant\Feature;

class AppServiceProvider extends ServiceProvider
{
    /**
     * 引导任何应用程序服务。
     */
    public function boot(): void
    {
        Feature::discover();

        // ...
    }
}

discover 方法将注册您应用程序的 app/Features 目录中的所有功能类。现在，all 方法将把这些类包含在其结果中，无论它们是否在当前请求期间被检查过：

php

Feature::all();

// [
//     'App\Features\NewApi' => true,
//     'billing-v2' => false,
//     'purchase-button' => 'blue-sapphire',
//     'site-redesign' => true,
// ]

预加载

尽管 Pennant 为单个请求中所有已解析的功能保留了内存缓存，但仍然可能遇到性能问题。为了缓解这个问题，Pennant 提供了预加载功能值的能力。

为了说明这一点，假设我们在一个循环中检查某个功能是否活跃：

php

use Laravel\Pennant\Feature;

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

假设我们使用的是数据库驱动，这段代码将为循环中的每个用户执行一次数据库查询——可能执行数百个查询。然而，使用 Pennant 的 load 方法，我们可以通过为一批用户或作用域预加载功能值来消除这个潜在的性能瓶颈：

php

Feature::for($users)->load(['notifications-beta']);

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

要仅在功能值尚未加载时才加载它们，您可以使用 loadMissing 方法：

php

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

您可以使用 loadAll 方法加载所有已定义的功能：

php

Feature::for($users)->loadAll();

更新值

当某个功能的值首次被解析时，底层驱动会将结果存储在存储中。这对于确保您的用户在请求之间获得一致的体验通常是必要的。但是，有时您可能希望手动更新功能的存储值。

为此，您可以使用 activate 和 deactivate 方法将功能切换为“开”或“关”：

php

use Laravel\Pennant\Feature;

// 为默认作用域激活功能...
Feature::activate('new-api');

// 为给定作用域停用功能...
Feature::for($user->team)->deactivate('billing-v2');

也可以通过在 activate 方法中提供第二个参数来手动设置功能的丰富值：

php

Feature::activate('purchase-button', 'seafoam-green');

要指示 Pennant 忘记某个功能的存储值，您可以使用 forget 方法。当再次检查该功能时，Pennant 将根据其功能定义解析该功能的值：

php

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

批量更新

要批量更新存储的功能值，您可以使用 activateForEveryone 和 deactivateForEveryone 方法。

例如，假设您现在对 new-api 功能的稳定性充满信心，并为您的结账流程确定了最佳的 'purchase-button' 颜色——您可以相应地更新所有用户的存储值：

php

use Laravel\Pennant\Feature;

Feature::activateForEveryone('new-api');

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

或者，您可以为所有用户停用该功能：

php

Feature::deactivateForEveryone('new-api');

NOTE

这只会更新已由 Pennant 存储驱动存储的已解析功能值。您还需要更新应用程序中的功能定义。

清除功能

有时，从存储中清除整个功能可能很有用。如果您已从应用程序中移除了该功能，或者您对功能定义进行了希望向所有用户推出的调整，这通常是必要的。

您可以使用 purge 方法删除某个功能的所有存储值：

php

// 清除单个功能...
Feature::purge('new-api');

// 清除多个功能...
Feature::purge(['new-api', 'purchase-button']);

如果您想从存储中清除_所有_功能，您可以调用不带任何参数的 purge 方法：

php

Feature::purge();

由于作为应用程序部署管道的一部分清除功能可能很有用，Pennant 包含一个 pennant:purge Artisan 命令，该命令将从存储中清除提供的功能：

shell

php artisan pennant:purge new-api

php artisan pennant:purge new-api purchase-button

也可以清除_除了_给定功能列表中的功能之外的所有功能。例如，假设您想清除所有功能，但保留 “new-api” 和 “purchase-button” 功能的值在存储中。为此，您可以将这些功能名称传递给 --except 选项：

shell

php artisan pennant:purge --except=new-api --except=purchase-button

为方便起见，pennant:purge 命令还支持 --except-registered 标志。此标志指示除了在服务提供者中显式注册的功能之外的所有功能都应该被清除：

shell

php artisan pennant:purge --except-registered

测试

测试与特性标志交互的代码时，在测试中控制特性标志返回值的最简单方法是简单地重新定义该功能。例如，假设您在应用程序的某个服务提供者中定义了以下功能：

php

use Illuminate\Support\Arr;
use Laravel\Pennant\Feature;

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

要在您的测试中修改功能的返回值，您可以在测试开始时重新定义该功能。即使 Arr::random() 实现仍然存在于服务提供者中，以下测试也将始终通过：

PestPHPUnit

php

use Laravel\Pennant\Feature;

test('它可以控制功能值', function () {
    Feature::define('purchase-button', 'seafoam-green');

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

php

use Laravel\Pennant\Feature;

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

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

相同的方法也可以用于基于类的功能：

PestPHPUnit

php

use Laravel\Pennant\Feature;

test('它可以控制功能值', function () {
    Feature::define(NewApi::class, true);

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

php

use App\Features\NewApi;
use Laravel\Pennant\Feature;

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

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

如果您的功能返回一个 Lottery 实例，有几个有用的测试辅助函数可用。

存储配置

您可以通过在应用程序的 phpunit.xml 文件中定义 PENNANT_STORE 环境变量来配置 Pennant 在测试期间将使用的存储：

xml

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

添加自定义 Pennant 驱动

实现驱动

如果 Pennant 现有的存储驱动都不符合您应用程序的需求，您可以编写自己的存储驱动。您的自定义驱动应该实现 Laravel\Pennant\Contracts\Driver 接口：

php

<?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 {}
}

现在，我们只需要使用 Redis 连接来实现这些方法中的每一个。关于如何实现这些方法的示例，请查看 Pennant 源代码中的 Laravel\Pennant\Drivers\DatabaseDriver。

NOTE

Laravel 没有附带一个目录来包含您的扩展。您可以自由地将它们放在任何您喜欢的位置。在此示例中，我们创建了一个 Extensions 目录来存放 RedisFeatureDriver。

注册驱动

一旦您的驱动实现好了，您就可以准备将其注册到 Laravel 中。要向 Pennant 添加额外的驱动，您可以使用 Feature Facade 提供的 extend 方法。您应该在您的某个应用程序的服务提供者的 boot 方法中调用 extend 方法：

php

<?php

namespace App\Providers;

use App\Extensions\RedisFeatureDriver;
use Illuminate\Contracts\Foundation\Application;
use Illuminate\Support\ServiceProvider;
use Laravel\Pennant\Feature;

class AppServiceProvider extends ServiceProvider
{
    /**
     * 注册任何应用程序服务。
     */
    public function register(): void
    {
        // ...
    }

    /**
     * 引导任何应用程序服务。
     */
    public function boot(): void
    {
        Feature::extend('redis', function (Application $app) {
            return new RedisFeatureDriver($app->make('redis'), $app->make('events'), []);
        });
    }
}

一旦驱动被注册，您就可以在应用程序的 config/pennant.php 配置文件中使用 redis 驱动：

php

'stores' => [

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

    // ...

],

在外部定义功能

如果您的驱动是围绕第三方特性标志平台的包装器，您很可能在平台上定义功能，而不是使用 Pennant 的 Feature::define 方法。如果是这种情况，您的自定义驱动还应实现 Laravel\Pennant\Contracts\DefinesFeaturesExternally 接口：

php

<?php

namespace App\Extensions;

use Laravel\Pennant\Contracts\Driver;
use Laravel\Pennant\Contracts\DefinesFeaturesExternally;

class FeatureFlagServiceDriver implements Driver, DefinesFeaturesExternally
{
    /**
     * 获取为给定作用域定义的功能。
     */
    public function definedFeaturesForScope(mixed $scope): array {}

    /* ... */
}

definedFeaturesForScope 方法应返回为给定作用域定义的功能名称列表。

事件

Pennant 会分发各种事件，这些事件在跟踪整个应用程序的特性标志时可能很有用。

`Laravel\Pennant\Events\FeatureRetrieved`

每当检查功能时，就会分发此事件。此事件可能有助于创建和跟踪整个应用程序中特性标志使用情况的指标。

`Laravel\Pennant\Events\FeatureResolved`

当某个特定作用域的功能值首次被解析时，会分发此事件。

`Laravel\Pennant\Events\UnknownFeatureResolved`

当某个特定作用域的未知功能首次被解析时，会分发此事件。如果您打算移除一个特性标志，但无意中在整个应用程序中留下了零散的引用，监听此事件可能会很有用：

php

<?php

namespace App\Providers;

use Illuminate\Support\ServiceProvider;
use Illuminate\Support\Facades\Event;
use Illuminate\Support\Facades\Log;
use Laravel\Pennant\Events\UnknownFeatureResolved;

class AppServiceProvider extends ServiceProvider
{
    /**
     * 引导任何应用程序服务。
     */
    public function boot(): void
    {
        Event::listen(function (UnknownFeatureResolved $event) {
            Log::error("正在解析未知功能 [{$event->feature}]。");
        });
    }
}

`Laravel\Pennant\Events\DynamicallyRegisteringFeatureClass`

当在请求期间首次动态检查基于类的功能时，会分发此事件。

`Laravel\Pennant\Events\UnexpectedNullScopeEncountered`

当将 null 作用域传递给一个不支持 null 的功能定义时，会分发此事件。

这种情况会被优雅地处理，并且该功能将返回 false。但是，如果您想选择退出此功能的默认优雅行为，您可以在应用程序的 AppServiceProvider 的 boot 方法中为此事件注册一个监听器：

php

use Illuminate\Support\Facades\Log;
use Laravel\Pennant\Events\UnexpectedNullScopeEncountered;

/**
 * 引导任何应用程序服务。
 */
public function boot(): void
{
    Event::listen(UnexpectedNullScopeEncountered::class, fn () => abort(500));
}

`Laravel\Pennant\Events\FeatureUpdated`

当为某个作用域更新功能时，通常会通过调用 activate 或 deactivate 来分发此事件。

`Laravel\Pennant\Events\FeatureUpdatedForAllScopes`

当为所有作用域更新功能时，通常会通过调用 activateForEveryone 或 deactivateForEveryone 来分发此事件。

`Laravel\Pennant\Events\FeatureDeleted`

当为某个作用域删除功能时，通常会通过调用 forget 来分发此事件。

`Laravel\Pennant\Events\FeaturesPurged`

当清除特定功能时，会分发此事件。

`Laravel\Pennant\Events\AllFeaturesPurged`

当清除所有功能时，会分发此事件。

Laravel Pennant ​

简介 ​

安装 ​

配置 ​

定义功能 ​

基于类的功能 ​

自定义存储的功能名称 ​

检查功能 ​

检查基于类的功能 ​

条件执行 ​

HasFeatures Trait ​

Blade 指令 ​

中间件 ​

自定义响应 ​

拦截功能检查 ​

内存缓存 ​

作用域 ​

指定作用域 ​

默认作用域 ​

可空作用域 ​

识别作用域 ​

序列化作用域 ​

丰富的功能值 ​

检索多个功能 ​

预加载 ​

更新值 ​

批量更新 ​

清除功能 ​

测试 ​

存储配置 ​

添加自定义 Pennant 驱动 ​

实现驱动 ​

注册驱动 ​

在外部定义功能 ​

事件 ​

Laravel\Pennant\Events\FeatureRetrieved ​

Laravel\Pennant\Events\FeatureResolved ​

Laravel\Pennant\Events\UnknownFeatureResolved ​

Laravel\Pennant\Events\DynamicallyRegisteringFeatureClass ​

Laravel\Pennant\Events\UnexpectedNullScopeEncountered ​

Laravel\Pennant\Events\FeatureUpdated ​

Laravel\Pennant\Events\FeatureUpdatedForAllScopes ​

Laravel\Pennant\Events\FeatureDeleted ​

Laravel\Pennant\Events\FeaturesPurged ​

Laravel\Pennant\Events\AllFeaturesPurged ​

Laravel Pennant

简介

安装

配置

定义功能

基于类的功能

自定义存储的功能名称

检查功能

检查基于类的功能

条件执行

`HasFeatures` Trait

Blade 指令

中间件

自定义响应

拦截功能检查

内存缓存

作用域

指定作用域

默认作用域

可空作用域

识别作用域

序列化作用域

丰富的功能值

检索多个功能

预加载

更新值

批量更新

清除功能

测试

存储配置

添加自定义 Pennant 驱动

实现驱动

注册驱动

在外部定义功能

事件

`Laravel\Pennant\Events\FeatureRetrieved`

`Laravel\Pennant\Events\FeatureResolved`

`Laravel\Pennant\Events\UnknownFeatureResolved`

`Laravel\Pennant\Events\DynamicallyRegisteringFeatureClass`

`Laravel\Pennant\Events\UnexpectedNullScopeEncountered`

`Laravel\Pennant\Events\FeatureUpdated`

`Laravel\Pennant\Events\FeatureUpdatedForAllScopes`

`Laravel\Pennant\Events\FeatureDeleted`

`Laravel\Pennant\Events\FeaturesPurged`

`Laravel\Pennant\Events\AllFeaturesPurged`