eppo / php-sdk
Eppo PHP SDK
Installs: 13 179
Dependents: 0
Suggesters: 0
Security: 0
Stars: 8
Watchers: 7
Forks: 2
Open Issues: 0
Requires
- php: ^8.1
- ext-json: *
- composer/semver: ^3.4
- php-http/discovery: ^1.17
- psr/simple-cache: 3.*
- shrikeh/teapot: ^2.3
- symfony/cache: ^6.4
- webclient/ext-redirect: ^2.0
Requires (Dev)
- ext-pcntl: *
- ext-posix: *
- ext-sockets: *
- google/cloud-storage: ^1.30
- phpunit/phpunit: ^9.6
- psr-mock/http: ^1.0
- squizlabs/php_codesniffer: ^3.10
- dev-main
- v3.2.1
- v3.2.0
- 3.1.0
- 3.0.0
- 1.2.3
- 1.2.2
- 1.2.1
- 1.2.0
- 1.1.0
- 1.0.1
- 1.0.0
- dev-tp/action/branch
- dev-tp/makefail
- dev-tp/bandits/readme
- dev-tp/bandits/e2e
- dev-tp/bandit/eveneval
- dev-leoromanovsky-patch-1
- dev-lr/ff-953/try
- dev-catchup-upstream-121
- dev-lr/ff-1018/one-request
- dev-lr/ff-888/no-guzzle
- dev-lr/ff-962/php-sdk-name
- dev-docs-link-fix
- dev-pavel/upgrade-composer-version
- dev-pavel/improve-request-timeout
- dev-pavel/ANA-182-php-sdk
This package is auto-updated.
Last update: 2024-10-03 18:27:19 UTC
README
Eppo is a modular flagging and experimentation analysis tool. Eppo's PHP SDK is built to make assignments in multi-user server side contexts, compatible with PHP 7.3 and above. Before proceeding you'll need an Eppo account.
Features
- Feature gates
- Kill switches
- Progressive rollouts
- A/B/n experiments
- Mutually exclusive experiments (Layers)
- Dynamic configuration
- Multi-armed Contextual Bandits
Installation
composer require eppo/php-sdk
Quick start
Begin by initializing a singleton instance of Eppo's client. Once initialized, the client can be used to make assignments anywhere in your app.
Initialize once
<?php use Eppo\EppoClient; require __DIR__ . '/vendor/autoload.php'; $eppoClient = EppoClient::init( '<your_api_key>', '<base_url>', // optional, default https://fscdn.eppo.cloud/api $assignmentLogger, // optional, must be an instance of Eppo\Logger\LoggerInterface $cache // optional, must be an instance of PSR-16 SimpleCache\CacheInterface. If not passed, FileSystem cache will be used $httpClient // optional, must be an instance of PSR-18 ClientInterface. If not passed, Discovery will be used to find a suitable implementation $requestFactory // optional, must be an instance of PSR-17 Factory. If not passed, Discovery will be used to find a suitable implementation );
Assign anywhere
$subjectAttributes = [ 'tier' => 2 ]; $assignment = $eppoClient->getStringAssignment('experimentalBackground', 'user123', $subjectAttributes, 'defaultValue'); if ($assignment !== 'defaultValue') { // do something }
Select a Bandit Action
This SDK supports Multi-armed Contextual Bandits.
$subjectContext = [ 'age' => 30, // Gets interpreted as a Numeric Attribute 'country' => 'uk', // Categorical Attribute 'pricingTier' => '1' // NOTE: Deliberately setting to string causes this to be treated as a Categorical Attribute ]; $actionContexts = [ 'nike' => [ 'brandLoyalty' => 0.4, 'from' => 'usa' ], 'adidas' => [ 'brandLoyalty' => 2, 'from' => 'germany' ] ]; $result = $client->getBanditAction( 'flagKey', 'subjectKey', $subjectContext, $actionContexts, 'defaultValue' ); if ($result->action != null) { // Follow the Bandit action doAction($result->action); } else { doSomething($result->variation); }
Assignment functions
Every Eppo flag has a return type that is set once on creation in the dashboard. Once a flag is created, assignments in code should be made using the corresponding typed function:
getBooleanAssignment(...) getNumericAssignment(...) getIntegerAssignment(...) getStringAssignment(...) getJSONAssignment(...)
Each function has the same signature, but returns the type in the function name. For booleans use getBooleanAssignment
, which has the following signature:
function getBooleanAssignment( string $flagKey, string $subjectKey, array $subjectAttributes, bool $defaultValue ): bool
Initialization options
The init
function accepts the following optional configuration arguments.
Assignment logger
To use the Eppo SDK for experiments that require analysis, pass in an implementation of the LoggerInterface
to the init
function on SDK initialization. The SDK invokes the callback to capture assignment data whenever a variation is assigned. The assignment data is needed in the warehouse to perform analysis.
The code below illustrates an example implementation of a logging callback using Segment, but you can use any system you'd like. The only requirement is that the SDK receives a logAssignment
callback function. Here we define an implementation of the Eppo AssignmentLogger
interface containing a single function named logAssignment
:
<?php use Eppo\Logger\LoggerInterface; use Eppo\Logger\AssignmentEvent; use Eppo\Logger\LoggerInterface; class SegmentLogger implements LoggerInterface { public function logAssignment(AssignmentEvent $assignmentEvent): void { Segment::track([ 'event' => 'Flag Assignment for ' . $assignmentEvent->featureFlag, 'userId' => $assignmentEvent->subject, 'properties' => $assignmentEvent->toArray() ]); } }
Bandit Action Logging
When using Bandits, a different logging method is called. Your logging class must implement IBanditLogger
instead of LoggerInterface
.
<?php use Eppo\Logger\AssignmentEvent; use Eppo\Logger\BanditActionEvent; use Eppo\Logger\IBanditLogger; class SegmentLogger implements IBanditLogger { public function logAssignment(AssignmentEvent $assignmentEvent): void { Segment::track([ 'event' => 'Flag Assignment for ' . $assignmentEvent->featureFlag, 'userId' => $assignmentEvent->subject, 'properties' => $assignmentEvent->toArray() ]); } public function logBanditAction(BanditActionEvent $banditActionEvent): void { Segment::track([ 'event' => 'Bandit Action Selected', 'userId' => $banditActionEvent->subjectKey, 'properties' => $banditActionEvent->toArray() ]); } }
Background Polling
To make the experience of using the library faster, there is an option to start a background polling for randomization params. This background job will start calling the Eppo API, updating the config in the cache.
For this, create a file, e.g. eppo-poller.php
with the contents:
$eppoClient = EppoClient::init( '<your_api_key>', '<base_url>', // optional, default https://fscdn.eppo.cloud/api $assignmentLogger, // optional, must be an instance of Eppo\LoggerInterface $cache // optional, must be an instance of PSR-16 SimpleInterface. If not passed, FileSystem cache will be used $httpClient // optional, must be an instance of PSR-18 ClientInterface. If not passed, Discovery will be used to find a suitable implementation $requestFactory // optional, must be an instance of PSR-17 Factory. If not passed, Discovery will be used to find a suitable implementation ); $eppoClient->startPolling();
after this, run this script by:
php eppo-poller.php
This will start an indefinite process of polling the Eppo-api.
Troubleshooting
HTTP
This package uses the php-http/discovery
package to automatically locate implementations of the various HTTP related
PSR interfaces (ex: ClientInterface
, RequstFactory
, etc.). If your project does not depend on any library which can
fulfill this need, you may see an exception such as follows.
Fatal error: Uncaught Http\Discovery\Exception\DiscoveryFailedException: Could not find resource using any discovery strategy.
To solve this, simply require a suitable package, such as guzzle
composer require guzzlehttp/guzzle:^7.0
Philosophy
Eppo's SDKs are built for simplicity, speed and reliability. Flag configurations are compressed and distributed over a global CDN (Fastly), typically reaching your servers in under 15ms. Server SDKs continue polling Eppo’s API at 30-second intervals. Configurations are then cached locally, ensuring that each assignment is made instantly. Evaluation logic within each SDK consists of a few lines of simple numeric and string comparisons. The typed functions listed above are all developers need to understand, abstracting away the complexity of the Eppo's underlying (and expanding) feature set.