Skip to main content

Server Side SDKs

tip

Server Side SDKs can run in 2 different modes: Local Evaluation and Remote Evaluation. We recommend reading up about the differences first before integrating the SDKS into your applications.

SDK Overview​

Add the Flagsmith package​

# Requires PHP 7.4 or newer and ships with GuzzleHTTP.
composer require flagsmith/flagsmith-php-client

# You can optionally provide your own implementation of PSR-18 and PSR-16.
# You will also need some implementation of PSR-18 and PSR-17,
# for example Guzzle and PSR-16, for example Symfony Cache.
composer require flagsmith/flagsmith-php-client guzzlehttp/guzzle symfony/cache

# or
composer require flagsmith/flagsmith-php-client symfony/http-client nyholm/psr7 symfony/cache

Initialise the SDK​

tip

Server-side SDKs must be initialised with Server-side Environment keys. These can be created in the Environment settings area and should be considered secret.

use Flagsmith\Flagsmith;

$flagsmith = new Flagsmith('FLAGSMITH_SERVER_SIDE_ENVIRONMENT_KEY');

Get Flags for an Environment​

$flags = $flagsmith->getEnvironmentFlags();
$flags->isFeatureEnabled('secret_button');
$flags->getFeatureValue('secret_button');

Get Flags for an Identity​

$identifier = 'delboy@trotterstraders.co.uk';
$traits = (object) [ 'car_type' => 'robin_reliant' ];

$flags = $flagsmith->getIdentityFlags($identifier, $traits);
$showButton = $flags->isFeatureEnabled('secret_button');
$buttonData = $flags->getFeatureValue('secret_button');

When running in Remote Evaluation mode​

  • When requesting Flags for an Identity, all the Traits defined in the SDK will automatically be persisted against the Identity within the Flagsmith API.
  • Traits passed to the SDK will be added to all the other previously persisted Traits associated with that Identity.
  • This full set of Traits are then used to evaluate the Flag values for the Identity.
  • This all happens in a single request/response.

When running in Local Evaluation mode​

  • Only the Traits provided to the SDK at runtime will be used. Local Evaluation mode, by design, does not make any network requests to the Flagsmith API when evaluating Flags for an Identity.
    • When running in Local Evaluation Mode, the SDK requests the Environment Document from the Flagsmith API. This contains all the information required to make Flag Evaluations, but it does not contain any Trait data.

Managing Default Flags​

Default Flags are configured by passing in a function that is called when a Flag cannot be found or if the network request to the API fails when retrieving flags.

$flagsmith = (new Flagsmith('FLAGSMITH_SERVER_SIDE_ENVIRONMENT_KEY'))
    ->withDefaultFlagHandler(function ($featureName) {
        $defaultFlag = (new DefaultFlag())
            ->withEnabled(false)->withValue(null);
        if ($featureName === 'secret_button') {
            return $defaultFlag->withValue('{"colour": "#ababab"}');
        }

        return $defaultFlag;
    });

Using an Offline Handler​

info

Offline handlers are still in active development. We are building them for all our SDKs; those that are production ready are listed below.

Progress on the remaining SDKs can be seen here.

Flagsmith SDKs can be configured to include an offline handler which has 2 functions:

  1. It can be used alongside Offline Mode to evaluate flags in environments with no network access
  2. It can be used as a means of defining the behaviour for evaluating default flags, when something goes wrong with the regular evaluation process. To do this, simply set the offline handler initialisation parameter without enabling offline mode.

To use it as a default handler, we recommend using the flagsmith CLI to generate the Environment Document and use our LocalFileHandler class, but you can also create your own offline handlers, by extending the base class.

// Using the built-in local file handler

$offline_handler = new LocalFileHandler("/path/to/environment.json")

// Instantiate the client with offline mode set to true

$flagsmith = new Flagsmith(
    offline_mode: true,
    offline_handler: offline_handler,
)

// Defining a custom offline handler

class LocalFileHandler implements IOfflineHandler
{
    public function getEnvironment()
    {
        // Some code providing the environment for the handler
    }
}

Network Behaviour​

The Server Side SDKS share the same network behaviour across the different languages:

Remote Evaluation Mode Network Behaviour​

  • A blocking network request is made every time you make a call to get an Environment Flags. In Python, for example, flagsmith.get_environment_flags() will trigger this request.
  • A blocking network request is made every time you make a call to get an Identities Flags. In Python, for example, flagsmith.get_identity_flags(identifier=identifier, traits=traits) will trigger this request.

Local Evaluation Mode Network Behaviour​

info

When using Local Evaluation, it's important to read up on the Pros, Cons and Caveats.

To use Local Evaluation mode, you must use a Server Side key.

  • When the SDK is initialised, it will make an asynchronous network request to retrieve details about the Environment.
  • Every 60 seconds (by default), it will repeat this aysnchronous request to ensure that the Environment information it has is up to date.

To achieve Local Evaluation, in most languages, the SDK spawns a separate thread (or equivalent) to poll the API for changes to the Environment. In certain languages, you may be required to terminate this thread before cleaning up the instance of the Flagsmith client. Languages in which this is necessary are provided below.

Since PHP does not share state between requests, you have to implement caching to get the benefits of Local Evaluation mode. Please see caching below.

Offline Mode​

To run the SDK in a fully offline mode, you can set the client to offline mode. This will prevent the SDK from making any calls to the Flagsmith API. To use offline mode, you must also provide an offline handler. See Configuring the SDK for more details on initialising the SDK in offline mode.

Configuring the SDK​

You can modify the behaviour of the SDK during initialisation. Full configuration options are shown below.

$flagsmith = new Flagsmith(
    /*
    Your API Token.
    Note that this is either the `Environment API` key or the `Server Side SDK Token`
    depending on if you are using Local or Remote Evaluation
    Required.
    */
    string $apiKey,

    /*
    Override the default Flagsmith API URL if you are self-hosting.
    Optional.
    Defaults to https://edge.api.flagsmith.com/api/v1/
    */
    string $host = self::DEFAULT_API_URL,

    /*
    Custom http headers can be added to the http client
    Optional
    */
    object $customHeaders = null,

    /*
    Set environment refresh rate with polling manager.
    This also enables local evaluation.
    Optional.
    Defaults to null
    */
    int $environmentTtl = null,

    /*
    Retry Object, instance of Flagsmith\Utils\Retry
    Retry configuration for api calls.
    Defaults to 3 retries for every api call.
    */
    Retry $retries = null,

    /*
    Controls whether Flag Analytics data is sent to the Flagsmith API
    See https://docs.flagsmith.com/advanced-use/flag-analytics
    Optional
    Defaults to false
    */
    bool $enableAnalytics = false,

    /*
    You can specify default Flag values on initialisation.
    Optional
    */
    Closure $defaultFlagHandler = null

    /*
    (Available in 4.4.0+) Set the SDK into offline mode
    Optional
    */
    bool $offlineMode = false,

    # (Available in 4.4.0+) Provide an offline handler to use with offline mode, or
    # as a means of returning default flags.
    # Optional
    IOfflineHandler $offlineHandler = null,
);

Caching​

Some SDKs support caching flags retrieved from the Flagsmith API, or calculated from your environment definition if using Local Evaluation.

$flagsmith = (new Flagsmith("FLAGSMITH_SERVER_SIDE_ENVIRONMENT_KEY"));
// This will load the environment from cache (or API, if cache does not exist.)
$flagsmith->updateEnvironment();

It is recommended to use a psr simple-cache implementation to cache the environment document between multiple requests.

composer require symfony/cache
$flagsmith = (new Flagsmith("FLAGSMITH_SERVER_SIDE_ENVIRONMENT_KEY"))
  ->withCache(new Psr16Cache(new FilesystemAdapter()));
// Cache the environment call to reduce network calls for each and every evaluation.
// This will load the environment from cache (or API, if cache does not exist.)
$flagsmith->updateEnvironment();

An optional cron job can be added to refresh this cache at a set time depending on your choice. Please set EnvironmentTTL value for this purpose.

// the environment will be cached for 100 seconds.
$flagsmith = $flagsmith->withEnvironmentTtl(100);
$flagsmith->updateEnvironment();
* * * 1 40 php index.php # using cli
* * * 1 40 curl http://localhost:8000/ # using http

Note:

  • For the environment cache, please use the server key generated from the Flagsmith Settings menu. The key's prefix is ser..
  • The cache is important for concurrent requests. Without the cache, each request in PHP is a different process with its own memory objects. The cache (filesystem or other) would enforce that the network call is reduced to a file system one.

Logging​

The following SDKs have code and functionality related to logging.

Logging is disabled by default. If you would like to enable it then call .enableLogging() on the client builder:

FlagsmithClient flagsmithClient = FlagsmithClient.newBuilder()
                // other configuration as shown above
                .enableLogging()
                .build();

Flagsmith uses SLF4J and we only implement its API. If your project does not already have SLF4J, then include an implementation, i.e.:

<dependency>
  <groupId>org.slf4j</groupId>
  <artifactId>slf4j-simple</artifactId>
  <version>${slf4j.version}</version>
</dependency>

Contribute to the SDKs​

All our SDKs are Open Source.

https://github.com/Flagsmith/flagsmith-php-client