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');
}

You can also pass a ConfigResponseData object directly:

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

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

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 HttpClientDiscovery::find().
2. PSR-17 factories (request factory, stream factory) are auto-discovered automatically.
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.

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. If data is provided, uses it immediately.
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