README

使用ConfigCat云服务在您的Laravel应用程序中实现功能标志。

安装

您可以通过Composer安装此包

composer require pod-point/laravel-configcat

发布配置文件

接下来，您应该使用Artisan命令 vendor:publish 发布Laravel包配置文件。它将被放置在您的应用程序的配置目录中

php artisan vendor:publish --provider="PodPoint\ConfigCat\ConfigCatServiceProvider"

别忘了在刚发布的Laravel配置文件 config/configcat.php 中指定您的ConfigCat SDK key。

此包的Laravel配置包含合理的默认值。有关更多详细信息，请参阅config/configcat.php。

使用方法

外观和全局辅助函数

可以使用ConfigCat外观以及全局辅助函数来检索功能标志的实际值、文本或数字设置

use PodPoint\ConfigCat\Facades\ConfigCat;

$flag = ConfigCat::get('new_registration_flow');

$flag = configcat('new_registration_flow');

注意：您可以在ConfigCat上定义功能标志的实际值为bool(true)或bool(false)，但不仅限于此，它还可以是数字或文本设置。

如果功能标志未定义或发生错误，则默认返回bool(false)，但您可以指定一个默认值，仅当使用外观或全局辅助函数检索功能标志值时才指定此默认值

use PodPoint\ConfigCat\Facades\ConfigCat;

$flag = ConfigCat::get('new_registration_flow', true);

$flag = configcat('new_registration_flow', true);

您还可以从config/configcat.php文件中全局指定一个默认值。

⚠️ 仅支持boolean、string、integer或float默认值类型，因为这些是ConfigCat中可用的唯一设置类型。

验证规则

给定以下验证规则

Validator::make([
    'email' => 'taylor@laravel.com',
    'username' => 'taylor',
], [
    'email' => 'required_if_configcat:new_registration_flow,true',
    'username' => 'required_if_configcat:new_registration_flow,false',
]);

当功能标志开启时
- email将是一个必填字段
- username将是一个可选字段
当功能标志关闭、未定义、文本或数字设置时
- email将是一个可选字段
- username将是一个必填字段

HTTP中间件

只有当功能标志为真时，以下路由才可访问，否则将抛出404。

Router::get('/registration')->middleware('configcat.on:new_registration_flow');

反之亦然，如果功能标志为假，也将抛出404

Router::get('/sign-up')->middleware('configcat.off:new_registration_flow');

注意：未定义、文本或数字设置将被视为功能标志关闭。

Blade指令

只有当功能标志为真时，以下视图内容才会渲染

@configcat('new_registration_flow')
    New registration form
@endconfigcat

@unlessconfigcat('new_registration_flow')
    Old registration form
@endconfigcat

@configcat('new_registration_flow_1')
    Sign up
@elseconfigcat('new_registration_flow_2')
    Get started
@else
    Register
@endconfigcat

注意：未定义、文本或数字设置将被视为功能标志关闭。

高级使用

用户定位

如果您想使用ConfigCat的定位功能，则需要使用用户对象。

ConfigCat需要理解您的应用程序中对用户的表示。为此，您需要将您的用户转换为ConfigCat\User对象。这可以直接从config/configcat.php文件中完成。以下是一个示例

'user' => \PodPoint\ConfigCat\Support\DefaultUserTransformer::class,

它将使用合理的默认转换器

class DefaultUserTransformer
{
    public function __invoke(\Illuminate\Foundation\Auth\User $user)
    {
        return new \ConfigCat\User($user->getKey(), $user->email);
    }
}

您可以自由地创建自己的转换器类并替换它，但请记住它需要是一个带有__invoke()函数的callable。

注意：出于安全原因，所有针对用户的逻辑计算都在使用ConfigCat SDK的您的应用程序端执行。为了确定用户是否应启用功能标志，不会将任何用户详细信息从您的应用程序中导出。

一旦您定义了映射，您就可以在检查功能标志时显式使用您的用户的表示。

use App\Models\User;
use PodPoint\ConfigCat\Facades\ConfigCat;

$user = User::where('email', 'taylor@laravel.com')->firstOrFail();
ConfigCat::get('new_registration_flow', $default, $user);

这也适用于全局助手和Blade指令

configcat('new_registration_flow', $default, $user);

@configcat('new_registration_flow', $user)
    New registration form
@endconfigcat

注意：如果您已定义了用户映射但没有显式使用特定用户来检查标志，我们将自动尝试使用任何已登录的用户，以便方便。

缓存与日志

此包支持Laravel的原生缓存和日志功能，以缓存来自ConfigCat CDN的功能标志值以及记录解决功能标志时的任何信息。我们已设置了一些合理的默认值，但可以配置不同级别的缓存和日志。

有关更多信息，请参阅config/configcat.php。

测试支持：模拟、伪造和覆盖

内存中测试

在编写单元或功能测试时，您可能需要能够完全模拟或伪造此包，以便在您的应用程序中测试各种行为。所有这些都可以通过强大的Facade来实现。

模拟

use PodPoint\ConfigCat\Facades\ConfigCat;

ConfigCat::shouldReceive('get')
    ->once()
    ->with('new_registration_flow')
    ->andReturn(true);

有关更多信息，请参阅https://laravel.net.cn/docs/mocking#mocking-facades。

伪造

伪造将阻止包真正尝试连接到ConfigCat的CDN

use PodPoint\ConfigCat\Facades\ConfigCat;

// you can fake it
ConfigCat::fake();
// optionally setup some predefined feature flags for your test
ConfigCat::fake(['new_registration_flow' => true]);

端到端测试

当在浏览器中运行测试时，该浏览器不共享应用程序的同一实例，使用模拟或伪造不适用。这就是我们为什么提供一些通过ConfigCat SDK提供的覆盖，这将使客户端仅限于本地主机，并使用本地生成的json文件来读取要测试的系统中的功能标志。

首先，您需要确保从config/configcat.php启用overrides。如果您愿意，还可以调整json文件的文件路径。当使用覆盖时，该文件将自动为您创建。

与ConfigCat::fake()类似，您可以定义一些预定义的功能标志，它们将被保存到一个json文件中

use PodPoint\ConfigCat\Facades\ConfigCat;

ConfigCat::override(['new_registration_flow' => true]);

测试

使用以下命令运行测试

composer test

变更日志

有关最近更改的更多信息，请参阅我们的Releases。

贡献

有关详细信息，请参阅CONTRIBUTING。

致谢

许可证

MIT许可证（MIT）。有关更多信息，请参阅许可证文件。

旅行不应该破坏地球 🌍

用❤️制作于 Pod Point

pod-point / laravel-configcat

维护者

详细信息