PHP API (4.9)

7 minute read

Class Rox

namespace: Rox\Server

class Rox

The Rox class provides your application with its primary interface for feature flags in the CloudBees Feature Management system. This is the central repository for your application’s flags. It handles communications with the server to obtain the latest values, implements experiment settings, and sets up configurations. It provides a mechanism through which you can use feature flags to control your application’s behavior. It works with a RoxContainer-derived object, which holds your application’s feature flags. The values contained in the provided RoxContainer will be marked as feature flags and will appear in your application’s CloudBees Feature Management dashboard 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

Register

public static function register($namespace, object $roxContainer)

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

$container

object

An object that contains your application’s feature flags

For example, assuming we have the following container:

class MyContainer
{
  public $includeFacebook;
  public $includeGithub;

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

and we register the container with the following code:

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

The flag and variant 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 set the namespace 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.

Class RoxOptions

namespace: Rox\Server

class RoxOptions implements RoxOptionsInterface

RoxOptions cover configuration options for the Rox client. These includes 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 options 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)`
$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)

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

setLogCacheHitsAndMisses

public function setLogCacheHitsAndMisses($logCacheHitsAndMisses)

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().

Class RoxFlag

namespace: Rox\Server\Flags

class RoxFlag extends Flag

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.

Class RoxVariant

namespace: Rox\Core\Entities\Variant

class RoxVariant extends Variant

RoxVariant is a feature flag object that can have values more complex than a simple boolean true or false. RoxVariant 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 override via the CloudBees Feature Management dashboard.

Example

$this->titleColorsVariant = new RoxVariant("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 variant’s value considering the given context.

getName

 function getName()

The name of the Variant.

interface ContextInterface

namespace: Rox\Core\Context

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 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
function getReportingValue()

This object has 2 properties: flag name and the value.

Property Description 
 function getName()

The flag name

 
 function getValue()

The evaluation result

 
 function getExperiment()

The experiment of the flag:

 
 function getName()

Experiment name

 
 function getIdentifier()

Experiment id (string)

 
 function isArchived()

If the experiment is archived (boolean)

 
 function getLabels()

Experiment’s Labels (string[]) Assigned on the dashboard

 
 function getContext()

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.

React Native API
C API