Download the PHP package unleash/symfony-client-bundle without Composer

A Symfony bundle for PHP implementation of the Unleash protocol aka Feature Flags in GitLab.

View the standalone PHP version at Packagist or GitHub.

Unleash allows you to gradually release your app's feature before doing a full release based on multiple strategies like releasing to only specific users or releasing to a percentage of your user base. Read more in the above linked documentations.

Requires php 7.3 or newer.

For generic description of the methods read the standalone package documentation, this README will focus on Symfony specific things

Installation

composer require unleash/symfony-client-bundle

If you use flex the bundle should be enabled automatically, otherwise add Unleash\Client\Bundle\UnleashSymfonyClientBundle to your config/bundles.php

Basic usage

First configure the basic parameters, either using a DSN or as separate parameters:

or

Tip: Generate the default config by running php bin/console config:dump unleash_client > config/packages/unleash_client.yaml which will create the default config file which you can then tweak

Controller attribute

You can also check for feature flag using #[IsEnabled] and #[IsNotEnabled] attributes on a controller. You can use it on the whole controller class as well as on a concrete method.

In the example above the user on /my-route needs both my_awesome_feature and another_awesome_feature enabled (because of one attribute on the class and another attribute on the method) while the /other-route needs only my_awesome_feature enabled (because of class attribute).

In the second example, /my-route route is only enabled if kill_switch is not enabled.

You can also notice that one of the attributes specifies a second optional parameter with status code. The supported status codes are:

• 404 - NotFoundHttpException
• 403 - AccessDeniedHttpException
• 400 - BadRequestHttpException
• 401 - UnauthorizedHttpException with message "Unauthorized".
• 503 - ServiceUnavailableHttpException

The default status code is 404. If you use an unsupported status code InvalidValueException will be thrown.

Setting custom exception for attribute

If you want custom exception for situations when user is denied access based on the attribute, you can listen to an event:

Context

The context object supplies additional parameters to Unleash and supports Symfony features out of the box. This context is also being injected to the Unleash service instead of the generic one.

The current user id is assigned automatically if the Symfony Security component is installed. You can configure which field to use for the user id, by default it uses either the Symfony\Component\Security\Core\User\UserInterface::getUserIdentifier() or Symfony\Component\Security\Core\User\UserInterface::getUsername().

With this configuration this bundle will use the id property to assign user id. The property doesn't have to be public.

The bundle also automatically integrates with Symfony's request stack getting the IP address and session id from it, which may be particularly useful if you're behind proxy and have it in your trusted proxies list.

The context environment defaults to the value of kernel.environment parameter.

Custom Properties

You can also define your own properties that will be present in the context. If you use the Symfony Expression Language you can also use expressions in them. If the value is an expression it must start with the > character. If you want your value to start with > and not be an expression, escape it using \. All expressions have access to user variable which is either the user object or null.

If you don't want to embed your logic in config, you can also listen to an event:

Events

There are two kinds of events, events from the base Unleash php sdk and from this Symfony bundle.

Base SDK events

• \Unleash\Client\Event\UnleashEvents::FEATURE_TOGGLE_NOT_FOUND
• \Unleash\Client\Event\UnleashEvents::FEATURE_TOGGLE_DISABLED
• \Unleash\Client\Event\UnleashEvents::FEATURE_TOGGLE_MISSING_STRATEGY_HANDLER

For more information read the documentation in the base SDK.

Symfony bundle events

• \Unleash\Client\Bundle\Event\UnleashEvents::CONTEXT_VALUE_NOT_FOUND
• \Unleash\Client\Bundle\Event\UnleashEvents::BEFORE_EXCEPTION_THROWN_FOR_ATTRIBUTE

The events are documented in relevant parts of this README.

Twig

If you use twig you can make use of functions, filters, test and a custom tag. The names are generic, that's why you can disable any of them in case they would clash with your own functions/filters/tests/tags.

The default is that everything is enabled if twig is installed.

Twig functions

There are two functions: feature_is_enabled() and feature_variant().

The first returns a boolean and the second one returns an instance of Unleash\Client\DTO\Variant.

Twig filter

Instead of function you can use a filter with the same name.

Twig test

You can also use a test with the name enabled.

Twig tag

This tag is experimental and may be removed in future version

You can use a custom feature tag. Anything in the body will get processed only if the feature is enabled. You also have access to implicit variant variable.

Custom strategies

Defining custom strategies is very easy because they get automatically injected, you just need to create a class implementing Unleash\Client\Strategy\StrategyHandler (or extending Unleash\Client\Strategy\AbstractStrategyHandler).

And that's it, due to implementing the interface (by extending the abstract class) your class is automatically registered as a strategy handler and the Unleash service can handle it.

If you want to make use of one of the default strategies, you can, all of them support autowiring.

Disabling built-in strategies

If for some reason you want to disable any of the built-in strategies, you can do so in config.

Cache and http

By default the services are set to make use of symfony/http-client, nyholm/psr7 and symfony/cache.

You can overwrite the default values in config:

The http client service must implement Psr\Http\Client\ClientInterface or Symfony\Contracts\HttpClient\HttpClientInterface.

The request factory service must implement Psr\Http\Message\RequestFactoryInterface.

The cache service must implement Psr\SimpleCache\CacheInterface or Psr\Cache\CacheItemPoolInterface (which by extension means it can implement the standard Symfony\Component\Cache\Adapter\AdapterInterface which extends it).

Bootstrapping

You can set a default response from the SDK in cases when for some reason contacting Unleash server fails.

You can bootstrap using a file or a service implementing \Unleash\Client\Bootstrap\BootstrapProvider.

Service

Tip: If you create only one service that implements BootstrapProvider it will be injected automatically. If you create more than one you need to manually choose a bootstrap as in example above.

File

Let's say you create a file called bootstrap.json in your config directory, this is how you can inject it as Unleash bootstrap:

Note: All files must start with the file:// prefix.

Disabling communication with Unleash server

It may be useful to disable communication with the Unleash server for local development and using a bootstrap instead.

Note that when you disable communication with Unleash and don't provide a bootstrap, an exception will be thrown.

Tip: Set the cache interval to 0 to always have a fresh bootstrap content.

The usually required parameters (app name, instance id, app url) are not required when communication is disabled.

Test command

If you need to quickly test what will your flags evaluate to, you can use the built-in command unleash:test-flag.

The command is documented and here's the output of ./bin/console unleash:test-flag --help:

Configuration reference

This is the autogenerated config dump (by running php bin/console config:dump unleash_client):