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
apiKey
stringDefault: undefined
Your Eppo SDK key. Required for initialization.
baseUrl
stringDefault: https://eppo.cloud/api
The base URL for the Eppo API.
assignmentLogger
LoggerInterfaceDefault: null
A callback that sends each assignment to your data warehouse. Required only for experiment analysis.
Must implement the Eppo\Logger\LoggerInterface
interface.
cache
CacheInterfaceDefault: FileSystem cache
A PSR-6 compatible cache implementation for storing flag configurations.
httpClient
ClientInterfaceDefault: automatic (Discovery)
A PSR-18 compatible client interface for making http requests.
pollingOptions
PollingOptionsDefault: none
Options to configure the local cache and background polling.
requestFactory
RequestFactoryInterfaceDefault: 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:
cacheAgeLimitMillis
intDefault: 300000
Maximum age (in milliseconds) of cached configurations before they are considered stale. Defaults to 5 minutes.
pollingIntervalMillis
intDefault: 30000
Interval (in milliseconds) between polling attempts when background polling is enabled. Defaults to 30 seconds.
pollingJitterMillis
intDefault: 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"} |
More details about logging and examples (with Segment, Rudderstack, mParticle, and Snowplow) can be found in the assignment logging page.