Download the PHP package solidworx/toggler without Composer

Toggler

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
• Installation
  • Composer
• Usage
  • StorageFactory
  • Toggle a feature
  • Toggle a feature based on context
  • Using Symfony Expression Language
  • Custom storage to retrieve feature settings
• Twig integration
• Symfony integration
• Testing
• Contributing
• Licence

Requirements

Toggler requires PHP 7.3+ and Symfony 4.0+

Installation

Composer

Usage

Quick Example

You can then check if a feature is active or not using the isActive call

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

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

Storage Adapters

Toggler supports various storage adapters to store the config.

Array

The most basic config is using an array with the ArrayStorage adapter.

ENV

Reads values from environment variables.

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:

Then you can define your config using a yaml file

Pass the path to the yml file to your config

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.

Pass the path to the PHP file to your config

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:

The RedisStorage adapter can take any class instance of Redis, RedisArray, RedisCluster or Predis\Client.

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.

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:

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:

Callbacks that takes any arguments, should be called with the context:

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:

Then you can create an expression for your feature:

When checking the feature, you need to pass the context to use in your expression:

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

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:

To add an alternative if a feature is not available, use the else tag

To use context values with the tag, you can pass it using the with keyword:

You can also use the toggle() function for conditions

Symfony Integration

Toggler comes with integration with the Symfony framework.

To enable toggler inside symfony, register the bundle

Then create a config/packages/toggler.yaml config file, to enable features

If you want to use an expression for a feature config, you can use the @= syntax:

If you want to use a storage class, you can use the storage config parameter to define a service for the 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

This will output the status of a feature.

You can also get the status of multiple features by passing in multiple values:

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.

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.

This will enable the foo feature.

List all available features

You can list all available features using the toggler:list command.

This will display all available features and their status.

Testing

To run the unit tests, execute the following command

Contributing

See CONTRIBUTING

License

Toggler is open-sourced software licensed under the MIT license

Please see the LICENSE file for the full license.