laravelphp 中文文档

介绍

Laravel Pennant 是一个简单轻量的特性标志包，没有臃肿。特性标志使你可以有信心地逐步推出新的应用程序功能，测试新的界面设计，支持基干开发策略等等。

安装

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

  2. composer require laravel/pennant

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

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

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

  2. php artisan migrate

配置

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

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

定义特性

要定义特性，你可以使用 php Feature 门面提供的 php define 方法。你需要为该特性提供一个名称以及一个闭包，用于解析该特性的初始值。

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

  2. <?php
  4. namespace App\Providers;
  6. use App\Models\User;
  8. use Illuminate\Support\Lottery;
  10. use Illuminate\Support\ServiceProvider;
  12. use Laravel\Pennant\Feature;
  14. class AppServiceProvider extends ServiceProvider
  16. {
  18.     /**
  20.      * Bootstrap any application services.
  22.      */
  24.     public function boot(): void
  26.     {
  28.         Feature::define('new-api', fn (User $user) => match (true) {
  30.             $user->isInternalTeamMember() => true,
  32.             $user->isHighTrafficCustomer() => false,
  34.  default => Lottery::odds(1 / 100),
  36.         });
  38.     }
  40. }

正如你所看到的，我们对我们的特性有以下规则：

所有内部团队成员应使用新 API。

任何高流量客户不应使用新 API。

否则，该特性应在具有 1/100 概率激活的用户中随机分配。

首次检查给定用户的 php new-api特性时，存储驱动程序将存储闭包的结果。下一次针对相同用户检查特性时，将从存储中检索该值，不会调用闭包。

为方便起见，如果特性定义仅返回一个 Lottery，你可以完全省略闭包：

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

基于类的特性

Pennant 还允许你定义基于类的特性。不像基于闭包的特性定义，不需要在服务提供者中注册基于类的特性。为了创建一个基于类的特性，你可以调用 php pennant:feature Artisan 命令。默认情况下，特性类将被放置在你的应用程序的 php app/Features 目录中：

  2. php artisan pennant:feature NewApi

在编写特性类时，你只需要定义一个 php resolve 方法，用于为给定的范围解析特性的初始值。同样，范围通常是当前经过身份验证的用户：

  2. <?php
  4. namespace App\Features;
  6. use Illuminate\Support\Lottery;
  8. class NewApi
  10. {
  12.     /**
  14.      * 解析特性的初始值.
  16.      */
  18.     public function resolve(User $user): mixed
  20.     {
  22.         return match (true) {
  24.             $user->isInternalTeamMember() => true,
  26.             $user->isHighTrafficCustomer() => false,
  28.  default => Lottery::odds(1 / 100),
  30.         };
  32.     }
  34. }

注 特性类是通过容器,解析的，因此在需要时可以在特性类的构造函数中注入依赖项。

检查特性

要确定一个特性是否处于活动状态，你可以在 php Feature 门面上使用 php active 方法。默认情况下，特性针对当前已认证的用户进行检查：

  2. <?php
  4. namespace App\Http\Controllers;
  6. use Illuminate\Http\Request;
  8. use Illuminate\Http\Response;
  10. use Laravel\Pennant\Feature;
  12. class PodcastController
  14. {
  16.     /**
  18.      * 显示资源的列表.
  20.      */
  22.     public function index(Request $request): Response
  24.     {
  26.         return Feature::active('new-api')
  28.                 ? $this->resolveNewApiResponse($request)
  30.                 : $this->resolveLegacyApiResponse($request);
  32.     }
  34.     // ...
  36. }

为了方便起见，如果一个特征定义只返回一个抽奖结果，你可以完全省略闭包:

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

基于类的特征

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

  2. php artisan pennant:feature NewApi

编写特征类时，你只需要定义一个 php resolve 方法，该方法将被调用以解析给定作用域的特征的初始值。同样，该作用域通常是当前已验证的用户。:

  2. <?php
  4. namespace App\Features;
  6. use Illuminate\Support\Lottery;
  8. class NewApi
  10. {
  12.     /**
  14.      * 解析特征的初始值.
  16.      */
  18.     public function resolve(User $user): mixed
  20.     {
  22.         return match (true) {
  24.             $user->isInternalTeamMember() => true,
  26.             $user->isHighTrafficCustomer() => false,
  28.  default => Lottery::odds(1 / 100),
  30.         };
  32.     }
  34. }

注意 特征类通过 容器, 解析，因此在需要时，你可以将依赖项注入到特征类的构造函数中.

Checking Features

要确定特征是否处于活动状态，你可以在 Feature 门面上使用 php active 方法。默认情况下，特征将针对当前已验证的用户进行检查。:

  2. <?php
  4. namespace App\Http\Controllers;
  6. use Illuminate\Http\Request;
  8. use Illuminate\Http\Response;
  10. use Laravel\Pennant\Feature;
  12. class PodcastController
  14. {
  16.     /**
  18.      *显示资源的列表.
  20.      */
  22.     public function index(Request $request): Response
  24.     {
  26.         return Feature::active('new-api')
  28.                 ? $this->resolveNewApiResponse($request)
  30.                 : $this->resolveLegacyApiResponse($request);
  32.     }
  34.     // ...
  36. }

虽然默认情况下特性针对当前已认证的用户进行检查，但你可以轻松地针对其他用户或范围检查特性。为此，使用 php Feature 门面提供的 php for 方法：

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

Pennant 还提供了一些额外的方便方法，在确定特性是否活动或不活动时可能非常有用：

  2. //确定所有给定的特性是否都活动...
  4. Feature::allAreActive(['new-api', 'site-redesign']);
  6. // 确定任何给定的特性是否都活动...
  8. Feature::someAreActive(['new-api', 'site-redesign']);
  10. // 确定特性是否处于非活动状态...
  12. Feature::inactive('new-api');
  14. // 确定所有给定的特性是否都处于非活动状态...
  16. Feature::allAreInactive(['new-api', 'site-redesign']);
  18. // 确定任何给定的特性是否都处于非活动状态...
  20. Feature::someAreInactive(['new-api', 'site-redesign']);

注

当在 HTTP 上下文之外使用 Pennant（例如在 Artisan 命令或排队作业中）时，你通常应明确指定特性的作用域。或者，你可以定义一个默认作用域，该作用域考虑到已认证的 HTTP 上下文和未经身份验证的上下文。

检查基于类的特性
对于基于类的特性，应该在检查特性时提供类名：

  2. <?php
  4. namespace App\Http\Controllers;
  6. use App\Features\NewApi;
  8. use Illuminate\Http\Request;
  10. use Illuminate\Http\Response;
  12. use Laravel\Pennant\Feature;
  14. class PodcastController
  16. {
  18.     /**
  20.      * 显示资源的列表.
  22.      */
  24.     public function index(Request $request): Response
  26.     {
  28.         return Feature::active(NewApi::class)
  30.                 ? $this->resolveNewApiResponse($request)
  32.                 : $this->resolveLegacyApiResponse($request);
  34.     }
  36.     // ...
  38. }

条件执行

php when 方法可用于在特性激活时流畅地执行给定的闭包。此外，可以提供第二个闭包，如果特性未激活，则将执行它：

  1. <?php
  3. namespace App\Http\Controllers;
  5. use App\Features\NewApi;
  7. use Illuminate\Http\Request;
  9. use Illuminate\Http\Response;
  11. use Laravel\Pennant\Feature;
  13. class PodcastController
  15. {
  17.     /**
  19.      * 显示资源的列表.
  21.      */
  23.     public function index(Request $request): Response
  25.     {
  27.         return Feature::when(NewApi::class,
  29.             fn () => $this->resolveNewApiResponse($request),
  31.             fn () => $this->resolveLegacyApiResponse($request),
  33.         );
  35.     }
  37.     // ...
  39. }

php unless 方法是 php when 方法的相反，如果特性未激活，则执行第一个闭包：

  1. return Feature::unless(NewApi::class,
  3.     fn () => $this->resolveLegacyApiResponse($request),
  5.     fn () => $this->resolveNewApiResponse($request),
  7. );

HasFeatures Trait

Pennant 的 php HasFeatures Trait 可以添加到你的应用的 php User 模型（或其他具有特性的模型）中，以提供一种流畅、方便的方式从模型直接检查特性：

  2. <?php
  4. namespace App\Models;
  6. use Illuminate\Foundation\Auth\User as Authenticatable;
  8. use Laravel\Pennant\Concerns\HasFeatures;
  10. class User extends Authenticatable
  12. {
  14.     use HasFeatures;
  16.     // ...
  18. }

一旦将 HasFeatures Trait 添加到你的模型中，你可以通过调用 php features 方法轻松检查特性：

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

当然，php features 方法提供了许多其他方便的方法来与特性交互：

  2. // 值...
  4. $value = $user->features()->value('purchase-button')
  6. $values = $user->features()->values(['new-api', 'purchase-button']);
  8. // 状态...
  10. $user->features()->active('new-api');
  12. $user->features()->allAreActive(['new-api', 'server-api']);
  14. $user->features()->someAreActive(['new-api', 'server-api']);
  16. $user->features()->inactive('new-api');
  18. $user->features()->allAreInactive(['new-api', 'server-api']);
  20. $user->features()->someAreInactive(['new-api', 'server-api']);
  22. // 条件执行...
  24. $user->features()->when('new-api',
  26.     fn () => /* ... */,
  28.     fn () => /* ... */,
  30. );
  32. $user->features()->unless('new-api',
  34.     fn () => /* ... */,
  36.     fn () => /* ... */,
  38. );

Blade 指令

为了使在 Blade 中检查特性的体验更加流畅，Pennant提供了一个 php @feature 指令：

  2. @feature('site-redesign')
  4. <!-- 'site-redesign' 活跃中 -->
  6. @else
  8. <!-- 'site-redesign' 不活跃-->
  10. @endfeature

中间件

Pennant 还包括一个中间件，它可以在路由调用之前验证当前认证用户是否有访问功能的权限。首先，你应该将 php EnsureFeaturesAreActive 中间件的别名添加到你的应用程序的 php app/Http/Kernel.php 文件中：

  2. use Laravel\Pennant\Middleware\EnsureFeaturesAreActive;
  4. protected $middlewareAliases = [
  6.     // ...
  8.  'features' => EnsureFeaturesAreActive::class,
  10. ];

接下来，你可以将中间件分配给一个路由并指定需要访问该路由的功能。如果当前认证用户的任何指定功能未激活，则路由将返回 php 400 Bad Request HTTP 响应。可以使用逗号分隔的列表指定多个功能：

  2. Route::get('/api/servers', function () {
  4.     // ...
  6. })->middleware(['features:new-api,servers-api']);

自定义响应
如果你希望在未激活列表中的任何一个功能时自定义中间件返回的响应，可以使用 php EnsureFeaturesAreActive 中间件提供的 php whenInactive 方法。通常，这个方法应该在应用程序的服务提供者的 boot 方法中调用：

  2. use Illuminate\Http\Request;
  4. use Illuminate\Http\Response;
  6. use Laravel\Pennant\Middleware\EnsureFeaturesAreActive;
  8. /**
  10.  * 加载服务.
  12.  */
  14. public function boot(): void
  16. {
  18.     EnsureFeaturesAreActive::whenInactive(
  20.         function (Request $request, array $features) {
  22.             return new Response(status: 403);
  24.         }
  26.     );
  28.     // ...
  30. }

内存缓存

当检查特性时，Pennant 将创建一个内存缓存以存储结果。如果你使用的是 php database 驱动程序，则在单个请求中重新检查相同的功能标志将不会触发额外的数据库查询。这也确保了该功能在请求的持续时间内具有一致的结果。

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

  1. Feature::flushCache();

作用域

指定作用域

如前所述，特性通常会针对当前已验证的用户进行检查。但这可能并不总是适合你的需求。因此，你可以通过 php Feature 门面的 php for 方法来指定要针对哪个作用域检查给定的特性：

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

当然，特性作用域不限于“用户”。假设你构建了一个新的结算体验，你要将其推出给整个团队而不是单个用户。也许你希望年龄最大的团队的推出速度比年轻的团队慢。你的特性解析闭包可能如下所示：

  2. use App\Models\Team;
  4. use Carbon\Carbon;
  6. use Illuminate\Support\Lottery;
  8. use Laravel\Pennant\Feature;
  10. Feature::define('billing-v2', function (Team $team) {
  12.     if ($team->created_at->isAfter(new Carbon('1st Jan, 2023'))) {
  14.         return true;
  16.     }
  18.     if ($team->created_at->isAfter(new Carbon('1st Jan, 2019'))) {
  20.         return Lottery::odds(1 / 100);
  22.     }
  24.     return Lottery::odds(1 / 1000);
  26. });

你会注意到，我们定义的闭包不需要 php User，而是需要一个 php Team 模型。要确定该特性是否对用户的团队可用，你应该将团队传递给 php Feature 门面提供的 php for 方法：

  2. if (Feature::for($user->team)->active('billing-v2')) {
  4.     return redirect()->to('/billing/v2');
  6. }
  8. // ...

默认作用域

还可以自定义 Pennant 用于检查特性的默认作用域。例如，你可能希望所有特性都针对当前认证用户的团队进行检查，而不是针对用户。你可以在应用程序的服务提供程序中指定此作用域。通常，应该在一个应用程序的服务提供程序中完成这个过程:

  2. <?php
  4. namespace App\Providers;
  6. use Illuminate\Support\Facades\Auth;
  8. use Illuminate\Support\ServiceProvider;
  10. use Laravel\Pennant\Feature;
  12. class AppServiceProvider extends ServiceProvider
  14. {
  16.     /**
  18.      * 加载程序服务.
  20.      */
  22.     public function boot(): void
  24.     {
  26.         Feature::resolveScopeUsing(fn ($driver) => Auth::user()?->team);
  28.         // ...
  30.     }
  32. }

如果没有通过 php for 方法显式提供作用域，则特性检查将使用当前认证用户的团队作为默认作用域：

  2. Feature::active('billing-v2');
  4. // 目前等价于...
  6. Feature::for($user->team)->active('billing-v2');

空作用域

如果你检查特性时提供的作用域范围为 php null，且特性定义中不支持 php null（即不是 nullable type 或者没有在 union type 中包含php null），那么 Pennant 将自动返回 php false 作为特性的结果值。

因此，如果你传递给特性的作用域可能为 null 并且你想要特性值的解析器被调用，你应该在特性定义逻辑中处理 php null 范围值。在一个 Artisan 命令、排队作业或未经身份验证的路由中检查特性可能会出现 php null 作用域。因为在这些情况下通常没有经过身份验证的用户，所以默认的作用域将为 php null。

如果你不总是明确指定特性作用域，则应确保范围类型为”nullable”，并在特性定义逻辑中处理 php null 范围值:

  2. use App\Models\User;
  4. use Illuminate\Support\Lottery;
  6. use Laravel\Pennant\Feature;
  8. Feature::define('new-api', fn (User $user) => match (true) {// [tl! remove]
  10. Feature::define('new-api', fn (User|null $user) => match (true) {// [tl! add]
  12.     $user === null => true,// [tl! add]
  14.     $user->isInternalTeamMember() => true,
  16.     $user->isHighTrafficCustomer() => false,
  18.  default => Lottery::odds(1 / 100),
  20. });

标识作用域

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

因此，Pennant 允许你通过在应用程序中用作 Pennant 作用域的对象上实现 php FeatureScopeable 协议来格式化存储范围值。

例如，假设你在单个应用程序中使用了两个不同的特性驱动程序：内置 php database 驱动程序和第三方的“Flag Rocket”驱动程序。 “Flag Rocket”驱动程序不知道如何正确地存储 Eloquent 模型。相反，它需要一个php FlagRocketUser 实例。通过实现 php FeatureScopeable 协议中的 php toFeatureIdentifier 方法，我们可以自定义提供给应用程序中每个驱动程序的可存储范围值：

  2. <?php
  4. namespace App\Models;
  6. use FlagRocket\FlagRocketUser;
  8. use Illuminate\Database\Eloquent\Model;
  10. use Laravel\Pennant\Contracts\FeatureScopeable;
  12. class User extends Model implements FeatureScopeable
  14. {
  16.     /**
  18.      * 将对象强制转换为给定驱动程序的功能范围标识符.
  20.      */
  22.     public function toFeatureIdentifier(string $driver): mixed
  24.     {
  26.         return match($driver) {
  28.  'database' => $this,
  30.  'flag-rocket' => FlagRocketUser::fromId($this->flag_rocket_id),
  32.         };
  34.     }
  36. }

丰富的特征值

到目前为止，我们主要展示了特性的二进制状态，即它们是「活动的」还是「非活动的」，但是 Pennant 也允许你存储丰富的值。

例如，假设你正在测试应用程序的「立即购买」按钮的三种新颜色。你可以从特性定义中返回一个字符串，而不是 php true 或 php false：

  2. use Illuminate\Support\Arr;
  4. use Laravel\Pennant\Feature;
  6. Feature::define('purchase-button', fn (User $user) => Arr::random([
  8.  'blue-sapphire',
  10.  'seafoam-green',
  12.  'tart-orange',
  14. ]));

你可以使用 php value 方法检索 php purchase-button 特性的值：

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

Pennant 提供的 Blade 指令也使得根据特性的当前值条件性地呈现内容变得容易：

  2. @feature('purchase-button', 'blue-sapphire')
  4. <!-- 'blue-sapphire' is active -->
  6. @elsefeature('purchase-button', 'seafoam-green')
  8. <!-- 'seafoam-green' is active -->
  10. @elsefeature('purchase-button', 'tart-orange')
  12. <!-- 'tart-orange' is active -->
  14. @endfeature

使用丰富值时，重要的是要知道，只要特性具有除 php false 以外的任何值，它就被视为「活动」。

在调用条件 php when 方法时，特性的丰富值将提供给第一个闭包：

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

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

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

获取多个特性

php values 方法允许检索给定作用域的多个特征：

  2. Feature::values(['billing-v2', 'purchase-button']);
  4. // [
  6. // 'billing-v2' => false,
  8. // 'purchase-button' => 'blue-sapphire',
  10. // ]

或者，你可以使用 php all 方法检索给定范围内所有已定义功能的值：

  2. Feature::all();
  4. // [
  6. // 'billing-v2' => false,
  8. // 'purchase-button' => 'blue-sapphire',
  10. // 'site-redesign' => true,
  12. // ]

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

如果你想确保使用 php all 方法时始终包括功能类，你可以使用Pennant的功能发现功能。要开始使用，请在你的应用程序的任何服务提供程序之一中调用 php discover 方法：

  1. <?php
  3. namespace App\Providers;
  5. use Illuminate\Support\ServiceProvider;
  7. use Laravel\Pennant\Feature;
  9. class AppServiceProvider extends ServiceProvider
  11. {
  13.     /**
  15.      * Bootstrap any application services.
  17.      */
  19.     public function boot(): void
  21.     {
  23.         Feature::discover();
  25.         // ...
  27.     }
  29. }

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

  2. Feature::all();
  4. // [
  6. // 'App\Features\NewApi' => true,
  8. // 'billing-v2' => false,
  10. // 'purchase-button' => 'blue-sapphire',
  12. // 'site-redesign' => true,
  14. // ]

预加载

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

为了说明这一点，想象一下我们正在循环中检查功能是否处于活动状态：

  2. use Laravel\Pennant\Feature;
  4. foreach ($users as $user) {
  6.     if (Feature::for($user)->active('notifications-beta')) {
  8.         $user->notify(new RegistrationSuccess);
  10.     }
  12. }

假设我们正在使用数据库驱动程序，此代码将为循环中的每个用户执行数据库查询-执行潜在的数百个查询。但是，使用 Pennant 的 php load 方法，我们可以通过预加载一组用户或作用域的功能值来消除这种潜在的性能瓶颈：

  2. Feature::for($users)->load(['notifications-beta']);
  4. foreach ($users as $user) {
  6.     if (Feature::for($user)->active('notifications-beta')) {
  8.         $user->notify(new RegistrationSuccess);
  10.     }
  12. }

为了仅在尚未加载功能值时加载它们，你可以使用 php loadMissing 方法：

  2. Feature::for($users)->loadMissing([
  4.  'new-api',
  6.  'purchase-button',
  8.  'notifications-beta',
  10. ]);

更新值

当首次解析功能的值时，底层驱动程序将把结果存储在存储中。这通常是为了确保在请求之间为你的用户提供一致的体验。但是，有时你可能想手动更新功能的存储值。

为了实现这一点，你可以使用 php activate 和 php deactivate 方法来切换功能的 「打开」或「关闭」状态：

  2. use Laravel\Pennant\Feature;
  4. // 激活默认作用域的功能...
  6. Feature::activate('new-api');
  8. // 在给定的范围中停用功能...
  10. Feature::for($user->team)->deactivate('billing-v2');

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

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

要指示 Pennant 忘记功能的存储值，你可以使用 php forget 方法。当再次检查功能时，Pennant 将从其功能定义中解析功能的值：

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

批量更新

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

例如，假设你现在对 php new-api 功能的稳定性有信心，并为结帐流程找到了最佳的「purchase-button」颜色-你可以相应地更新所有用户的存储值：

  2. use Laravel\Pennant\Feature;
  4. Feature::activateForEveryone('new-api');
  6. Feature::activateForEveryone('purchase-button', 'seafoam-green');

或者，你可以停用所有用户的该功能：

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

注意：这将仅更新已由 Pennant 存储驱动程序存储的已解析功能值。你还需要更新应用程序中的功能定义。

清除功能

有时，清除存储中的整个功能可以非常有用。如果你已从应用程序中删除了功能或已对功能的定义进行了调整，并希望将其部署到所有用户，则通常需要这样做。

你可以使用 php purge 方法删除功能的所有存储值：

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

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

  2. Feature::purge();

由于在应用程序的部署流程中清除功能可能非常有用，因此 Pennant 包括一个php pennant:purge Artisan命令：

  2. php artisan pennant:purge new-api
  4. php artisan pennant:purge new-api purchase-button

测试

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

  2. use Illuminate\Support\Arr;
  4. use Laravel\Pennant\Feature;
  6. Feature::define('purchase-button', fn () => Arr::random([
  8.  'blue-sapphire',
  10.  'seafoam-green',
  12.  'tart-orange',
  14. ]));

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

  2. use Laravel\Pennant\Feature;
  4. public function test_it_can_control_feature_values()
  6. {
  8.     Feature::define('purchase-button', 'seafoam-green');
  10.     $this->assertSame('seafoam-green', Feature::value('purchase-button'));
  12. }

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

  2. use App\Features\NewApi;
  4. use Laravel\Pennant\Feature;
  6. public function test_it_can_control_feature_values()
  8. {
  10.     Feature::define(NewApi::class, true);
  12.     $this->assertTrue(Feature::value(NewApi::class));
  14. }

如果你的功能返回一个 php Lottery 实例，那么有一些有用的测试辅助函数可用。

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

  2. <?xml version="1.0"  encoding="UTF-8"?>
  4. <phpunit colors="true">
  6.     <!-- ... -->
  8.     <php>
  10. <env name="PENNANT_STORE"  value="array"/>
  12.         <!-- ... -->
  14.     </php>
  16. </phpunit>

添加自定义Pennant驱动程序

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

  2. <?php
  4. namespace App\Extensions;
  6. use Laravel\Pennant\Contracts\Driver;
  8. class RedisFeatureDriver implements Driver
  10. {
  12.     public function define(string $feature, callable $resolver): void {}
  14.     public function defined(): array {}
  16.     public function getAll(array $features): array {}
  18.     public function get(string $feature, mixed $scope): mixed {}
  20.     public function set(string $feature, mixed $scope, mixed $value): void {}
  22.     public function setForAllScopes(string $feature, mixed $value): void {}
  24.     public function delete(string $feature, mixed $scope): void {}
  26.     public function purge(array|null $features): void {}
  28. }

现在，我们只需要使用 Redis 连接实现这些方法。可以在 Pennant 源代码中查看如何实现这些方法的示例。

注意

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

注册驱动
一旦你的驱动程序被实现，就可以将其注册到 Laravel 中。要向 Pennant 添加其他驱动程序，可以使用 php Feature 门面提供的 php extend 方法。应该在应用程序的 服务提供者 的 php boot 方法中调用 php extend 方法：

  2. <?php
  4. namespace App\Providers;
  6. use App\Extensions\RedisFeatureDriver;
  8. use Illuminate\Contracts\Foundation\Application;
  10. use Illuminate\Support\ServiceProvider;
  12. use Laravel\Pennant\Feature;
  14. class AppServiceProvider extends ServiceProvider
  16. {
  18.     /**
  20.      * 注册任何应用程序服务。
  22.      */
  24.     public function register(): void
  26.     {
  28.         // ...
  30.     }
  32.     /**
  34.      * 引导任何应用程序服务。
  36.      */
  38.     public function boot(): void
  40.     {
  42.         Feature::extend('redis', function (Application $app) {
  44.             return new RedisFeatureDriver($app->make('redis'), $app->make('events'), []);
  46.         });
  48.     }
  50. }

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

‘stores’ => [

‘redis’ => [

‘driver’ => ‘redis’,

‘connection’ => null,

  1.     ],
  3.     // ...
  5. ],

事件

Pennant 分发了各种事件，这些事件在跟踪应用程序中的特性标志时非常有用。

Laravel\Pennant\Events\RetrievingKnownFeature

该事件在请求特定作用域的已知特征值第一次被检索时被触发。此事件可用于创建和跟踪应用程序中使用的特征标记的度量标准。

Laravel\Pennant\Events\RetrievingUnknownFeature

当在请求特定作用域的情况下第一次检索未知特性时，将分派此事件。如果你打算从应用程序中删除功能标志，但可能在整个应用程序中留下了某些零散的引用，此事件可能会有用。你可能会发现有用的是监听此事件并在其发生时 php report 或抛出异常：

例如，你可能会发现在监听到此事件并出现此情况时，使用 php report 或引发异常会很有用：

  2. <?php
  4. namespace App\Providers;
  6. use Illuminate\Foundation\Support\Providers\EventServiceProvider as ServiceProvider;
  8. use Illuminate\Support\Facades\Event;
  10. use Laravel\Pennant\Events\RetrievingUnknownFeature;
  12. class EventServiceProvider extends ServiceProvider
  14. {
  16.     /**
  18.      * Register any other events for your application.
  20.      */
  22.     public function boot(): void
  24.     {
  26.         Event::listen(function (RetrievingUnknownFeature $event) {
  28.             report("Resolving unknown feature [{$event->feature}].");
  30.         });
  32.     }
  34. }

Laravel\Pennant\Events\DynamicallyDefiningFeature

当在请求期间首次动态检查基于类的特性时，将分派此事件。