Initialization

The Eppo PHP SDK is easy to initialize while offering robust customization options, making it adaptable to various use cases such as custom caching requirements and background polling, exposing PSR-6/17, PSR-17, and PSR-18 interfaces.

Initialize the SDK

To complete basic initialization, you only need to provide an SDK key. Create an SDK key if you don't already have one.

use Eppo\EppoClient;

require __DIR__ . '/vendor/autoload.php';

$eppoClient = EppoClient::init("<your_sdk_key>");

Advanced Configuration

The SDK provides several optional parameters during initialization to customize its behavior:

Initialization Options

apiKeystringDefault: undefined

Your Eppo SDK key. Required for initialization.

baseUrlstringDefault: https://eppo.cloud/api

The base URL for the Eppo API.

assignmentLoggerLoggerInterfaceDefault: null

A callback that sends each assignment to your data warehouse. Required only for experiment analysis. Must implement the Eppo\Logger\LoggerInterface interface.

cacheCacheInterfaceDefault: FileSystem cache

A PSR-6 compatible cache implementation for storing flag configurations.

httpClientClientInterfaceDefault: automatic (Discovery)

A PSR-18 compatible client interface for making http requests.

pollingOptionsPollingOptionsDefault: none

Options to configure the local cache and background polling.

requestFactoryRequestFactoryInterfaceDefault: automatic (Discovery)

A PSR-18 compatible client interface for making http requests.

PollingOptions Configuration

The PollingOptions object allows you to configure caching and background polling behavior with the following parameters:

cacheAgeLimitMillisintDefault: 300000

Maximum age (in milliseconds) of cached configurations before they are considered stale. Defaults to 5 minutes.

pollingIntervalMillisintDefault: 30000

Interval (in milliseconds) between polling attempts when background polling is enabled. Defaults to 30 seconds.

pollingJitterMillisintDefault: 5000

Random jitter (in milliseconds) added to the polling interval to prevent synchronized polling across multiple instances. Defaults to 5 seconds.

Configuration Caching

To avoid making a fetch request for every assignment, the SDK caches the configuration, re-fetching it when the cache expires. By default, it uses a filesystem cache, but you can provide your own PSR-6 compatible cache implementation as showin in the example below. You can also change the age limit of the cache.

use Symfony\Component\Cache\Adapter\RedisAdapter;

$cache = new RedisAdapter($redisConnection);

$pollingOptions = new PollingOptions(
    cacheAgeLimitMillis: 5 * 60 * 1000 // 5 minutes
);

$eppoClient = EppoClient::init(
   "<your_sdk_key>",
   null,
   $assignmentLogger,
   $cache,
   pollingOptions: $pollingOptions
);

Background Polling

A unique feature of the PHP SDK is its ability to poll for configuration updates in a background process. This ensures your application always has fresh configurations without blocking requests.

Create a dedicated poller file (e.g. eppo-poller.php):

$pollingOptions = new PollingOptions(
    pollingIntervalMillis: 10000,
    pollingJitterMillis: 2000
);

$eppoClient = EppoClient::init(
   "<your_sdk_key>",
   "<base_url>",
   $assignmentLogger,
   $cache,
   pollingOptions: $pollingOptions
);

$eppoClient->startPolling();

Run this as a separate process:

php eppo-poller.php

Reloading Configuration as a Cron Job

You can force a refresh of your Eppo configuration data by calling the fetchAndActivateConfiguration method as in the example below:

<?php

require __DIR__ . '/../vendor/autoload.php';

use Eppo\EppoClient;
use Eppo\Exception\EppoClientException;

try {
    $eppoClient = EppoClient::init(apiKey: "<your sdk key>", isGracefulMode: false);
    $eppoClient->fetchAndActivateConfiguration();
} catch (EppoClientException $e) {
    print ($e->getMessage());
}

Assignment Logger

For experiment analysis, implement the LoggerInterface:

<?php

use Eppo\Logger\LoggerInterface;

class Logger implements LoggerInterface {
  public function logAssignment(AssignmentEvent $assignmentEvent) {
    // Implement your logging logic here
  }
}

The logger receives these parameters:

Field	Description	Example
experiment (string)	An Eppo experiment key	"recommendation-algo-allocation-17"
subject (string)	An identifier of the subject or user assigned to the experiment variation	UUID
variation (string)	The experiment variation the subject was assigned to	"control"
timestamp (string)	The time when the subject was assigned to the variation	2021-06-22T17:35:12.000Z
subjectAttributes (map)	A free-form map of metadata about the subject	{ "country": "US" }
featureFlag (string)	An Eppo feature flag key	"recommendation-algo"
allocation (string)	An Eppo allocation key	"allocation-17"
allocation (string)	An Eppo allocation key	"allocation-17"
sdkMetadata (map)	SDK version of other SDK metadata	{ "sdkName": "php", "sdkVersion": "1.0.0" }
extraLogging (map)	Freeform map of additional data to log	{"appVer":"5.0.9","cluster":"a4"}

note

More details about logging and examples (with Segment, Rudderstack, mParticle, and Snowplow) can be found in the assignment logging page.