PHP API

11 minute readReference

The following information is for the latest version of the PHP SDK. If you are running an older version, please check the CloudBees Feature Management - PHP changelog for any differences.

Class Rox

namespace Rox\Server;

class Rox
▼

The Rox class provides an interface for CloudBees Feature Management to manage feature flags that control the behavior of your application. This is the central repository for your application’s flags. This class handles communications with the server to obtain the latest flag values, implement flag settings, and set up flag configurations. It works with a RoxContainer-derived object, which holds your application’s feature flags. The values in the provided container are marked as feature flags and display in the CloudBees Feature Management UI once the application is run.

This class also allows you to manage custom properties. These can be static settings of type string, boolean, integer, or double, or you can use a generator class to provide a custom property that is dependent upon code state. These generated properties must derive from CustomPropertyGenerator, which is a template class.

You can also use a RoxOptions object to configure some aspects of this class. You can set the verbosity level, custom platform, global freeze level, impression handler, and fetch handler.

Setup

public static function setup($apiKey, RoxOptions $roxOptions = null)
▼

Configures the Rox object to work with the provided application.

Parameter Modifier and Type Description

$apiKey

string

The environment key provided by the CloudBees Feature Management dashboard

$roxOptions

RoxOptions

A RoxOptions instance with the desired configuration for this application

Shutdown

public static function shutdown()
▼

This method may be used for the graceful shutdown of the Rox framework, to close and clean all the consumed resources, and reset the state of the framework.

It can only be used when Rox is successfully setup.

Calling shutdown when it’s not possible, will result a log warning.

You can call setup again after shutdown; right after shutdown, all register and setCustomProperty will use a new ROXCore, and will register the objects to the Dashboard on the next setup call.

Register

public static function register($namespace, $container)
public static function register($container)
▼

Registers a feature flag container with the Rox client. The public member variables of this container will become a flag in your CloudBees Feature Management dashboard and will be named with the object name.

Parameter Modifier and Type Description

$namespace

string

The prefix namespace for all flags in this container (optional). If not specified, the default namespace ("") will be used.

$container

object

An object that contains your application’s feature flags

For example, assuming we have the following container:

class MyContainer
{
  public $includeFacebook;
  public $headline;

  public function __construct() {
    $this->includeFacebook = new RoxFlag();
    $this->headline = new RoxString("welcome");
  }
}
▼

and register the container with the following code:

$flags = new MyContainer();
Rox::register("Login", flags);
Rox::setup(rolloutKey);
▼

The flags in the dashboard will have the names Login.includeFacebook and Login.headline.

This is very handy if you want to have groups of flags.

If you don’t need a namespace, you can omit the namespace parameter ot set it to an empty string.

setCustomComputedBooleanProperty

public static function setCustomComputedBooleanProperty($name, callable $value)
▼

Sets a computed boolean Custom Property on the Rox client. This is a computable boolean, with an object that generates the value for the property.

Parameter Modifier and Type Description

$name

string

The name of the property to create

$value

callable

A function with a context parameter, that returns the computed property value

setCustomComputedDoubleProperty

public static function setCustomComputedDoubleProperty($name, callable $value)
▼

Sets a computed double Custom Property on the Rox client. This is a computable double, with an object that generates the value for the property.

Parameter Modifier and Type Description

$name

string

The name of the property to create

$value

callable

A function with a context parameter, that returns the computed property value

setCustomComputedIntegerProperty

public static function setCustomComputedIntegerProperty($name, callable $value)
▼

Sets a computed integer Custom Property on the Rox client. This is a computable integer, with an object that generates the value for the property.

Parameter Modifier and Type Description

$name

string

The name of the property to create

$value

callable

A function with a context parameter, that returns the computed property value

setCustomComputedSemverProperty

public static function setCustomComputedSemverProperty($name, callable $value)
▼

Sets a computed semantic-versioned string Custom Property on the Rox client. This is a computable semantically-versioned string, with an object that generates the value for the property.

Parameter Modifier and Type Description

$name

string

The name of the property to create

$value

callable

A function with a context parameter, that returns the computed property value

setCustomComputedStringProperty

public static function setCustomComputedStringProperty($name, callable $value)
▼

Sets a custom computed string property on the Rox client. This is a computable string, with an object that generates the value for the property.

Parameter Modifier and Type Description

$name

string

The name of the property to create

$value

callable

A function with a context parameter, that returns the computed property value

setCustomBooleanProperty

public static function setCustomBooleanProperty($name, $value)
▼

Sets a custom property representing a boolean value.

Parameter Modifier and Type Description

$name

string

The name of the custom property

$value

boolean

The value for the custom property, as a boolean true or false

setCustomDoubleProperty

public static function setCustomDoubleProperty($name, $value)
▼

Sets a custom property that can store a specified double value.

Parameter Modifier and Type Description

$name

string

The property name

$value

double

The value of the property

setCustomIntegerProperty

public static function setCustomIntegerProperty($name, $value)
▼

Sets a custom property that can store a specified integer value.

Parameter Modifier and Type Description

$name

string

The property name

$value

int

The value of the property

setCustomSemverProperty

public static function setCustomSemverProperty($name, $value)
▼

Sets a custom property that uses a Semantic Version as its value. See semver.org for more information on Semantic Versioning.

Parameter Modifier and Type Description

$name

string

The name of the property to create

$value

string

The property value, formatted using the rules defined at semver.org

setCustomStringProperty

public static function setCustomStringProperty($name, $value)
▼

Sets a custom string property for the Rox client, which is a string property you can fetch by name.

Parameter Modifier and Type Description

$name

string

The name of the property to create

$value

string

The property’s value

setContext

public static function setContext(ContextInterface $context)
▼

Sets a global context. This context will be available to all flags evaluations.

fetch

public static function fetch()
▼

Creates a network request for the latest configuration.

dynamicApi

public static function dynamicApi()
▼

The returned DynamicApiInterface will create flags as if they were registered, including sending them to the dashboard. This allows you to evaluate flags without having a static container.

See also Dynamic api.

setUserspaceUnhandledErrorHandler

public static function setUserspaceUnhandledErrorHandler(callable $userspaceUnhandledErrorHandler)
▼

A handler for all user function errors, which might help you debug and understand unexpected flag values. In case this function is not set, errors will be logged to the logger.

Note: it is recommended to wrap all user methods with try-catch in order to handle it while in the relevant context, and not afterward.

getState

public static function getState()
▼

This method can be used to determine the current state of Rox framework setup. The returned integer can be one of the following:

namespace Rox\Server;

final class RoxState
{
    const Idle = 0;
    const SettingUp = 1;
    const Set = 2;
    const ShuttingDown = 3;
    const Corrupted = 4;
}
▼

Class RoxOptions

namespace Rox\Server;

class RoxOptions implements RoxOptionsInterface
▼

RoxOptions covers configuration options for the Rox client. These include settings like the verbosity of the logging. Instances of this class should be created using RoxOptionsBuilder.

Example

Here is an example of setting up a new RoxOptions object. This object sets the version, logger, provides an impression handler, and calls the fetch handler.

$options = new RoxOptions(new RoxOptions.RoxOptionsBuilder()
    ->setVersion("2.0.0")
    ->setRoxyURL("http://someUrl/")
    ->setConfigurationFetchedHandler(function (ConfigurationFetchedArgs $args) {
        //TODO: add things to do when configuration was fetch
    },
    ->setImpressionHandler(function (ImpressionArgs $args) {
        //TODO: add things to do on impression
    },
    ->setDynamicPropertiesRule(function ($propName, ContextInterface $ctx) {
        //TODO: return dynamic rule for properties
    }
    ->setLogCacheHitsAndMisses(true)
    ->setCacheStorage(new DoctrineCacheStorage(
        new ChainCache([
          new ArrayCache(),
          new FilesystemCache('/tmp/rollout/cache'),
        ])
    ))
    ->setConfigFetchIntervalInSeconds(50)
);
Rox::setup(ROLLOUT_KEY, $options);
▼

Class RoxOptionsBuilder

namespace Rox\Server;

class RoxOptionsBuilder
▼

This builder class is used to create a new RoxOptions instance.

setVersion

public function setVersion($version)
▼

Sets the version of the service running the CloudBees Feature Management SDK.

setConfigFetchIntervalInSeconds

public function setConfigFetchIntervalInSeconds($configFetchIntervalInSeconds)
▼

Sets the http request interval (in seconds) for configuration requests to stay cached and not go to the network.

setConfigurationFetchedHandler

public function setConfigurationFetchedHandler($configurationFetchedHandler)
▼

Sets the configuration event handler. Used to add actions after configurations were fetched.

setImpressionHandler

public function setImpressionHandler($impressionHandler)
▼

Sets the impression event handler. Used to add actions after a flag evaluation.

setDynamicPropertiesRule

public function setDynamicPropertiesRule(callable $dynamicPropertiesRule)`
▼

Where $dynamicPropertiesRule is a callable that accept 2 parameters:

function($propName, ContextInterface $context) {}
▼

The Dynamic Custom Property Generator is called when an explicit Custom Property definition does not exist on the client side.

If you do not set the setDynamicPropertiesRule it will then activate the default function which tries to extract the property value by calling it by name from the context.

return ($context != null) ? $context->get($propName) : null
▼

setRoxyURL

public function setRoxyURL($roxyURL)
▼

Sets a roxy URL (see Microservices automated testing and local development).

setLogCacheHitsAndMisses

public function setLogCacheHitsAndMisses($logCacheHitsAndMisses)
▼

Sets a true/false value that indicates whether to log HTTP cache requests hits/misses to the logger.

setCacheStorage

public function setCacheStorage($cacheStrategy)
▼

Cache to use in order to keep CloudBees Feature Management configurations local. Defaults to DoctrineCacheStorage, using sys_get_temp_dir().

setTimeout

public function setTimeout($time)
▼

Sets a timeout on all network requests. Time is a float in seconds. Defaults to 0 (no timeout).

Class RoxFlag

namespace Rox\Server\Flags;

class RoxFlag implements BooleanFlagInterface
▼

RoxFlag is a boolean feature flag. It can be either true or false.

isEnabled

function isEnabled($context = null)
▼

Returns true if the flag is enabled.

getName

function getName()
▼

The name of the Flag.

enabled

function enabled($context, callable $action)
▼

Executes the provided action if the flag is enabled (i.e. the flag value is true), and otherwise does nothing.

action - A callable function to execute if the RoxFlag for the feature is enabled.

disabled

function disabled($context, callable $action);
▼

Executes the provided action if the flag is disabled, otherwise does nothing.

action - A callable function to execute if the RoxFlag for the feature is disabled.

Class RoxString

namespace Rox\Server\Flags;

class RoxString implements StringFlagInterface
▼

RoxString is a feature flag object that can have values more complex than a simple boolean true or false. RoxString accepts a list of possible values for the feature flag, and a default value. This list of values will be used when selecting new values for the feature and will be available for overriding via the CloudBees Feature Management dashboard.

Example

$this->titleColorsVariant = new RoxString("Black", ["Red", "Green"]);
▼
if ($container->titleColorsVariant->getValue() == "Black")
{
    // set title color to black
}
else if ($container->titleColorsVariant->getValue() == "Green")
{
    // set title color to green
}
▼

getValue

function getValue($context = null)
▼

Returns the flag’s string value considering the given context.

getName

function getName()
▼

The name of the flag.

Class RoxInt

namespace Rox\Server\Flags;

class RoxInt implements IntFlagInterface
▼

RoxInt is a feature flag object that can have int values. RoxInt accepts a list of possible int values for the feature flag and a default value. This list of values will be used when selecting new values for the feature and will be available for an override via the dashboard.

Example

$this->fontSize = new RoxInt(10, [12, 14]);
▼
$fontSize = $container->fontSize->getValue();
▼

getValue

function getValue($context = null)
▼

Returns the flag’s string value considering the given context.

getName

function getName()
▼

The name of the flag.

Class RoxDouble

namespace Rox\Server\Flags;

class RoxDouble implements DoubleFlagInterface
▼

RoxDouble is a feature flag object that can have double values. RoxDouble accepts a list of possible double values for the feature flag, and a default value.

This list of values will be used when selecting new values for the feature and will be available for an override via the dashboard.

Example

$this->someDouble = new RoxDouble(1.1, [2.2, 3.3]);
▼
$doubleValue = $container->someDouble->getValue();
▼

getValue

function getValue($context = null)
▼

Returns the flag’s string value considering the given context.

getName

function getName()
▼

The name of the flag.

Interface ContextInterface

namespace Rox\Core\Context;

interface ContextInterface
▼

The context object is used to pass data to the flag when checking if the current flag is enabled or disabled. This object is used by the registered Custom Properties to evaluate the experiment expression and return the flag value.

You can create a context using the ContextBuilder and send a key/value map to its build function.

Example

use Rox\Core\Context\ContextBuilder;

$context = (new ContextBuilder())->build([
    "user" => $currentUser
]);
▼

get

function get($key);
▼

This get function is used to retrieve data from the context.

Example

In this example, we can see how the setCustomComputedStringProperty is using the context to get the username.

use Rox\Core\Context\ContextInterface;

Rox::setCustomComputedStringProperty("user_name", function (ContextInterface $context) {
    return $context->get("user")->getName();
});
▼

Using UserspaceUnhandledErrorHandler

Class UserspaceUnhandledErrorArgs

namespace Rox\Core\ErrorHandling;

final class UserspaceUnhandledErrorArgs
▼

getExceptionSource

Returns the user-defined source object that caused the exception. For the impression invoker handler or configuration fetched handler, the returned object is a handler function. For dynamic property and custom property rules, it is the rule function.

getExceptionTrigger

Returns integer code from the following list:

namespace Rox\Core\ErrorHandling;

final class ExceptionTrigger
{
    const DynamicPropertiesRule = 1;
    const ConfigurationFetchedHandler = 2;
    const ImpressionHandler = 3;
    const CustomPropertyGenerator = 4;
}
▼

getException

Returns the exception itself.

Example

$dynamicPropertiesRule = function ($propName, ContextInterface $context) {
    // write some custom logic
    return $context->get($propName);
};

$roxOptionsBuilder->setDynamicPropertiesRule($dynamicPropertiesRule);

Rox::setUserspaceUnhandledErrorHandler(function (UserspaceUnhandledErrorArgs $args) use ($dynamicPropertiesRule) {
    if ($args->getExceptionSource() === $dynamicPropertiesRule) {
        // add some action
    }
});
▼

For more information see User space error handler.

Using ConfigurationFetchedHandler

As seen in RoxOptions, setConfigurationFetchedHandler can be used to set the configuration fetched event handler function.

This is how the function looks:

function (ConfigurationFetchedArgs $args) {
    // function code...
}
▼

Below are the additional definitions used in this example.

ConfigurationFetchedArgs

namespace Rox\Core\Configuration;

class ConfigurationFetchedArgs
▼

getCreationDate

Reads the configuration creation date, if fetched successfully.

isHasChanges

Checks whether the last fetch contained any changes in the configuration.

getErrorDetails

Returns an integer code which can be one of the described below.

FetcherError

Numeric fetch error code.

namespace Rox\Core\Configuration;

final class FetcherError
{
    const NoError = 0;
    const CorruptedJson = 1;
    const EmptyJson = 2;
    const SignatureVerificationError = 3;
    const NetworkError = 4;
    const MismatchAppKey = 5;
    const Unknown = 6;
}
▼

getFetcherStatus

public function getFetcherStatus()
▼

Returns the numeric code of the configuration fetch status. Can be one of the following.

FetcherStatus

namespace Rox\Core\Configuration;

final class FetcherStatus
{
    const AppliedFromEmbedded = 1;
    const AppliedFromLocalStorage = 2;
    const AppliedFromNetwork = 3;
    const ErrorFetchedFailed = 4;
}
▼

For an additional information and examples, see Configuration fetched handler.

Using ImpressionHandler

The impressionHandler function (you can provide to RoxOptions) uses a few parameters and can be helpful in determining what actions should be taken after a flag evaluation.

The function signature:

function (ImpressionArgs $args)
▼

Class ImpressionArgs

namespace Rox\Core\Impression;

class ImpressionArgs
▼

getReportingValue

function getReportingValue()
▼

The returned object has 3 properties: the flag name, the value, and targeting indicating whether the flag has configurations targeting on or off.

Property Description 
 function getName()
▼

The flag name

 
 function getValue()
▼

The evaluation result

 
 function isTargeting()
▼

is targeting on or off

getContext

public function getContext()
▼

Returns the context in which the impression was called (this is a merged context containing the global context, and the call’s context).

For an example, see Impression handler.

Interface DynamicApiInterface

namespace Rox\Core\Client;

interface DynamicApiInterface
▼

An alternative to using container with Rox::register method. This allows you to evaluate flags without having a static container. DynamicApi will create flags as if they were registered, including sending them to the dashboard.

See also Dynamic api.

isEnabled

function isEnabled($name, $defaultValue, ContextInterface $context = null);
▼

Evaluate a boolean flag.

Parameter Modifier and Type Description

$name

string

The flag’s name containing optional namespace - throws an error if null.

$defaultValue

bool

The default value to use if no dashboard configurations.

$context

ContextInterface

A context to evaluate the flag with, will be merged with the global context.

getValue

function getValue($name, $defaultValue, $variations = [], ContextInterface $context = null);
▼

Evaluate a string flag.

Parameter Modifier and Type Description

$name

string

The flag’s name containing optional namespace - throws an error if null.

$defaultValue

string

The default value to use if no dashboard configurations.

$variations

array

All alternative values to use on the dashboard (can be changed on the dashboard side). Cannot contain nulls.

$context

ContextInterface

A context to evaluate the flag with, will be merged with the global context.

getInt

function getInt($name, $defaultValue, $variations = [], ContextInterface $context = null);
▼

Evaluate an integer flag.

Parameter Modifier and Type Description

$name

string

The flag’s name containing optional namespace - throws an error if null.

$defaultValue

int

The default value to use if no dashboard configurations.

$variations

array

All alternative values to use on the dashboard (can be changed on the dashboard side). Cannot contain nulls.

$context

ContextInterface

A context to evaluate the flag with, will be merged with the global context.

getDouble

function getDouble($name, $defaultValue, $variations = [], ContextInterface $context = null);
▼

Evaluate a double flag.

Parameter Modifier and Type Description

$name

string

The flag’s name containing optional namespace - throws an error if null.

$defaultValue

double

The default value to use if no dashboard configurations.

$variations

array

All alternative values to use on the dashboard (can be changed on the dashboard side). Cannot contain nulls.

$context

ContextInterface

A context to evaluate the flag with, will be merged with the global context.
Objective-C API
Python API