README

为 Symfony 5.4+、6.4+ 和 7.0+ 应用程序提供的 Unleash 包。

这提供了一个使用 Gitlab 特性标志功能 实现特性标志的简单方法。

本实现符合官方 Unleash 标准。

受 minds/unleash-client-php 和 mikefrancis/laravel-unleash 的启发。

安装

composer require stogon/unleash-bundle

配置

完整的配置示例

# config/packages/unleash.yaml
unleash:
    # The full URL to your unleash-server instance (must end with a slash).
    # Example with the "feature_flags" feature from Gitlab.com : https://gitlab.com/api/v4/feature_flags/unleash/<project_id>/
    api_url: 'https://gitlab.com/api/v4/feature_flags/unleash/<project_id>/'

    # Authorization key if needed
    auth_token: '<auth>'

    # Instance ID of your unleash application.
    # Example : VPQgqIdAxQyXY96d6oWj
    instance_id: '<some ID>'

    # Unleash application name.
    # For Gitlab feature flags, it can be set to the environment name.
    # default: '%kernel.environment%'
    environment: '%kernel.environment%'

    cache:
        # Enable caching of features fetched from Unleash server.
        # default: true
        enabled: true
        # Service ID to use for caching (must be a cache pool)
        # default: '%unleach.cache.service%' (which resolve to '@cache.unleash.strategies' service)
        service: '@cache.app'
        # The period of time from the present after which the item MUST be considered expired in the cache in seconds
        # default: 15
        ttl: 15

用法

要使用客户端，只需将 Stogon\UnleashBundle\UnleashInterface 注入到您的服务中，并像这样使用它

<?php

namespace App\Controller;

use Stogon\UnleashBundle\UnleashInterface;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Annotation\Route;

class HomeController extends AbstractController
{
    #[Route('/', name: 'homepage')]
    public function index(UnleashInterface $unleash): Response
    {
        if ($unleash->isFeatureEnabled('my_awesome_feature')) {
            // do something awesome !
        }

        if ($unleash->isFeatureDisabled('my_other_feature')) {
            // do something else
        }

        return $this->render('home/index.html.twig');
    }
}

Twig

该包还提供了 Twig 函数来检查特性是否对当前用户启用/禁用

{# Check if a feature is enabled for current user #}
{%- if is_feature_enabled('my_awesome_feature') -%}
    <div class="alert alert-success" role="alert">
        The <code>my_awesome_feature</code> feature is enabled for current user !
    </div>
{%- else -%}
    <div class="alert alert-warning" role="alert">
        The <code>my_awesome_feature</code> feature is disabled for current user !
    </div>
{%- endif -%}

{# Check if a feature is disabled for current user #}
{%- if is_feature_disabled('my_awesome_feature') -%}
    <div class="alert alert-success" role="alert">
        The <code>my_awesome_feature</code> feature is disabled for current user !
    </div>
{%- else -%}
    <div class="alert alert-warning" role="alert">
        The <code>my_awesome_feature</code> feature is enabled for current user !
    </div>
{%- endif -%}

控制台

此包附带一些控制台命令

策略

可用策略

有关更多信息，请参阅 https://docs.getunleash.io/docs/activation_strategy

添加自定义策略

如果现有策略无法满足您的需求，您可以使用自己的逻辑实现自定义策略。

首先，您需要创建一个实现了 Stogon\UnleashBundle\Strategy\StrategyInterface 的类

<?php

namespace App\Unleash\Strategy;

use Stogon\UnleashBundle\Strategy\StrategyInterface;

class MyCustomStrategy implements StrategyInterface
{
    public function isEnabled(array $parameters = [], array $context = [], ...$args): bool
    {
        // TODO: Implement your custom logic here.

        return false;
    }
}

然后，您需要使用 unleash.strategy 标签标记您的自定义策略，并提供一个 activation_name。

services:
    App\Unleash\Strategy\MyCustomStrategy:
        tags:
            - { name: unleash.strategy, activation_name: my_custom_activation_strategy }

activation_name 必须与您的 Unleash 策略的 strategy.name 值匹配！请参阅 https://docs.getunleash.io/docs/activation_strategy

覆盖现有策略

您可以通过将标签的 activation_name 设置为与这里使用的相同 策略名称 来覆盖现有策略。

示例

services:
    App\Unleash\Strategy\MyCustomStrategy:
        tags:
            - { name: unleash.strategy, activation_name: userWithId }

向策略添加额外上下文

如果您想向传递给解析策略的上下文中添加额外数据（Stogon\UnleashBundle\Strategy\StrategyInterface::isEnabled 方法的 $context 参数），您可以实现一个事件监听器/订阅者来响应 Stogon\UnleashBundle\Event\UnleashContextEvent 事件。

示例

<?php

namespace App\EventSubscriber;

use Stogon\UnleashBundle\Event\UnleashContextEvent;
use Symfony\Component\EventDispatcher\EventSubscriberInterface;

class UnleashContextSubscriber implements EventSubscriberInterface
{
    public static function getSubscribedEvents(): array
    {
        return [
            UnleashContextEvent::class => ['onUnleashContextEvent'],
        ];
    }

    public function onUnleashContextEvent(UnleashContextEvent $event): void
    {
        // Get the original payload as an array;
        $payload = $event->getPayload();

        // Set some custom data
        $payload['awesome_data'] = 'amazing';

        // Update payload
        $event->setPayload($payload);
    }
}

测试

只需运行

composer run test

或

$ ./vendor/bin/phpunit
$ ./vendor/bin/phpstan analyse
$ ./vendor/bin/php-cs-fixer fix --config=.php-cs-fixer.dist.php

贡献

请参阅 CONTRIBUTING.md。