Download the PHP package unleash/client without Composer
On this page you can find all versions of the php package unleash/client. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Informations about the package client
- Unleash client SDK
- Migrating
- Installation
- Usage
- Builder
- Required parameters
- Optional parameters
- Returning intermediate objects
- Builder
- Proxy SDK
- Caching
- Bootstrapping
- Custom bootstrap provider
- Disabling communication with Unleash server
- Strategies
- Default strategy
- IP address strategy
- User ID strategy
- Gradual rollout strategy
- Hostname strategy
- Context provider
- Custom strategies
- Variants
- Client registration
- Metrics
- Custom headers via middleware
- Constraints
- GitLab specifics
Unleash client SDK
A PHP implementation of the Unleash protocol aka Feature Flags in GitLab.
You may also be interested in the Symfony Bundle for this package.
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.
Migrating
If you're migrating from 1.x to 2.x, you can read the migration guide.
Installation
composer require unleash/client
Requires PHP 7.2 or newer.
You will also need some implementation of PSR-18 and PSR-17, for example Guzzle and PSR-16, for example Symfony Cache. Example:
composer require unleash/client guzzlehttp/guzzle symfony/cache
or
composer require unleash/client symfony/http-client nyholm/psr7 symfony/cache
If you want to make use of events you also need to install symfony/event-dispatcher
.
See event documentation here.
Usage
The basic usage is getting the Unleash
object and checking for a feature:
You can (and in some cases you must) also provide a context object. If the feature doesn't exist on the server
you will get false
from isEnabled()
, but you can change the default value to true
.
Builder
The builder contains many configuration options, and it's advised to always use the builder to construct an Unleash instance. The builder is immutable.
The builder object can be created using the create()
static method or by using its constructor:
You can replace various parts of the Unleash SDK with custom implementation using the builder, like custom registration service, custom metrics handler and so on.
Replaceable parts (some of them have further documentation below):
- registration service (
withRegistrationService()
) - context provider (
withContextProvider()
) - bootstrap handler (
withBootstrapHandler()
) - event dispatcher (
withEventDispatcher()
) - metrics handler (
withMetricsHandler()
) - variant handler (
withVariantHandler()
)
Dependencies can be injected by implementing one of the following interfaces from the Unleash\Client\Helper\Builder
namespace:
CacheAware
- injects standard cacheConfigurationAware
- injects the global configuration objectHttpClientAware
- injects the http clientMetricsSenderAware
- injects the metrics sender serviceRequestFactoryAware
- injects the request factoryStaleCacheAware
- injects the stale cache handlerStickinessCalculatorAware
- injects the stickiness calculator used for calculating stickiness in gradual rollout strategy
In addition to the parts above these interfaces can also be implemented by these kinds of classes:
- bootstrap providers
- event subscribers
- strategy handlers
Some classes cannot depend on certain objects, namely any object that is present in the configuration cannot implement ConfigurationAware (to avoid circular dependency). The same classes also cannot implement MetricsSenderAware because metrics sender depends on the configuration object. You will get a \Unleash\Client\Exception\CyclicDependencyException if that happens.
Example:
Required parameters
The app name, instance id and app url are required as per the specification.
If you're using Unleash v4 you also need to specify authorization key (API key), you can do so with custom header.
To filter feature toggles by tag or name prefix you can use the Url
helper:
Optional parameters
Some optional parameters can be set, these include:
- http client implementation (PSR-18)
- request factory implementation (PSR-17)
- cache implementation (PSR-16)
- cache ttl
- available strategies
- http headers
The builder will attempt to load http client and request factory implementations automatically. Most implementations, such as guzzlehttp/guzzle or symfony/http-client (in combination with nyholm/psr7), will be loaded automatically. If the builder is unable to locate a http client or request factory implementation, you will need to provide some implementation on your own.
If you use symfony/cache or cache/filesystem-adapter as your cache implementation, the cache handler will be created automatically, otherwise you need to provide some implementation on your own.
Returning intermediate objects
For some use cases the builder can return intermediate objects, for example the UnleashRepository
object. This can be
useful if you need to directly interact with the repository, to refresh the cache manually for example.
Proxy SDK
By default the SDK uses the Server-side endpoints on the Unleash API. You can also use the Proxy SDK, which is a lightweight SDK that uses the Client-side endpoints on the Unleash API. The Proxy SDK give a substantial performance improvement when using a large set of feature toggles (10K+).
To use the Proxy SDK, you need to call withProxy($apiKey)
on the builder. The $apiKey
needs to be a frontend token. Note that withProxy($apiKey)
is in lieu of setting the API key header.
Example of using the builder to create a Proxy SDK instance:
As of version 1.12, the Proxy SDK requires Edge, so the appUrl
needs to point to the Edge server.
Not supported in the Proxy SDK:
- Custom strategies
- Registration (this is handled by Edge)
Caching
It would be slow to perform a http request every time you check if a feature is enabled, especially in popular apps. That's why this library has built-in support for PSR-16 cache implementations.
If you don't provide any implementation and default implementation exists, it's used, otherwise you'll get an exception. You can also provide a TTL which defaults to 30 seconds for standard cache and 30 minutes for stale data cache.
Stale data cache is used when http communication fails while fetching feature list from the server. In that case the latest valid version is used until the TTL expires or server starts responding again. An event gets emitted when this happens, for more information see events documentation.
Cache implementations supported out of the box (meaning you don't need to configure anything):
You can use a different cache implementation for standard item cache and for stale cache. If you don't provide any implementation for stale cache, the same instance as for standard cache is used.
Bootstrapping
You can set a default response from the SDK in cases when for some reason contacting Unleash server fails.
By default, you can bootstrap using:
- json string
- file (via path or instance of
SplFileInfo
) - URL address
- custom stream wrapper path
array
- instances of
Traversable
- instances of
JsonSerializable
These correspond to bootstrap providers:
JsonBootstrapProvider
(json string)FileBootstrapProvider
(file, URL address, custom stream wrapper path)JsonSerializableBootstrapProvider
(array, Traversable, JsonSerializable)EmptyBootstrapProvider
(default provider that doesn't provide any bootstrap)CompoundBootstrapProvider
(can contain multiple bootstrap providers and tries them one by one)
Examples of bootstraps:
Using bootstrap providers directly:
Using multiple bootstrap providers:
Custom bootstrap provider
Creating a custom bootstrap provider is very simple, just implement the BootstrapProvider
interface and use your
class in the builder:
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.
Strategies
Unleash servers can use multiple strategies for enabling or disabling features. Which strategy gets used is defined on the server. This implementation supports all v4 strategies. More here.
Default strategy
This is the simplest of them and simply always returns true if the feature defines default as its chosen strategy and doesn't need any context parameters.
IP address strategy
Enables feature based on the IP address. Takes current user's IP address from the context object. You can provide your
own IP address or use the default ($_SERVER['REMOTE_ADDR']
). Providing your own is especially useful if you're behind
proxy and thus REMOTE_ADDR
would return your proxy server's IP address instead.
As of 1.4.0 the CIDR notation is supported
User ID strategy
Enables feature based on the user ID. The user ID can be any string. You must always provide your own user id via context.
Gradual rollout strategy
Also known as flexible rollout. Allows you to enable feature for only a percentage of users based on their user id, session id or randomly. The default is to try in this order: user id, session id, random.
If you specify the user id type on your Unleash server, you must also provide the user id via context, same as in the
User ID strategy. Session ID can also be provided via context, it defaults to the current session id via session_id()
call.
This strategy requires a stickiness calculator that transforms the id (user, session or random) into a number between 1 and 100. You can provide your own or use the default \Unleash\Client\Stickiness\MurmurHashCalculator
Hostname strategy
This strategy allows you to match against a list of server hostnames (which are not the same as http hostnames).
If you don't specify a hostname in context, it defaults to the current hostname using
gethostname()
.
Note: This library also implements some deprecated strategies, namely
gradualRolloutRandom
,gradualRolloutSessionId
andgradualRolloutUserId
which all alias to the Gradual rollout strategy.
Context provider
Manually creating relevant context can get tiring real fast. Luckily you can create your own context provider that will do it for you!
Custom strategies
To implement your own strategy you need to create a class implementing StrategyHandler
(or AbstractStrategyHandler
which contains some useful methods). Then you need to instruct the builder to use your custom strategy.
Now you must instruct the builder to use your new strategy
Variants
You can use multiple variants of one feature, for example for A/B testing. If no variant matches or the feature doesn't
have any variants, a default one will be returned which returns false
for isEnabled()
. You can also provide your
own default variant.
Variant may or may not contain a payload.
Client registration
By default, the library automatically registers itself as an application in the Unleash server. If you want to prevent
this, use withAutomaticRegistrationEnabled(false)
in the builder.
Metrics
By default, this library sends metrics which are simple statistics about whether user was granted access or not.
The metrics will be bundled and sent once the bundle created time crosses the configured threshold. By default this threshold is 30,000 milliseconds (30 seconds) meaning that when a new bundle gets created it won't be sent sooner than in 30 seconds. That doesn't mean it's guaranteed that the metrics will be sent every 30 seconds, it only guarantees that the metrics won't be sent sooner.
Example:
- user visits your site and this sdk gets triggered, no metric has been sent
- after five seconds user visits another page where again this sdk gets triggered, no metric sent
- user waits one minute before doing anything, no one else is accessing your site
- after one minute user visits another page, the metrics have been sent to the Unleash server
In the example above the metric bundle gets sent after 1 minute and 5 seconds because there was no one to trigger the code.
Custom headers via middleware
While middlewares for http client are not natively supported by this SDK, you can pass your own http client which supports them.
The most popular http client, guzzle, supports them out of the box and here's an example of how to pass custom headers automatically (for more information visit official guzzle documentation on middlewares):
Constraints
Constraints are supported by this SDK and will be handled correctly by Unleash::isEnabled()
if present.
GitLab specifics
- In GitLab you have to use the provided instance id, you cannot create your own.
- No authorization header is necessary.
- Instead of app name you need to specify the GitLab environment.
- For this purpose you can use
withGitlabEnvironment()
method in builder, it's an alias towithAppName()
but communicates the intent better.
- For this purpose you can use
- GitLab doesn't use registration system, you can set the SDK to disable automatic registration and save one http call.
- GitLab doesn't read metrics, you can set the SDK to disable sending them and save some http calls.
Check out our guide for more information on how to build and scale feature flag systems
All versions of client with dependencies
ext-json Version *
psr/http-client Version ^1.0
psr/http-client-implementation Version ^1.0
psr/http-factory Version ^1.0
psr/http-factory-implementation Version ^1.0
psr/simple-cache Version ^1.0 | ^2.0 | ^3.0
psr/simple-cache-implementation Version ^1.0 | ^2.0 | ^3.0
lastguest/murmurhash Version ^2.1
psr/http-message Version ^1.0 | ^2.0
php-http/discovery Version ^1.14
symfony/event-dispatcher Version ^5.0 | ^6.0 | ^7.0