Initialize the PHP SDK

15 min

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.

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 configure 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 following are the required and optional parameters in the PHP SDK (client constructed using Builder class and passing to Build()) for the start method:

Parameter	Type	Description
`datafile` _optional_	string	The JSON string representing the project.
`errorHandler` _optional_	IErrorHandler	An error handler object to handle errors.
`datafileAuthToken` _optional_	string	Use an access token (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. See the [Use authenticated datafile in a secure environment](#use-authenticated-datafile-in-a-secure-environment) section.

Returns

Instantiates an instance of the Optimizely class.

Automatic datafile management (ADM)

Optimizely provides automatic 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 the 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 information.

Basic example with only SDK key

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

// access your HTTPProjectConfigManager

$configManager = $optimizelyClient->configManager;

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

Basic example with 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 lets you refresh the ProjectConfig. To update the ProjectConfig, see the following:

// 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 following table lists the required and optional parameters in PHP:

Parameter	Default	Description
sdkKey	null	Optimizely project SDK key. Required unless source URL is overridden.
url	null	URL override location used to specify custom HTTP source for the Optimizely datafile.
urlTemplate	null	Parameterized datafile URL by SDK key.
fetchOnInit	false	Boolean flag to specify if datafile fetching should start immediately, when the HTTPConfigManager is initialized.
datafile	null	Initial datafile, typically sourced from a local cached source.

Update config notifications

A notification is triggered whenever a new datafile is fetched and ProjectConfig is updated. To subscribe to these notifications, use $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 does 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 more advanced implementations, you can 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 by going to Settings>Environments. Select your secure environment, and copy the Datafile access token. The following example 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 and platform source files containing the implementation for PHP are at Optimizely.php.