This guide provides detailed information about our PHP Thin SDK. All of our SDKs are open source. Go to our PHP Thin SDK GitHub repository to learn more.
Language support
The PHP Thin SDK supports PHP language version 7.3 and later.
Architecture
The PHP Thin SDK depends on the Split Daemon (splitd) which should be set up on the same host. The PHP Thin SDK client uses splitd to maintain the local cached copy of the Split rollout plan and return feature flag evaluations.
Initialization
1. Import the SDK into your project
composer require splitsoftware/thin-sdk:1.0.0
The public release of the PHP Thin SDK is available at packagist.org.
2. Set up the splitd service
When the composer is done, follow the guidance of our Split Daemon (splitd) doc to integrate splitd into your application infrastructure.
3. Instantiate the SDK and create a new split client
We recommend instantiating the SDK once as a singleton and reusing it throughout your application, as demonstrated below.
<?php
require_once '../vendor/autoload.php';
use \SplitIO\ThinSdk\Factory;
$factory = Factory::withConfig([
'transfer' => ['address' => 'path/to/socket/file.sock'],
'logging' => ['level' => \Psr\Log\LogLevel::INFO],
]);
$client = $factory->client();
Using the SDK
Basic use
After you instantiate the SDK client, you can start using the getTreatment
method of the SDK client to decide what version of your features your customers are served. The method requires the FEATURE_FLAG_NAME
attribute that you want to ask for a treatment and a unique key
attribute that corresponds to the end user that you want to serve the feature to.
From there, you simply need to use an if-else-if block as shown below and insert the code for the different treatments that you defined in the Split user interface. Remember the final else branch in your code to handle the client returning the control treatment.
<?php
// The key here represents the ID of the user/account/etc you're trying to evaluate a treatment for
$treatment = $client->getTreatment('key', 'bucketingKey', 'FEATURE_FLAG_NAME', null);
if ($treatment === 'on') {
// insert code here to show on treatment
} elseif ($treatment === 'off') {
// insert code here to show off treatment
} else {
// insert your control treatment code here
}
Shutdown
Due to the nature of PHP and the way HTTP requests are handled, the client is instantiated on every request, and automatically wiped when the request lifecycle comes to an end. The data is synchronized by an external tool and stored in memory, so the SDK client does not need to invoke any shutdown tasks.
Multiple evaluations at once
In some instances, you may want to evaluate treatments for multiple feature flags at once. Use the getTreatments
method of the Split client to do this. Pass a list of the feature flags names you want treatments for and the method returns the proper treatments in the form of an associative array, where each key of the associative array is the name of the string and the value is the resulting treatment.
$treatments = $client->getTreatments('key', 'bucketingKey', ['FEATURE_FLAG_NAME_1', 'FEATURE_FLAG_NAME_2'], null);
echo json_encode($treatments);
Attribute syntax
To target based on custom attributes, the SDK's getTreatment
method needs to pass an attribute map at runtime.
In the example below, we are rolling out a feature flag to users. The provided attributes plan_type
, registered_date
, permissions
, paying_customer
, and deal_size
are passed to the getTreatment
call. These attributes are compared and evaluated against the attributes used in the rollout plan as defined in the Split Web Console to decide whether to show the on
or off
treatment to this account.
The getTreatment
method supports five types of attributes: strings, numbers, dates, booleans, and sets. The proper data type and syntax for each are:
- Strings: Use type String.
- Numbers: Use type Integer.
- Dates: Express the value in
seconds since epoch
. Use a timestamp represented by an Integer. - Booleans: Use type Boolean.
- Sets: Use type Array.
<?php
$attributes["plan_type"] = "growth";
$attributes["registered_date"] = (new DateTime("now", new DateTimeZone("UTC")))->getTimestamp();
$attributes["deal_size"] = 10000;
$attributes["paying_customer"] = True;
$attributes["permissions"] = array("gold","silver","platinum");
$treatment = $client->getTreatment('key', 'bucketingKey', 'FEATURE_FLAG_NAME', $attributes);
if ($treatment === 'on') {
// insert code here to show on experience
} elseif ($treatment === 'off') {
// insert code here to show off experience
} else {
// insert your control treatment code here to show no reporting
}
Get Treatments with Configurations
Coming soon.
Track
Coming soon.
Configuration
With the SDK architecture, there is a set of options that you can configure to get everything connected and working as expected.
Option | Description |
---|---|
transfer | IPC socket parameters (type, address, timeouts) |
logging | Logging parameters |
utils | Instance of an impression listener to send impression data to a custom location |
<?php
$sdkConfig = [
'transfer' => ['address' => '/var/run/splitd.sock'],
'logging' => ['psr-instance' => $myLogger],
];
$splitFactory = \SplitIO\ThinSdk\Factory::withConfig($sdkConfig);
$splitClient = $splitFactory->client();
Impressions data
By default, the SDK sends small amounts of information to the Split backend indicating the reason for each treatment returned from a feature flag. An example would be that a user saw the on
treatment because they are in segment all
.
Manager
Coming soon.
Listener
Split SDKs send impression data back to Split servers periodically when evaluating feature flags. To send this information to a location of your choice, define an impression listener. Use the impressionListener
parameter, where you can provide an implementation of an ImpressionListener
. This implementation must define the accept
method, with the signature public function accept(Impression $impression, ?array $attributes)
and with parameters as defined below.
Name | Type | Description |
---|---|---|
impression | SplitIO\ThinSdk\Models\Impression | Impression object that has the feature name, treatment result, label, etc. |
attributes | ?array | A list of attributes passed by the client. |
Implement a custom impression listener
Here is an example of how to implement a custom impression listener.
use \SplitIO\ThinSdk\Utils\ImpressionListener;
use \SplitIO\ThinSdk\Models\Impression;
class CustomListener implements ImpressionListener
{
public function accept(Impression $i, ?array $a)
{
echo "got an impression for: key=".$i->getKey()
." feat=".$i->getFeature()
." treatment=".$i->getTreatment()
." label=".$i->getLabel()
." cn=".$i->getChangeNumber()
." #attrs=".(($a == null) ? 0 : count($a))."\n";
}
}
Attach a custom impression listener
Here is an example of how to attach a custom impression listener.
$sdkConfig = [
'transfer' => ['address' => '/var/run/splitd.sock'],
'logging' => ['psr-instance' => $myLogger],
'utils' => ['impressionListener' => new \App\Utils\CustomListener()], # <-- custom listener
];
$splitFactory = \SplitIO\ThinSdk\Factory::withConfig($sdkConfig);
$splitClient = $splitFactory->client();
Logging
The Split SDK provides a custom logger that implements the PSR-3 standard. By default, the SDK logs to stdout at the INFO log level. To configure the logger, set the adapter and the desired log level.
Production environments
For production environments, we strongly recommend passing a proper psr-instance
parameter with a PSR3 compliant logger (or custom wrapper for a non-cmpliant one).
<?php
$sdkConfig = [
'logging' => ['level' => \Psr\Log\LogLevel::DEBUG],
);
$splitFactory = \SplitIO\ThinSdk\Factory::withConfig($sdkConfig);
$splitClient = $splitFactory->client();
The log configuration parameters are described below.
Configuration | Description | Default value |
---|---|---|
level | The log level message. According the PSR-3 standard the supported levels are:
|
|
psr-instance | Your custom logger instance that implements the PSR-3 standard | null |
Custom logging
You can integrate a third-party logger to format logging or to push logging info to a configurable location.
Zend logger
The Zend logger can be integrated with the SDK as shown below.
<?php
$zendLogLogger = new Zend\Log\Logger;
$psrLogger = new Zend\Log\PsrLoggerAdapter($zendLogLogger);
/** SDK options */
$sdkConfig = [
'logging' => ['psr-instance' => $psrLogger],
];
/** Create the Split Client instance. */
$splitFactory = \SplitIO\ThinSdk\Factory::withConfig($sdkConfig);
$splitClient = $splitFactory->client();
Monolog
Monolog sends your logs to files, sockets, inboxes, databases, and various web services. See the complete list of handlers in the Monolog documentation.
The following is a demonstration of Monolog integration for the SDK.
<?php
use Monolog\Logger;
use Monolog\Handler\StreamHandler;
/** create a log channel */
$psrLogger = new Logger('SplitIO');
$psrLogger->pushHandler(new StreamHandler('path/to/your.log', Logger::WARNING));
/** SDK options */
$sdkConfig = [
'logging' => ['psr-instance' => $psrLogger],
];
/** Create the Split Client instance. */
$splitFactory = \SplitIO\ThinSdk\Factory::withConfig($sdkConfig);
$splitClient = $splitFactory->client();
Comments
0 comments
Please sign in to leave a comment.