Initialization

Key difference from the JavaScript SDK: The PHP SDK is fully synchronous. There is no onReady() Promise. The SDK is ready to use immediately after ConvertSDK::create() returns. Use isReady() to verify initialization succeeded.

ConvertSDK::create() Factory

ConvertSDK is a static factory. Use ConvertSDK::create() — the constructor is private and cannot be called directly.

use ConvertSdk\ConvertSDK;

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

Using SDK Key (Remote Config Fetch)

The SDK fetches the project configuration from Convert's CDN and caches it using the provided PSR-16 cache.

use ConvertSdk\ConvertSDK;

$sdk = ConvertSDK::create([
    'sdkKey' => 'your-sdk-key',
    'sdkKeySecret' => 'xxx',  // required when using an authenticated SDK key
    'environment' => 'staging',
    'dataRefreshInterval' => 300000, // in milliseconds (5 minutes)
]);

if ($sdk->isReady()) {
    // SDK is ready — create a user context and run experiences
    $context = $sdk->createContext('visitor-123');
}

Using Static Configuration

Provide a project configuration array directly. The config data can be fetched from https://cdn-4.convertexperiments.com/api/v1/config/{account_id}/{project_id}.

use ConvertSdk\ConvertSDK;

$sdk = ConvertSDK::create([
    'data' => [/* your static project configuration array */],
    'environment' => 'staging',
]);

if ($sdk->isReady()) {
    $context = $sdk->createContext('visitor-123');
}

A raw array is wrapped in a ConfigResponseData for you — the shape is the CDN config response:

$sdk = ConvertSDK::create([
    'data' => [
        'account_id' => '100123456',
        'project' => [
            'id' => '10045678',
            // ... full project config
        ],
    ],
]);

You can also pass an already-constructed OpenAPI\Client\Model\ConfigResponseData instance instead of the array.

You must provide either sdkKey or data. If both are missing, an InvalidArgumentException is thrown.

QA Debug Token

Passing a debugToken widens the config fetch to every non-archived experience (drafts and paused ones included) and bypasses the config cache entirely:

$sdk = ConvertSDK::create([
    'sdkKey'     => 'your-sdk-key',
    'debugToken' => 'your-qa-debug-token',
]);

See Configuration → QA Debug Token for the full behaviour and the production warning.

Checking Readiness

if ($sdk->isReady()) {
    echo "Convert SDK is ready!\n";
    // Now you can start creating contexts for visitors
}

isReady() returns true when the SDK has successfully fetched and processed configuration data.

PSR Discovery

The SDK auto-discovers PSR-18 HTTP client and PSR-17 request/stream factories using php-http/discovery. During ConvertSDK::create():

1. PSR-18 HTTP client is auto-discovered via Http\Discovery\Psr18ClientDiscovery::find().
2. PSR-17 factories (request factory, stream factory) are auto-discovered via Http\Discovery\Psr17FactoryDiscovery.
3. PSR-16 cache defaults to ConvertSdk\Cache\ArrayCache (in-memory) if not provided.

No adapter code is needed — install any PSR-18 compliant client and the SDK finds it automatically. When discovery finds nothing, ConvertSDK::create() throws a RuntimeException telling you to install a client (e.g. guzzlehttp/guzzle ^7).

What Happens Under the Hood

When you call ConvertSDK::create($config):

1. Configuration — The SDK reads the $config array and sets defaults for any options not specified.
2. PSR Discovery — Auto-discovers PSR-18 HTTP client and PSR-17 factories.
3. Manager Creation — Creates internal managers: LogManager, EventManager, ApiManager, DataManager, RuleManager, BucketingManager, ExperienceManager, FeatureManager, SegmentsManager.
4. Data Persistence Wiring — If a PSR-16 cache is provided, it is wired as the visitor data store automatically.
5. Initialization — If sdkKey is present, fetches config from Convert's CDN, reading and writing the PSR-16 config cache along the way (both are skipped when debugToken is set). If data is provided, it is validated and used immediately with no fetch.
6. Shutdown Handler — register_shutdown_function is registered to flush pending tracking events when the PHP script ends. In PHP-FPM, it calls fastcgi_finish_request() first so the response is sent before flushing.
7. Ready State — isReady() returns true.

Next Steps

• Configuration — Full SDK config options reference
• Code Examples — All SDK methods with examples