solidworx / toggler
Feature toggle library
Installs: 19 949
Dependents: 1
Suggesters: 0
Security: 0
Stars: 21
Watchers: 5
Forks: 3
Open Issues: 3
Requires
- php: >=7.3
- symfony/polyfill-php80: ^1.20
Requires (Dev)
- mikey179/vfsstream: ^1.6
- phpstan/extension-installer: ^1.0
- phpstan/phpstan: ^1.10
- phpstan/phpstan-deprecation-rules: ^1.1
- phpstan/phpstan-phpunit: ^1.3
- phpstan/phpstan-strict-rules: ^1.5
- phpstan/phpstan-symfony: ^1.2
- phpunit/phpunit: ^9.5
- predis/predis: ^1.1 || ^2.0
- symfony/console: ^4.4 || ^5.0
- symfony/expression-language: ^4.4 || ^5.0
- symfony/framework-bundle: ^4.1 || ^5.0
- symfony/security-core: ^4.4 || ^5.0
- symfony/yaml: ^4.4 || ^5.0
- twig/twig: ^2.7 || ^3.0
Suggests
- symfony/expression-language: To use expressions for conditions
- symfony/framework-bundle: To enable Symfony integration
- symfony/yaml: To pass yml files to the config
- twig/twig: To use the twig extension
This package is auto-updated.
Last update: 2024-11-12 18:22:20 UTC
README
Toggler is a feature toggle library for PHP. It allows you to enable or disable features based on a toggle switch. This is useful in a continues deployment environment, where you can deploy not-yet-ready features which are disabled, and just enable them when the feature is complete.
Table of Contents
Requirements
Toggler requires PHP 7.3+ and Symfony 4.0+
Installation
Composer
$ composer require solidworx/toggler:^2.0
Usage
Quick Example
<?php use SolidWorx\Toggler\Toggle; use SolidWorx\Toggler\Storage\ArrayStorage; $features = [ 'foo' => true, 'bar' => false ]; $toggle = new Toggle(new ArrayStorage($features));
You can then check if a feature is active or not using the isActive
call
<?php $toggle->isActive('foo'); // true $toggle->isActive('bar'); // false
StorageFactory
Toggler comes with many storage adapters to store the configuration. The most basic is the ArrayStorage
class, which takes an array of features.
The StorageFactory
class acts as a factory to create the config. You can pass it any value, and it will determine which storage adapter to use.
To get an instance of the config, you can use the static factory
method
<?php use SolidWorx\Toggler\Storage\StorageFactory; $features = [ 'foo' => true, 'bar' => false ]; $config = StorageFactory::factory($features); // $config will be an instance of ArrayStorage // Using YAML $config = StorageFactory::factory('/path/to/config.yml'); // $config will be an instance of YamlFileStorage
Each feature flag need to be a truthy value in order to be enabled.
The following truthy values are accepted:
- (boolean) true
- (int) 1
- '1'
- 'on'
- 'yes'
- 'y'
Using callbacks
You can also use closures or callbacks to retrieve the value
<?php $features = [ 'foo' => function () { return true; }, 'bar' => [$myObject, 'checkBar'] ];
Storage Adapters
Toggler supports various storage adapters to store the config.
Array
The most basic config is using an array with the ArrayStorage
adapter.
<?php use SolidWorx\Toggler\Storage\StorageFactory; use SolidWorx\Toggler\Storage\ArrayStorage; use SolidWorx\Toggler\Toggle; $features = [ 'foo' => true, 'bar' => false ]; $toggle = new Toggle(new ArrayStorage($features)); // Or using the StorageFactory factory $toggle = new Toggle(StorageFactory::factory($features));
ENV
Reads values from environment variables.
<?php use SolidWorx\Toggler\Storage\EnvStorage; use SolidWorx\Toggler\Toggle; $toggle = new Toggle(new EnvStorage()); $toggle->isActive('MY_AWESOME_FEATURE'); // true if the environment variable MY_AWESOME_FEATURE is set to a truthy value
YAML
In order to use yml files for config, you need to include the Symfony Yaml Component
To install and use the Yaml component, run the following command from the root of your project:
$ composer require symfony/yaml
Then you can define your config using a yaml file
// config.yml foo: true bar: false
Pass the path to the yml file to your config
<?php use SolidWorx\Toggler\Storage\StorageFactory; use SolidWorx\Toggler\Storage\YamlFileStorage; use SolidWorx\Toggler\Toggle; $toggle = new Toggle(new YamlFileStorage('/path/to/config.yml')); // Or using the StorageFactory factory $toggle = new Toggle(StorageFactory::factory('/path/to/config.yml'));
PHP File
You can store your config in a separate PHP file.
This fille needs to return an array with the config.
By default, PHP files always use the ArrayStorage
adapter.
<?php // config.php return[ 'foo' => true, 'bar' => false, ];
Pass the path to the PHP file to your config
<?php use SolidWorx\Toggler\Storage\StorageFactory; use SolidWorx\Toggler\Toggle; $toggle = new Toggle(StorageFactory::factory('/path/to/config.php'));
Redis
You can use Redis to store the configs.
You will then need to either install the Predis library or the Redis PHP extension.
To install Predis, run the following command from the root of your project:
$ composer require predis/predis
The RedisStorage
adapter can take any class instance of Redis
, RedisArray
, RedisCluster
or Predis\Client
.
<?php use SolidWorx\Toggler\Storage\RedisStorage; use SolidWorx\Toggler\Toggle; $redis = new \Redis(); $toggle = new Toggle(new RedisStorage($redis));
Database
You can use a database to store the configs.
Toggler comes with a PDOStorage
adapter, which can be used with any database that supports PDO.
<?php use SolidWorx\Toggler\Storage\PDOStorage; use SolidWorx\Toggler\Toggle; $toggle = new Toggle(new PDOStorage('mysql:host=localhost', 'username', 'password', 'my_feature_table_name'));
Persistent Storage
Toggler supports persisting config values if a storage adapter implements the SolidWorx\Toggler\Storage\PersistenStorageInterface
.
The following storage adapters currently supports persisting config values:
- YamlFileStorage
- RedisStorage
- PDOStorage
To update a feature, use the set
method:
<?php $toggle->set('foo', true); // This will enable the foo feature $toggle->set('bar', false); // This will disable the bar feature
Toggle a feature based on context
To enable a feature only under specific conditions (E.G only enable it for users in a certain group, or only enable it for 10% of visitor etc)
Each feature in the config can take a callback, where you can return a truthy value based on any logic you want to add:
<?php $features = [ 'foo' => function (User $user) { return in_array('admin', $user->getGroups()); // Only enable features for users in the 'admin' group }, 'bar' => function () { return (crc32($_SERVER['REMOTE_ADDR']) % 100) < 25; // Only enable this features for about 25% of visitors }, 'baz' => function (Request $request) { return false !== strpos($request->headers->get('referer'), 'facebook.com'); // Only enable this features for users that come from Facebook } ];
Callbacks that takes any arguments, should be called with the context:
<?php $user = User::find(); // Get the current logged-in user if ($toggle->isActive('foo', [$user])) { } if ($toggle->isActive('bar', [$request])) { }
Using Symfony Expression Language
You can use the Symfony Expression Language Component to create expressions for your features.
To install and use the Expression Language component, run the following command from the root of your project:
$ composer require symfony/expression-language
Then you can create an expression for your feature:
<?php use Symfony\Component\ExpressionLanguage\Expression; $feaures = [ 'foo' => new Expression('valueOne > 10 and valueTwo < 10') ];
When checking the feature, you need to pass the context to use in your expression:
<?php if ($toggle->isActive('foo', ['valueOne' => 25, 'valueTwo' => 5])) { // Will return true }
Twig Integration
Toggler comes with an optional Twig extension, which allows you to toggle elements from Twig templates.
To use the extension, register it with Twig
<?php use SolidWorx\Toggler\Twig\Extension\ToggleExtension; $twig = new \Twig_Environment($loader); $twig->addExtension(new ToggleExtension($toggle));
or if you use symfony, register it as a service.
Note: When using the [Symfony Bundle](Symfony Integration), the twig extension is automatically registered.
Then you can use the toggle
tag in twig templates:
{% toggle 'foo' %} Some content that will only display if foo is enabled {% endtoggle %}
To add an alternative if a feature is not available, use the else
tag
{% toggle 'foo' %} Some content that will only display if foo is enabled {% else %} Some content that will only display if foo is not enabled {% endtoggle %}
To use context values with the tag, you can pass it using the with
keyword:
{% toggle 'foo' with {"valueOne" : 12} %} Some content that will only display if foo is enabled based on the context provided {% endtoggle %}
You can also use the toggle()
function for conditions
{{ toggle('foo') ? 'Foo is enabled' : 'Foo is NOT enabled' }}
Symfony Integration
Toggler comes with integration with the Symfony framework.
To enable toggler inside symfony, register the bundle
// config/bundles.php return array( ... SolidWorx\Toggler\Symfony\TogglerBundle::class => ['all' => true], ... );
Then create a config/packages/toggler.yaml
config file, to enable features
toggler: config: features: foo: true bar: false # Callables is also supported baz: '@my.service.class' # Class must be callable (I.E implement the __invoke() method) foobar: ['@my.service.class', 'foobar'] # Will call the `foobar` method on the service class baz: ['My\Awesome\Feature\Class', 'checkFeature'] # Will call the static method `checkFeature` on the `My\Awesome\Feature\Class` class # The last two lines can be written as the following: foobar: '@my.service.class::foobar' baz: 'My\Awesome\Feature\Class::checkFeature'
If you want to use an expression for a feature config, you can use the @=
syntax:
toggler: config: features: foo: '@=myValue > 10'
If you want to use a storage class, you can use the storage
config parameter to define a service for the storage:
services: my.toggler.storage: class: SolidWorx\Toggler\Storage\RedisStorage arguments: ['@redis'] toggler: config: storage: '@my.toggler.storage'
Note: The features
and storage
options can't be used together. You must use either the one or the other. At least one of the two must be defined.
Note: When using the Symfony bundle, the twig extension is automatically registered.
Note: The symfony/security-core
package is required with symfony/framework-bundle
.
Console Commands
The Symfony Bundle comes with 2 pre-registered console commands.
Get the status of a feature
To see if a feature is enabled or not, run the following command
$ php bin/console toggler:get foo
This will output the status of a feature.
You can also get the status of multiple features by passing in multiple values:
$ php bin/console toggler:get foo bar baz
This will show whether the features foo
, bar
and baz
is enabled or not.
Get the value using context values
To test if a feature will be enabled under certain conditions, you can pass context values to the command using either the -c
or --context
flags.
Multiple values for the context can be provided.
Note: Context values can only be strings. Objects are not supported.
$ php bin/console toggler:get foo -c myValue=10 -c anotherValue=25
Set the value of a feature
You can enable or disable a feature using the toggler:set
command.
Note: You can only change the status of a feature if you are using a persistent storage.
$ php bin/console toggler:set foo true
This will enable the foo
feature.
List all available features
You can list all available features using the toggler:list
command.
$ php bin/console toggler:list
This will display all available features and their status.
Testing
To run the unit tests, execute the following command
$ vendor/bin/phpunit
Contributing
See CONTRIBUTING
License
Toggler is open-sourced software licensed under the MIT license
Please see the LICENSE file for the full license.