Experiment PHP SDK

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

Install¶

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.

<?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);

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

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

Configuration¶

You can configure the SDK client on initialization.

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 = []): array<Variant>
// An array of variants is returned on success, an empty array is returned on failure

<?php
$user = \AmplitudeExperiment\User::builder()
    ->deviceId('abcdefg')
    ->userId('user@company.com')
    ->userProperties(['premium' => true])
    ->build();
$variants = $client->fetch($user);

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.

<?php
// (1) Initialize the experiment client
$experiment = new \AmplitudeExperiment\Experiment();
$client = $experiment->initializeLocal('<DEPLOYMENT_KEY>');

// (2) Fetch flags for the local evaluation client.
$client->refreshFlagConfigs();

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

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

Initialize local evaluation¶

For more information, see Local Evaluation.

initializeLocal(string $apiKey, ?LocalEvaluationConfig $config = null): LocalEvaluationClient

Configuration¶

You can configure the SDK client on initialization.

refreshFlagConfigs¶

Fetch up-to-date local evaluation mode flag configs for evaluation.

refreshFlagConfigs(): void

Call refreshFlagConfigs() to ensure that flag configs are up-to-date before you use evaluate()

<?php
$client->refreshFlagConfigs();

getFlagConfigs¶

Return flag configs currently used in the client.

getFlagConfigs(): array

Flag configs returned can be used to reduce start up time by bootstrapping the local evaluation client.

<?php
$client->getFlagConfigs();

Evaluate¶

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

evaluate(User $user, array $flagKeys = []): array

<?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
    }
}

Assignment tracking¶

You can configure the local evaluation client to send assignment events to Amplitude.

AssignmentTrackingProvider¶

The local evaluation client uses an assignment tracking provider to send assignment events to Amplitude. Amplitude provides a default assignment tracking provider, but this is best used for testing due to its synchronous nature. Amplitude recommends that you use a custom provider for increased flexibility and performance.

<?php
interface AssignmentTrackingProvider {
  public function track(Assignment $assignment): void;
}

The local evaluation client calls track() when it determines there are untracked assignment events. It compares the resulting assignment from evaluate() with the assignment cache and tracks it if it's not in the cache.

DefaultAssignmentTrackingProvider¶

The default assignment tracking provider is a basic implementation of the interface which uses the internal Amplitude package to send assignment events through synchronous HTTP requests.

<?php
class DefaultAssignmentTrackingProvider implements AssignmentTrackingProvider {
  public function __construct(Amplitude $amplitude);
}

<?php
$config = \AmplitudeExperiment\Amplitude\AmplitudeConfig::builder()
          ->useBatch(true)
          ->minIdLength(10)
          ->build();
$amplitude = new \AmplitudeExperiment\Amplitude\Amplitude('<API_Key>', $config);
$defaultAssignmentTrackingProvider = new \AmplitudeExperiment\Assignment\DefaultAssignmentTrackingProvider($amplitude);

Custom Logger¶

Local and remote evaluation clients can be configured to use a custom logger which implements the PSR logger interface, otherwise a default error_log-based logger is used.

Log level¶

The following log levels are used by the SDK:

Custom HTTP Client¶

Local and remote evaluation clients can be configured to use a custom HTTP client which implements the HttpClientInterface, otherwise a default Guzzle-based HTTP client is used.

HttpClientInterface¶

GuzzleHttpClient¶

The default Guzzle client can be configured via the guzzleClientConfig option in RemoteEvaluationConfig and LocalEvaluationConfig.

<?php
// Configure the default Guzzle client
$config = \AmplitudeExperiment\RemoteEvaluationConfig::builder()
          ->guzzleClientConfig(['timeoutMillis' => 5000, 'retries' => 10])
          ->build();

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,
    ]);
}