PHP Thin Client SDK

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.

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

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.

<?php
$sdkConfig = [
   'logging' => ['level' => \Psr\Log\LogLevel::DEBUG],
);

$splitFactory = \SplitIO\ThinSdk\Factory::withConfig($sdkConfig);
$splitClient = $splitFactory->client();

The log configuration parameters are described below.

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