unleash / symfony-client-bundle
Installs: 188 095
Dependents: 0
Suggesters: 2
Security: 0
Stars: 33
Watchers: 4
Forks: 8
Open Issues: 2
Type:symfony-bundle
Requires
- php: ^8.2
- nyholm/psr7: ^1.0
- symfony/cache: ^5.0 | ^6.0 | ^7.0
- symfony/event-dispatcher: ^5.0 | ^6.0 | ^7.0
- symfony/framework-bundle: ^5.0 | ^6.0 | ^7.0
- symfony/http-client: ^5.0 | ^6.0 | ^7.0
- unleash/client: ^2.4
Requires (Dev)
- friendsofphp/php-cs-fixer: ^3.15
- jetbrains/phpstorm-attributes: ^1.0
- phpstan/phpstan: ^1.10
- rector/rector: ^0.15.23
- symfony/expression-language: ^5.0 | ^6.0 | ^7.0
- symfony/security-core: ^5.0 | ^6.0 | ^7.0
- symfony/yaml: ^6.3 | ^7.0
- twig/twig: ^3.3
Suggests
- symfony/expression-language: For integration of expression language in custom properties in Unleash context
- symfony/security-bundle: For integration of Symfony users into Unleash context
- dev-main
- v0.11.382
- v0.11.381
- v0.11.380
- v0.11.374
- v0.11.373
- v0.11.282
- v0.11.281
- v0.11.280
- v0.11.274
- v0.11.273
- v0.11.182
- v0.11.181
- v0.11.180
- v0.11.174
- v0.11.173
- v0.11.082
- v0.11.081
- v0.11.080
- v0.11.074
- v0.11.073
- v0.10.382
- v0.10.381
- v0.10.380
- v0.10.374
- v0.10.373
- v0.10.282
- v0.10.281
- v0.10.280
- v0.10.274
- v0.10.273
- v0.10.182
- v0.10.181
- v0.10.180
- v0.10.174
- v0.10.173
- v0.10.082
- v0.10.081
- v0.10.080
- v0.10.074
- v0.10.073
- v0.9.1480
- v0.9.1474
- v0.9.1473
- v0.9.1380
- v0.9.1374
- v0.9.1373
- v0.9.1280
- v0.9.1274
- v0.9.1273
- v0.9.1180
- v0.9.1174
- v0.9.1173
- v0.9.1080
- v0.9.1074
- v0.9.1073
- v0.9.980
- v0.9.974
- v0.9.973
- v0.9.880
- v0.9.874
- v0.9.873
- v0.9.780
- v0.9.774
- v0.9.773
- v0.9.680
- v0.9.674
- v0.9.673
- v0.9.580
- v0.9.574
- v0.9.573
- v0.9.480
- v0.9.474
- v0.9.473
- v0.9.380
- v0.9.374
- v0.9.373
- v0.9.280
- v0.9.274
- v0.9.273
- v0.9.180
- v0.9.174
- v0.9.173
- v0.9.080
- v0.9.074
- v0.9.073
- dev-feat/env-processors
- dev-php-7.3
- dev-php-8.0
- dev-php-8.1
- dev-php-7.4
This package is auto-updated.
Last update: 2024-11-06 11:21:50 UTC
README
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 yourconfig/bundles.php
Basic usage
First configure the basic parameters, either using a DSN or as separate parameters:
unleash_client: dsn: http://localhost:4242/api?instance_id=myCoolApp-Server1&app_name=myCoolApp
or
unleash_client: app_url: http://localhost:4242/api instance_id: myCoolApp-Server1 app_name: myCoolApp
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
<?php use Unleash\Client\Unleash; class MyService { public function __construct(Unleash $unleash) { if ($unleash->isEnabled('someFeatureName')) { // todo } } }
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.
<?php use Unleash\Client\Bundle\Attribute\IsEnabled; use Symfony\Component\HttpFoundation\Response; use Symfony\Component\Routing\Annotation\Route; #[IsEnabled('my_awesome_feature')] final class MyController { #[IsEnabled('another_awesome_feature', Response::HTTP_BAD_REQUEST)] #[Route('/my-route')] public function myRoute(): Response { // todo } #[Route('/other-route')] public function otherRoute(): Response { // todo } }
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).
<?php use Unleash\Client\Bundle\Attribute\IsNotEnabled; use Symfony\Component\HttpFoundation\Response; use Symfony\Component\Routing\Annotation\Route; #[IsNotEnabled('kill_switch')] final class MyHeavyController { #[Route('/my-route')] public function myRoute(): Response { // todo } }
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:
<?php use Symfony\Component\EventDispatcher\EventSubscriberInterface; use Unleash\Client\Bundle\Event\UnleashEvents; use Unleash\Client\Bundle\Event\BeforeExceptionThrownForAttributeEvent; use Symfony\Component\HttpFoundation\Response; final class MySubscriber implements EventSubscriberInterface { public static function getSubscribedEvents(): array { return [ UnleashEvents::BEFORE_EXCEPTION_THROWN_FOR_ATTRIBUTE => 'handleException', ]; } public function handleException(BeforeExceptionThrownForAttributeEvent $event): void { $statusCode = $event->getErrorCode(); switch ($statusCode) { case Response::HTTP_NOT_FOUND: $exception = new CustomException('Custom message'); break; default: $exception = null; } // the exception can be a Throwable or null, null means that this bundle reverts // to its own default exceptions $event->setException($exception); } }
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.
<?php use Unleash\Client\Configuration\Context; use Unleash\Client\Enum\ContextField; class MyService { public function __construct(Context $context) { $context->getCurrentUserId(); $context->getSessionId(); $context->getIpAddress(); $context->hasCustomProperty('someProperty'); $context->getCustomProperty('someProperty'); $context->hasMatchingFieldValue('someProperty', ['someValue1', 'someValue2']); $context->findContextValue(ContextField::USER_ID); } }
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()
.
unleash_client: context: user_id_field: id
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.
unleash_client: context: custom_properties: myCustomProperty: someValue # just a good old string myOtherProperty: '> 1+1' # starts with >, it will be turned into expression, meaning the value will be 2 myEscapedProperty: '\> someValue' # will be turned into '> someValue' someUserField: '> user.getCustomField()' # will be the result of the getCustomField() method call safeUserField: '> user ? user.getCustomField() : null'
If you don't want to embed your logic in config, you can also listen to an event:
<?php use Unleash\Client\Bundle\Event\UnleashEvents; use Symfony\Component\EventDispatcher\EventSubscriberInterface; use Unleash\Client\Bundle\Event\ContextValueNotFoundEvent; class MyListener implements EventSubscriberInterface { public static function getSubscribedEvents(): array { return [ UnleashEvents::CONTEXT_VALUE_NOT_FOUND => 'handleNotFoundContextValue', ]; } public function handleNotFoundContextValue(ContextValueNotFoundEvent $event) { switch ($event->getContextName()) { case 'myProperty': $value = '...'; // dynamically create the value $event->setValue($value); break; } } }
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.
unleash_client: twig: functions: true filters: true tests: true tags: true
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
.
{% if feature_is_enabled('featureName') %} {% set variant = feature_variant('featureName') %} {% if variant.enabled %} {{ variant.name }} {% endif %} {% endif %}
Twig filter
Instead of function you can use a filter with the same name.
{% if 'featureName'|feature_is_enabled %} {% set variant = 'featureName' | feature_variant %} {# Do something #} {% endif %}
Twig test
You can also use a test with the name enabled
.
{% if 'featureName' is enabled %} {# Do something #} {% endif %}
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.
{% feature 'featureName' %} {{ variant.name }} {# Implicit variant variable that only exists in the scope of feature block #} {% endfeature %}
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
).
<?php use Unleash\Client\Strategy\AbstractStrategyHandler; use Unleash\Client\DTO\Strategy; use Unleash\Client\Configuration\Context; class MyCustomStrategy extends AbstractStrategyHandler { public function getStrategyName() : string { return 'my_custom_strategy'; } public function isEnabled(Strategy $strategy, Context $context) : bool { $someCustomProperty = $this->findParameter('customProperty', $strategy); if ($someCustomProperty === false) { return false; } // assume it's a list $someCustomProperty = array_map('trim', explode(',', $someCustomProperty)); $enabled = $context->hasMatchingFieldValue('customProperty', $someCustomProperty); // check if the constraints are valid using the abstract class' method if (!$enabled || !$this->validateConstraints($strategy, $context)) { return false; } return true; } }
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.
unleash_client: disabled_strategies: - default - remoteAddress
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:
unleash_client: http_client_service: my_custom_http_client_service request_factory_service: my_custom_request_factory_service cache_service: my_custom_cache_service
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
<?php use Unleash\Client\Bootstrap\BootstrapProvider; final class MyBootstrap implements BootstrapProvider { public function getBootstrap() : array|JsonSerializable|Traversable|null{ // TODO: Implement getBootstrap() method. } }
unleash_client: bootstrap: '@MyBootstrap'
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:
unleash_client: bootstrap: 'file://%kernel.project_dir%/config/bootstrap.json'
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.
unleash_client: bootstrap: '@MyBootstrap' cache_ttl: 0 fetching_enabled: false
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
:
Description:
Check the status of an Unleash feature
Usage:
unleash:test-flag [options] [--] <flag>
Arguments:
flag The name of the feature flag to check the result for
Options:
-f, --force When this flag is present, fresh results without cache will be forced
--user-id=USER-ID [Context] Provide the current user's ID
--ip-address=IP-ADDRESS [Context] Provide the current IP address
--session-id=SESSION-ID [Context] Provide the current session ID
--hostname=HOSTNAME [Context] Provide the current hostname
--environment=ENVIRONMENT [Context] Provide the current environment
--current-time=CURRENT-TIME [Context] Provide the current date and time
--custom-context=CUSTOM-CONTEXT [Context] Custom context values in the format [contextName]=[contextValue], for example: myCustomContextField=someValue (multiple values allowed)
--expected=EXPECTED For use in testing, if this option is present, the exit code will be either 0 or 1 depending on whether the expectation matches the result
-h, --help Display help for the given command. When no command is given display help for the list command
-q, --quiet Do not output any message
-V, --version Display this application version
--ansi|--no-ansi Force (or disable --no-ansi) ANSI output
-n, --no-interaction Do not ask any interactive question
-e, --env=ENV The Environment name. [default: "dev"]
--no-debug Switch off debug mode.
--profile Enables profiling (requires debug).
-v|vv|vvv, --verbose Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug
Configuration reference
This is the autogenerated config dump (by running php bin/console config:dump unleash_client
):
# Default configuration for extension with alias: "unleash_client" # Default configuration for extension with alias: "unleash_client" unleash_client: # You can provide the connection details as a DSN instead of app_url, instance_id and app_name. DSN takes precedence over individual parameters. dsn: null # Example: 'https://localhost:4242/api?instance_id=myCoolApp-Server1&app_name=myCoolApp' # The application api URL app_url: null # The instance ID, for Unleash it can be anything, for GitLab it must be the generated value instance_id: null # Application name, for Unleash it can be anything, for GitLab it should be a GitLab environment name app_name: null context: # The field name to use as user id, if set to null getUserIdentifier() or getUsername() method will be called user_id_field: null # Any additional context properties custom_properties: [] # Whether to enable communication with Unleash server or not. If you set it to false you must also provide a bootstrap. fetching_enabled: true # The http client service, must implement the Psr\Http\Client\ClientInterface or Symfony\Contracts\HttpClient\HttpClientInterface interface http_client_service: psr18.http_client # The request factory service, must implement the Psr\Http\Message\RequestFactoryInterface interface. Providing null means autodetect between supported default services. request_factory_service: null # The cache service, must implement the Psr\SimpleCache\CacheInterface or Psr\Cache\CacheItemPoolInterface interface cache_service: cache.app # Default bootstrap in case contacting Unleash servers fails. Can be a path to file (prefixed with file://) or a service implementing Unleash\Client\Bootstrap\BootstrapProvider (prefixed with @) bootstrap: null # Disabled default strategies, must be one of: default, flexibleRollout, gradualRolloutRandom, gradualRolloutSessionId, gradualRolloutUserId, remoteAddress, userWithId, applicationHostname disabled_strategies: [] # The interval at which to send metrics to the server in milliseconds metrics_send_interval: 30000 # Whether to allow sending feature usage metrics to your instance of Unleash, set this to false for GitLab metrics_enabled: true # Whether to allow automatic client registration on client initialization, set this to false for GitLab auto_registration: true # The time in seconds the features will stay valid in cache cache_ttl: 30 # The maximum age (in seconds) old features will be served from cache if http request fails for some reason stale_ttl: 1800 # Additional headers to use in http client, for Unleash "Authorization" is required custom_headers: [] # Enable or disable twig function/filter/tests twig: # Enables the "feature_is_enabled" and "feature_variant" twig functions functions: false # Enables the "feature_is_enabled" and "feature_variant" filters filters: false # Enables the "enabled" test, allowing you to write {% if "featureName" is enabled %} tests: false # Enables the "feature" twig tag tags: false