README

An Unleash bundle for Symfony 5.4+, 6.4+ and 7.0+ applications.

This provide an easy way to implement feature flags using Gitlab Feature Flags Feature.

This implementation conforms to the official Unleash standards.

Inspired by minds/unleash-client-php and mikefrancis/laravel-unleash.

Installation

composer require stogon/unleash-bundle

Configurations

Full configurations example:

# 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

Usage

To use the client, simply inject Stogon\UnleashBundle\UnleashInterface into your service and use it like this:

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

The bundle also provide Twig functions to check if a feature is enabled/disabled for the current user:

{# 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 -%}

Console

There are console commands that comes with this bundle :

Command name	Description
`unleash:features:fetch`	Fetch Unleash features from remote and store them in the cache for later usage.
`unleash:features:list`	List available Unleash features from remote.

Strategies

Available strategies:

Strategy name	Description
`default`	It is the simplest activation strategy and basically means "active for everyone".
`userWithId`	This strategy allows you to specify a list of user IDs that you want to expose the new feature for. (A user id may, of course, be an email if that is more appropriate in your system.)
`flexibleRollout`	A flexible rollout strategy which combines all gradual rollout strategies in to a single strategy (and will in time replace them)
`gradualRolloutUserId`	The `gradualRolloutUserId` strategy gradually activates a feature toggle for logged-in users. Stickiness is based on the user ID. The strategy guarantees that the same user gets the same experience every time across devices
`gradualRolloutSessionId`	Similar to `gradualRolloutUserId` strategy, this strategy gradually activates a feature toggle, with the exception being that the stickiness is based on the session IDs. This makes it possible to target all users (not just logged-in users), guaranteeing that a user will get the same experience within a session.
`gradualRolloutRandom`	The `gradualRolloutRandom` strategy randomly activates a feature toggle and has no stickiness. We have found this rollout strategy very useful in some scenarios, especially when we enable a feature which is not visible to the user. It is also the strategy we use to sample metrics and error reports.

For more informations, see https://docs.getunleash.io/docs/activation_strategy

Add a custom strategy

If the existing strategies does not fill your needs, you can implement a custom strategy with your own logic.

First, you need to create a class which implements the 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;
    }
}

Then you need to tag your custom strategy with the unleash.strategy tag and provide a activation_name for it.

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

The activation_name must match the strategy.name value of your Unleash strategy ! see https://docs.getunleash.io/docs/activation_strategy

Override an existing strategy

You can override an existing strategy simply by setting the activation_name of the tag to the same strategy name used here.

Example:

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

Add additional context to strategies

If you want to add additional data to the context passed to resolved strategy ($context parameter of the Stogon\UnleashBundle\Strategy\StrategyInterface::isEnabled method), you can implement an event listener/subscriber to react to the Stogon\UnleashBundle\Event\UnleashContextEvent event.

Example:

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

Testing

Simply run :

composer run test

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

Contributing

See CONTRIBUTING.md.

stogon / unleash-bundle

Maintainers

Details