Disclaimer: This website requires JavaScript to function properly. Some features may not work as expected. Please enable JavaScript in your browser settings for the best experience.

Optimizely will be sunsetting Full Stack Experimentation on July 29, 2024. See the recommended Feature Experimentation migration timeline and documentation.

Dev GuideAPI Reference
Dev GuideAPI ReferenceUser GuideLegal TermsGitHubDev CommunityOptimizely AcademySubmit a ticketLog In
Dev Guide

Initialize SDK

This topic describes how to initialize the Optimizely 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 Get Enabled Features. Each client corresponds to the datafile representing the state of a project for a certain environment.

Version

SDK v3.1.0

Description

The constructor accepts a configuration object to configure Optimizely.

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

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 SDKs can use an access token (in combination with an sdkkey) to fetch the datafile from an authenticated endpoint. 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 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 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 getConfig method for retrieving 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. In order 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 project SDK key; required unless source URL is overridden.
urlnullURL override location used to specify custom HTTP source for the Optimizely datafile.
urlTemplatenullParameterized datafile URL by SDK key.
fetchOnInitfalseBoolean flag to specify if datafile fetching should start right away, 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'll 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. 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.