Dev guideAPI Reference
Dev guideAPI ReferenceUser GuideGitHubNuGetDev CommunitySubmit a ticketLog In
GitHubNuGetDev CommunitySubmit a ticket

Initialize the PHP SDK

How to initialize the Optimizely Feature Experimentation PHP SDK in your application.

Use the instantiate method to initialize the PHP SDK and instantiate an instance of the Optimizely client class that exposes API methods like Decide methods. Each client corresponds to the datafile representing the state of a project for a certain environment. The datafile is accessible through OptimizelyConfig.

Version

SDK v3.1.0 and higher

Description

The constructor accepts a configuration object to configure Optimizely Feature Experimentation.

Some parameters are optional because the SDK provides a default implementation, but you may want to override these for your production environments. For example, you may want to set up an error handler and logger to catch issues, an event dispatcher to manage network calls, and a User Profile Service to ensure sticky bucketing.

Parameters

The table below lists the required and optional parameters in PHP (client constructed using Builder class and passing to Build()) for the start method:

ParameterTypeDescription
datafile
optional
stringThe JSON string representing the project.
errorHandler
optional
IErrorHandlerAn error handler object to handle errors.
access_token
optional
string(Server-side only) Optimizely Feature Experimentation SDKs can use an access token (in combination with an SDK key) to fetch an authenticated datafile. Find your datafile access token in the Optimizely app at Settings > Environments. Select your secure environment, and copy the Datafile access token.

Returns

Instantiates an instance of the Optimizely class.

Automatic datafile management (ADM)

Optimizely Feature Experimentation provides out-of-the-box functionality to dynamically manage datafiles (configuration files) on either the client or the server. The PHP SDK provides default implementations of ProjectConfigManagerInterface.

You can use OptimizelyFactory method to create an Optimizely client using your SDK key and an optional fallback datafile. Using this method internally creates an HTTPProjectConfigManager. See HttpProjectConfigManager for further detail.

Basic example using only SDK key

$optimizelyClient = OptimizelyFactory::createDefaultInstance($sdkKey);

// access your HTTPProjectConfigManager

$configManager = $optimizelyClient->configManager;

You can instantiate the Optimizely Feature Experimentation PHP SDK with the default configuration of HttpProjectConfigManager.

Basic example using HTTPProjectConfigManager

$configManager = new HTTPProjectConfigManager($sdkKey);
$optimizely = new Optimizely(
  $datafile, 
  null, 
  null, 
  null, 
  false, 
  null, 
  $configManager, 
  $notificationCenter
);

ProjectConfigManagerInterface exposes the getConfig method for retrieving the ProjectConfig instance.

HTTPProjectConfigManager

HTTPProjectConfigManager is an implementation of ProjectConfigManagerInterface interface.

The fetch method makes a blocking HTTP GET request to the configured URL to download the project datafile and initialize an instance of the ProjectConfig.

Advanced example

$configManager = new HTTPProjectConfigManager(
  $sdkKey,
  $url,
  $urlTemplate,
  $fetchOnInit,
  $datafile
);

$optimizely = new Optimizely(
  $datafile,
  null, 
  null, 
  null, 
  false, 
  null, 
  $configManager, 
  $notificationCenter
);

The fetch method allows you to refresh the ProjectConfig. To update the ProjectConfig, you can do something like:

// Call fetch to retrieve an up-to-date-datafile.
$configManager->fetch();
// Now the Optimizely instance has the latest version of the datafile.

SDK key

The SDK key is used to compose the outbound HTTP request to the default datafile location on the Optimizely CDN.

Parameters

The table below lists the required and optional parameters in PHP.

ParameterDefaultDescription
sdkKeynullOptimizely Feature Experimentation project SDK key; required unless source URL is overridden.
urlnullURL override location used to specify custom HTTP source for the Optimizely Feature Experimentation datafile.
urlTemplatenullParameterized datafile URL by SDK key.
fetchOnInitfalseBoolean flag to specify if datafile fetching should start immediately, as soon as the HTTPConfigManager is initialized.
datafilenullInitial datafile, typically sourced from a local cached source.

Update config notifications

A notification will be triggered whenever a new datafile is fetched and ProjectConfig is updated. To subscribe to these notifications, use the $notificationCenter->addNotificationListener();.

$notificationCenter->addNotificationListener(
   NotificationType::OPTIMIZELY_CONFIG_UPDATE,
   $updateCallback
);

Example

You can instantiate with a hard-coded datafile. If you do not pass in an SDK key, the Optimizely Client will not automatically sync newer versions of the datafile. Any time you retrieve an updated datafile, just re-instantiate the same client.

For simple applications, all you need to provide to instantiate a client is a datafile specifying the project configuration for a given environment. For most advanced implementations, you will want to customize the logger or error handler for your specific requirements.

$template = "https://cdn.optimizely.com/datafiles/%s.json";

$configManager = new HTTPProjectConfigManager('QBw9gFM8oTn7ogY9ANCC1z', null, $template, true, null, false, null, null);

$optimizelyClient  = new Optimizely($datafile, null, null, null, false, null, $configManager);

Notes

Enable JSON schema validation

Skipping JSON schema validation enhances performance during instantiation. In the PHP SDK, you have control over whether to validate the JSON schema of the datafile when instantiating the client. This example shows how to skip JSON schema validation:

// Skip JSON schema validation
$optimizelyClient = new Optimizely($datafile);

Use authenticated datafiles in secure environments

You can fetch the Optimizely datafile from an authenticated endpoint using a server-side (only) Optimizely SDK, like the PHP SDK.

To use an authenticated datafile, download your Optimizely environment's access token from the Optimizely app at Settings>Environments. Select your secure environment, and copy the Datafile access token. The example below shows how to initialize the Optimizely client using an access token and sdkKey, enabling the client to fetch the authenticated datafile and complete initialization.

// fetch the datafile from an authenticated endpoint
use Optimizely\OptimizelyFactory;

$sdkKey = '<YOUR_SDK_KEY>';
$datafileAuthToken = '<YOUR_DATAFILE_ACCESS_TOKEN>';

$optly = OptimizelyFactory::createDefaultInstance($sdkKey, null, $datafileAuthToken);

Source files

The language/platform source files containing the implementation for PHP are at Optimizely.php.