Configuration

PHP SDK — Configuration

Full SDK Configuration Options

use ConvertSdk\ConvertSDK;

$sdk = ConvertSDK::create([
    'sdkKey' => '',              // either this or 'data' is required
    'sdkKeySecret' => '',        // required when using an authenticated SDK key
    'environment' => 'production',
    'dataRefreshInterval' => 300000, // config cache TTL in ms (5 minutes)
    'data' => [],                // static project configuration (alternative to sdkKey)
    'logger' => [                 // optional logging configuration
        'logLevel' => \ConvertSdk\Enums\LogLevel::Debug,
        'customLoggers' => [$psrLogger],  // array of PSR-3 LoggerInterface instances
    ],
    'cache' => $psrCache,        // optional PSR-16 CacheInterface instance (e.g., Redis, Memcached)
    'dataStore' => null,         // optional visitor data store (defaults to the PSR-16 cache above)
    'bucketing' => [
        'hash_seed' => 9999,         // MurmurHash seed
        'max_traffic' => 10000,      // max hash value (100% traffic)
        'excludeExperienceIdHash' => false, // exclude experience ID from hash input
    ],
    'events' => [
        'batch_size' => 10,          // max events per network batch
    ],
    'network' => [
        'tracking' => true,          // set false to disable tracking events
        'cacheLevel' => 'default',   // 'low' for short-lived cache (dev only)
        'source' => 'php-sdk',       // SDK source identifier
    ],
    'rules' => [
        'keys_case_sensitive' => true,
        'comparisonProcessor' => null, // allows 3rd party comparison processor
        'negation' => '!',            // negation character for rule matching
    ],
    'api' => [
        'endpoint' => [
            'config' => 'https://cdn-4.convertexperiments.com/api/v1',
            'track' => 'https://[project_id].metrics.convertexperiments.com/v1',
        ],
    ],
]);

Configuration Options Reference

Option	Type	Description
sdkKey	string	Required if not providing data. Your unique project identifier from Convert.
sdkKeySecret	string	Required when using an authenticated SDK key.
data	array|ConfigResponseData	Required if not providing sdkKey. Provide project configuration directly.
environment	string	Target environment (e.g., 'staging', 'production').
dataRefreshInterval	int	Cache TTL in milliseconds. Default: 300000 (5 minutes).
logger	array	Logging configuration with logLevel and customLoggers keys.
cache	CacheInterface	PSR-16 compatible cache. Used for config caching AND visitor data persistence. Defaults to ArrayCache (in-memory).
dataStore	object	Custom data store for visitor data. Overrides cache for visitor data if provided.
bucketing.hash_seed	int	MurmurHash3 seed. Default: 9999.
bucketing.max_traffic	int	Max hash value (100% traffic). Default: 10000.
bucketing.excludeExperienceIdHash	bool	Exclude the experience ID from the hash input. Default: false.
events.batch_size	int	Max events per tracking batch. Default: 10.
network.tracking	bool	Set false to disable tracking events. Default: true.
network.cacheLevel	string	'low' for short-lived cache (dev only). Default: 'default'.
network.source	string	SDK source identifier. Default: 'php-sdk'. Can be overridden by the VERSION environment variable.
rules.keys_case_sensitive	bool	Whether rule keys are case-sensitive. Default: true.
rules.comparisonProcessor	mixed	Allows 3rd party comparison processor. Default: null.
rules.negation	string	Negation character for rule matching. Default: '!'.
api.endpoint.config	string	CDN endpoint for fetching config. Default: 'https://cdn-4.convertexperiments.com/api/v1'.
api.endpoint.track	string	Tracking API endpoint. Default: 'https://[project_id].metrics.convertexperiments.com/v1'.

PSR Standards Integration

Config Key	PSR Standard	Interface	Default
logger.customLoggers[]	PSR-3	Psr\Log\LoggerInterface	Empty array (no custom loggers)
cache	PSR-16	Psr\SimpleCache\CacheInterface	ConvertSdk\Cache\ArrayCache (in-memory)
(auto-discovered)	PSR-18	Psr\Http\Client\ClientInterface	Auto-discovered via php-http/discovery

The cache option serves a dual purpose: it stores both the fetched project configuration (with TTL) and visitor bucketing data for cross-request persistence. See Persistent DataStore for details.

Logger Configuration

The logger config accepts an array with two keys:

Key	Type	Description
logLevel	LogLevel	The minimum log level. Default: LogLevel::Debug. One of: Trace, Debug, Info, Warn, Error, Silent.
customLoggers	array	An array of PSR-3 logger entries. Each entry is either a LoggerInterface instance or an array ['logger' => $loggerInstance, 'logLevel' => LogLevel::Info] for per-logger level overrides.

use ConvertSdk\ConvertSDK;
use ConvertSdk\Enums\LogLevel;
use Monolog\Logger;
use Monolog\Handler\StreamHandler;

$monolog = new Logger('convert');
$monolog->pushHandler(new StreamHandler('php://stderr'));

$convert = ConvertSDK::create([
    'sdkKey' => 'YOUR_SDK_KEY',
    'logger' => [
        'logLevel' => LogLevel::Debug,
        'customLoggers' => [
            $monolog,  // uses the global logLevel
            // Or with per-logger level override:
            // ['logger' => $monolog, 'logLevel' => LogLevel::Warn],
        ],
    ],
]);

Log Levels

Level	What is logged
trace	Internal method calls, config data, initialization steps
debug	Event firing, entity lookups, bucketing internals
warn	Failed HTTP requests, retry attempts, discarded batches
error	Initialization failures, config fetch errors, invalid config

Persistent DataStore

The PHP SDK uses a PSR-16 (Psr\SimpleCache\CacheInterface) cache for dual purposes:

1. Config caching — Stores the fetched project configuration with a TTL (controlled by dataRefreshInterval), avoiding redundant HTTP requests within the cache window.
2. Visitor data persistence — Stores visitor bucketing data, segments, and properties across requests when a persistent cache backend is used.

By default, the SDK uses ConvertSdk\Cache\ArrayCache, an in-memory implementation. This means bucketing decisions are lost between PHP requests. To persist data across requests, provide a PSR-16 cache backed by Redis, Memcached, or another persistent store.

Using Redis

use ConvertSdk\ConvertSDK;
use Symfony\Component\Cache\Adapter\RedisAdapter;
use Symfony\Component\Cache\Psr16Cache;

// Create a PSR-16 cache backed by Redis
$redisConnection = RedisAdapter::createConnection('redis://localhost:6379');
$psr6Cache = new RedisAdapter($redisConnection);
$cache = new Psr16Cache($psr6Cache);

$sdk = ConvertSDK::create([
    'sdkKey' => 'your-sdk-key',
    'cache' => $cache,  // PSR-16 CacheInterface
]);

Using Memcached

use Symfony\Component\Cache\Adapter\MemcachedAdapter;
use Symfony\Component\Cache\Psr16Cache;

$memcached = MemcachedAdapter::createConnection('memcached://localhost:11211');
$psr6Cache = new MemcachedAdapter($memcached);
$cache = new Psr16Cache($psr6Cache);

$sdk = ConvertSDK::create([
    'sdkKey' => 'your-sdk-key',
    'cache' => $cache,
]);

Custom DataStore

If you need a separate store for visitor data (distinct from the config cache), pass the dataStore option:

$sdk = ConvertSDK::create([
    'sdkKey' => 'your-sdk-key',
    'cache' => $configCache,      // Used for config caching
    'dataStore' => $visitorCache,  // Used for visitor data persistence
]);

When dataStore is not provided, the cache instance is used for both purposes.

How Cross-Request Persistence Works

Without a persistent cache, each PHP request creates a fresh in-memory ArrayCache. Bucketing decisions are recalculated every request, which is deterministic (same visitor ID produces same bucketing) but incurs repeated computation.

With a persistent cache (Redis, Memcached, etc.):

• The first request calculates bucketing and stores results in the cache.
• Subsequent requests for the same visitor read from the cache, skipping bucketing computation.
• If the project configuration changes, the cached config expires based on dataRefreshInterval, and a fresh config is fetched automatically.

Environment Variables

Variable	Used By	Default	Description
CONFIG_ENDPOINT	SDK runtime	https://cdn-4.convertexperiments.com/api/v1	Override the CDN endpoint used to fetch project configuration.
TRACK_ENDPOINT	SDK runtime	https://[project_id].metrics.convertexperiments.com/v1	Override the Tracking API endpoint. [project_id] is replaced at runtime.
VERSION	SDK runtime	php-sdk	Override the source identifier sent with tracking requests.

Next Steps

• Code Examples — All SDK methods with examples
• Return Types — DTOs and enums reference