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 |
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.
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).
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.
getValue
function getValue($context = null)
Returns the variant’s value considering the given context.
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.
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 |
---|---|
|
The flag name |
|
The evaluation result |
|
The experiment of the flag: |
|
Experiment name |
|
Experiment id (string) |
|
If the experiment is archived (boolean) |
|
Experiment’s Labels (string[]) Assigned on the dashboard |
|
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.