PHP Quickstart

A copy-paste-ready guide to get the Convert PHP SDK running in under 5 minutes.

1. Install

composer require convertcom/php-sdk

The install includes Guzzle as the default PSR-18 HTTP client — no extra install is needed. To swap in a different client, see Installation → Swapping the PSR-18 Client.

2. Full Working Example

<?php

declare(strict_types=1);

use ConvertSdk\ConvertSDK;
use ConvertSdk\DTO\BucketedVariation;
use ConvertSdk\DTO\BucketedFeature;
use ConvertSdk\DTO\ConversionAttributes;
use ConvertSdk\DTO\GoalData;
use ConvertSdk\Enums\FeatureStatus;
use ConvertSdk\Enums\GoalDataKey;

// 1. Initialize the SDK
$sdk = ConvertSDK::create([
    'sdkKey' => 'your-sdk-key',
]);

// 2. Verify the SDK is ready
if (!$sdk->isReady()) {
    die('SDK failed to initialize');
}

// 3. Create a visitor context
$context = $sdk->createContext('visitor-123', [
    'country' => 'US',
    'plan'    => 'premium',
]);

// 4. Run an experience
/** @var BucketedVariation|null $variation */
$variation = $context->runExperience('homepage-redesign');

if ($variation !== null) {
    echo "Experience: {$variation->experienceKey}\n";
    echo "Variation:  {$variation->variationKey}\n";
}

// 5. Resolve a feature flag
/** @var BucketedFeature|null $feature */
$feature = $context->runFeature('dark-mode');

if ($feature !== null && $feature->status === FeatureStatus::Enabled) {
    $theme = $feature->variables['theme'] ?? 'dark';
    echo "Dark mode theme: {$theme}\n";
}

// 6. Track a conversion with revenue
$context->trackConversion('purchase-completed', new ConversionAttributes(
    conversionData: [
        new GoalData(GoalDataKey::Amount, 49.99),
        new GoalData(GoalDataKey::TransactionId, 'txn-abc-123'),
    ],
));

// Events auto-flush on shutdown in PHP-FPM, or flush manually:
$sdk->flush();

Key Points

Synchronous: The PHP SDK is fully synchronous. There is no onReady() Promise. The SDK is ready immediately after ConvertSDK::create() returns.
isReady(): Always check $sdk->isReady() before creating contexts.
ConvertSDK is a static factory: Use ConvertSDK::create() — the constructor is private and cannot be called directly.
Auto-flush: In PHP-FPM environments, queued tracking events flush automatically on shutdown. In CLI scripts, call $sdk->flush() explicitly.

Next Steps

Installation — PSR requirements and dependency details
Initialization — SDK Key vs. static config, PSR discovery
Configuration — Full config options reference
Code Examples — All SDK methods with examples
Return Types — DTOs and enums reference