Skip to content

Experiment PHP SDK (Beta)

Official documentation for Amplitude Experiment's server-side PHP SDK implementation.

Packagist

SDK Resources

GitHub · Releases

Install

PHP version compatibility

The PHP Server SDK works with PHP 7.4+.

Install the PHP Server SDK with composer.

composer require amplitude/experiment-php-server

Remote evaluation

This SDK supports and uses remote evaluation to fetch variants for users.

Quick Start

  1. Initialize the experiment client
  2. Fetch variants for the user
  3. Access a flag's variant
<?php
// (1) Initialize the experiment client
$experiment = new \AmplitudeExperiment\Experiment();
$client = $experiment->initializeRemote('<DEPLOYMENT_KEY>');

// (2) Fetch variants for a user
$user = \AmplitudeExperiment\User::builder()
    ->deviceId('abcdefg')
    ->userId('user@company.com')
    ->userProperties(['premium' => true]) 
    ->build();
$variants = $client->fetch($user)>wait();

// (3) Access a flag's variant
$variant = $variants['FLAG_KEY'] ?? null;
if ($variant) {
    if ($variant->value == 'on') {
        // Flag is on
    } else {
        // Flag is off
    }
}

Not getting the expected variant result for your flag? Make sure your flag is activated, has a deployment set, and has users allocated.

Initialize remote evaluation

Configure the SDK to initialize on server startup. The deployment key argument you pass into the apiKey parameter must live within the same project that you send analytics events to.

<?php
initializeRemote(string $apiKey, ?RemoteEvaluationConfig $config = null): RemoteEvaluationClient
Parameter Requirement Description
apiKey required The deployment key which authorizes fetch requests and determines which flags to evaluate for the user.
config optional The client configuration used to customize SDK client behavior.

Timeout & Retry Configuration

Configure the timeout and retry options to best fit your performance requirements. 

<?php
$experiment = new \AmplitudeExperiment\Experiment();
$config = \AmplitudeExperiment\Remote\RemoteEvaluationConfig::builder()
            ->fetchTimeoutMillis(500)
            ->fetchRetries(1)
            ->fetchRetryBackoffMinMillis(0)
            ->fetchRetryTimeoutMillis(500)
            ->build();
$client = $experiment->initializeRemote('<DEPLOYMENT_KEY>', $config);

Configuration

You can configure the SDK client on initialization.

Configuration Options
Name
 Description Default Value
debug Enable additional debug logging. false
serverUrl The host to fetch variants from. https://api.lab.amplitude.com
fetchTimeoutMillis The timeout for fetching variants in milliseconds. This timeout applies to the initial request, not subsequent retries. 10000
fetchRetries The number of retries to attempt if a request to fetch variants fails. 8
fetchRetryBackoffMinMillis The minimum (initial) backoff after a request to fetch variants fails. This delay scales according to the fetchRetryBackoffScalar setting. 500
fetchRetryBackoffMaxMillis The maximum backoff between retries. If the scaled backoff becomes greater than the maximum, Experiment uses the maximum for all subsequent requests. 10000
fetchRetryBackoffScalar Scales the minimum backoff exponentially. 1.5
fetchRetryTimeoutMillis The request timeout for retrying variant fetches. 10000

EU Data Center

If you use Amplitude's EU data center, set the serverUrl option on initialization to https://api.lab.eu.amplitude.com

Fetch

Fetches variants for a user and returns the results. This function remote evaluates the user for flags associated with the deployment used to initialize the SDK client.

<?php
fetch(User $user, array $flagKeys = []): PromiseInterface
// Upon resolution of the promise, an array of variants is returned on success, an empty array is returned on failure
Parameter Requirement Description
user required The user to remote fetch variants for.
flagKeys optional Specific flags or experiments to evaluate. If empty, Amplitude evaluates all flags and experiments. 
<?php
$user = \AmplitudeExperiment\User::builder()
    ->deviceId('abcdefg')
    ->userId('user@company.com')
    ->userProperties(['premium' => true])
    ->build();
$variants = $client.fetch($user)->wait();

After fetching variants for a user, you may to access the variant for a specific flag.

<?php
$variant = $variants['FLAG-KEY'] ?? null;
if ($variant) {
    if ($variant->value == 'on') {
        // Flag is on
    } else {
        // Flag is off
    }
}

Local evaluation

Implements evaluation of variants for a user through local evaluation. If you plan to use local evaluation, you should understand the tradeoffs.

Local Evaluation Mode

The local evaluation client can only evaluate flags which are set to local evaluation mode.

Quick Start

  1. Initialize the local evaluation client.
  2. Start the local evaluation client.
  3. Evaluate a user.
<?php
// (1) Initialize the experiment client
$experiment = new \AmplitudeExperiment\Experiment();
$client = $experiment->initializeLocal('<DEPLOYMENT_KEY>');

// (2) Start the local evaluation client.
$client->start()->wait();

// (3) Evaluate a user.
$user = \AmplitudeExperiment\User::builder()
    ->deviceId('abcdefg')
    ->userId('user@company.com')
    ->userProperties(['premium' => true]) 
    ->build();

$variants = $client->evaluate($user);

Not getting the expected variant result for your flag? Make sure your flag is activated, has a deployment set, and has users allocated.

Initialize local evaluation

For more information, see Local Evaluation.

Server Deployment Key

Initialize the local evaluation client with a server deployment key to access local evaluation flag configurations.

initializeLocal(string $apiKey, ?LocalEvaluationConfig $config = null): LocalEvaluationClient
Parameter Requirement Description
apiKey required The server deployment key which authorizes fetch requests and determines which flags to evaluate for the user.
config optional The client configuration used to customize SDK client behavior.

Configuration

You can configure the SDK client on initialization.

Configuration Options

LocalEvaluationConfig

Name
 Description Default Value
debug Set to true to enable debug logging. false
serverUrl The host to fetch flag configurations from. https://api.lab.amplitude.com
bootstrap Bootstrap the client with an array of flag key to flag configuration []
assignmentConfig Configuration for automatically tracking assignment events after an evaluation. null

AssignmentConfig

Name
 Description Default Value
apiKey The analytics API key. Not to be confused with the experiment deployment key. required
cacheCapacity The maximum number of assignments stored in the assignment cache. 65536
flushQueueSize Events wait in the buffer and are sent in a batch. Experiment flushes the buffer when the number of events reaches the flushQueueSize. 200
flushMaxRetries The number of times the client retries an event when the request returns an error. 12
minIdLength The minimum length of userId and deviceId. 5
serverZone The server zone of the projects. Supports EU and US. For EU data residency, Change to EU. US
serverUrl The API endpoint URL that events are sent to. Automatically selected by serverZone and useBatch. If this field is set with a string value instead of null, then serverZone and useBatch are ignored and the string value is used. https://api2.amplitude.com/2/httpapi
useBatch Whether to use batch API. By default, the SDK will use the default serverUrl. false

EU Data Center

If you use Amplitude's EU data center, configure the serverUrl option on initialization to https://api.lab.eu.amplitude.com

Start

Fetch local evaluation mode flag configs for evaluation.

start(): PromiseInterface

Await the result of start() to ensure that flag configs are ready for use before you call evaluate()

<?php
$client->start()->wait();

Evaluate

Executes the evaluation logic using the flags fetched on start(). Give evaluate() a user object argument. Optionally pass an array of flag keys if you require only a specific subset of required flag variants.

Automatic Assignment Tracking

Set assignmentConfig to automatically track an assignment event to Amplitude when you call evaluate().

evaluate(User $user, array $flagKeys = []): array
Parameter Requirement Description
user required The user to evaluate.
flagKeys optional Specific flags or experiments to evaluate. If empty, Amplitude evaluates all flags and experiments. 
<?php
// The user to evaluate
$user = \AmplitudeExperiment\User::builder()
        ->deviceId('abcdefg')
        ->build();

// Evaluate all flag variants
$allVariants = $client->evaluate($user);

// Evaluate a specific subset of flag variants
$specificVariants = $client->evaluate($user, [
  'my-local-flag-1',
  'my-local-flag-2',
]);

// Access a flag's variant
$variant = $allVariants['FLAG_KEY'] ?? null;
if ($variant) {
    if ($variant->value == 'on') {
        // Flag is on
    } else {
        // Flag is off
    }
}

Access Amplitude cookies

If you use the Amplitude Analytics SDK on the client-side, the PHP server SDK provides an AmplitudeCookie class with convenience functions for parsing and interacting with the Amplitude identity cookie. This helps ensure that the Device ID on the server matches the Device ID set on the client, especially if the client hasn't yet generated a Device ID.

<?php
// Grab amp device id if present
$ampCookieName = AmplitudeCookie::cookieName('amplitude-api-key');
$deviceId = null;

if (!empty($_COOKIE[$ampCookieName])) {
    $parsedCookie = AmplitudeCookie::parse($_COOKIE[$ampCookieName]);
    $deviceId = $parsedCookie['deviceId'];
}

if ($deviceId === null) {
    // deviceId doesn't exist, set the Amplitude Cookie
    $deviceId = bin2hex(random_bytes(16));
    $ampCookieValue = AmplitudeCookie::generate($deviceId);
    setcookie($ampCookieName, $ampCookieValue, [
        'domain' => '.your-domain.com', // this should be the same domain used by the Amplitude JS SDK
        'httponly' => false,
        'secure' => false,
    ]);
}
Was this page helpful?