README

This project is heavily inspired by Graham Campbell's packages; Bitbucket and GitLab.

Installation

This package requires PHP 7.3 or PHP 8.x. To get started, require the project using Composer. You will also need to install packages that provide psr/http-client-implementation and psr/http-factory-implementation.

Standard Installation

composer require "checkmango/php-sdk:^2.0" "guzzlehttp/guzzle:^7.2" "http-interop/http-factory-guzzle:^1.0"

Laravel Installation

composer require "checkmango/laravel:dev-master" "guzzlehttp/guzzle:^7.2" "http-interop/http-factory-guzzle:^1.0"

Usage

$client = new Checkmango\Client();
$client->authenticate('your_api_token');

$organizations = $client->organizations()->list();
$organization = $client->organizations($organizationId);
$config = $organization->config();
$experiment = $organization->experiments()->show('EXPERIMENT_KEY');

// Enroll the participant and track an impression for the selected variant.
$organization->ingest()->store('EXPERIMENT_KEY', 'PARTICIPANT_KEY', 'VARIANT_KEY');

// Track a conversion, optionally supplying a revenue value.
$organization->ingest()->store('EXPERIMENT_KEY', 'PARTICIPANT_KEY', 'VARIANT_KEY', 'EVENT_KEY');
$organization->ingest()->store('EXPERIMENT_KEY', 'PARTICIPANT_KEY', 'VARIANT_KEY', 'REVENUE_EVENT', 29.95);

Organization IDs are numeric; experiments, variants, events, features, and participants are addressed by their keys. Ingestion is asynchronous: a successful request returns an empty array after the API accepts it with HTTP 202. Select a variant before ingesting; the experiment must be running.

Organizations and account

$organization = $client->organizations($organizationId)->show();
$organization = $client->organizations()->show($organizationId);
$currentOrganization = $client->currentOrganization();
$user = $client->user();
$health = $client->health(); // Does not require authentication.

Experiments, events, and variants

$organization = $client->organizations($organizationId);
$organization->events()->create('PURCHASE', ['type' => 'count', 'is_revenue' => true]);
$organization->experiments()->create('CHECKOUT', ['event_key' => 'PURCHASE']);
$organization->experiments()->variants('CHECKOUT')->create(['key' => 'CONTROL', 'control' => true]);
$organization->experiments()->variants('CHECKOUT')->create(['key' => 'BLUE', 'control' => false]);
$organization->experiments()->start('CHECKOUT');
$statistics = $organization->experiments()->variants('CHECKOUT')->statistics('BLUE', ['event_key' => 'PURCHASE']);
$organization->experiments()->stop('CHECKOUT');

These resources also provide list, show, update, and remove. Pass query options such as include, filter, sort, and per_page in the parameter array for reads. Experiment statistics are available once analysis has produced a result.

Feature flags

$features = $client->organizations($organizationId)->features();
$features->create('NEW_CHECKOUT', ['enabled' => true, 'value' => 'blue', 'format' => 'text']);
$feature = $features->show('NEW_CHECKOUT');
$features->update('NEW_CHECKOUT', ['enabled' => false]);
$features->remove('NEW_CHECKOUT');

Feature values support text format. Organization config includes feature values and features_revision. To revalidate cached config, supply If-None-Match to config([], ['If-None-Match' => $etag]). Read the ETag and status through $client->getLastResponse(); a 304 returns an empty array, so retain your cached config.

Participants and attributes

$participants = $client->organizations($organizationId)->participants();
$participants->create(['key' => 'CUSTOMER_123', 'notes' => 'Example participant']);
$participant = $participants->show('CUSTOMER_123');
$attributes = $participants->attributes('CUSTOMER_123');
$attributes->update([['key' => 'plan', 'value' => 'pro']]);
$attributes->list();
$attributes->remove('plan');
$attributes->remove(); // Removes all attributes.

$participants->experiments('CUSTOMER_123')->list();
$participants->experiments('CUSTOMER_123')->show('CHECKOUT');
$participants->experiments('CUSTOMER_123')->remove('CHECKOUT');

Participant resources expose blocked and blocked_at in their attributes. The SDK returns JSON:API data as arrays, preserving resource attributes and relationships. Validation exceptions expose field messages through $exception->errors.

Example with Pager

ResultPager retrieves results across multiple pages using the API's per_page parameter.

$pager = new Checkmango\ResultPager($client, 50);
$experiments = $pager->fetchAll($client->organizations($organizationId)->experiments(), 'list');

Migrating existing integrations

• Use organizations($organizationId) to access organization resources through /api/organizations. The former team-named methods and classes have been removed.
• Existing create($key, $params) calls for events and experiments now POST to the collection URL with key in the body.
• Prefer ingest()->store(...) for enrollment and impressions. The legacy experiment enrol / enroll helpers require ['variant' => 'VARIANT_KEY']; participant experiment create requires ['experiment' => 'EXPERIMENT_KEY', 'variant' => 'VARIANT_KEY']. These helpers now use ingestion and return an empty array on HTTP 202. Variant impression also uses ingestion. Additional parameters on these legacy helpers are not forwarded.
• Use list as the method name with ResultPager; there is no all method.

Security

If you discover a security vulnerability within this package, please email James Brooks at james@checkmango.com. All security vulnerabilities will be promptly addressed. You may view our full security policy here.

License

Checkmango PHP SDK is licensed under The MIT License (MIT).