origamy / php-sdk
PHP SDK for the Origamy analytics API
Requires
- php: ^8.2
- ramsey/uuid: ^4.7
Requires (Dev)
- phpunit/phpunit: ^10.5
Suggests
None
Provides
None
Conflicts
None
Replaces
None
This package is auto-updated.
Last update: 2026-10-22 16:00:09 UTC
README
composer require origamy/php-sdk
Requires PHP 8.2+.
Usage
Basic Usage
<?php use Origamy\AnalyticsClient; use Origamy\Config; use Origamy\Messages\Track; [$client, $err] = AnalyticsClient::newWithConfig( getenv('ORIGAMY_WRITE_KEY'), new Config(), ); if ($err !== null) { throw $err; } $client->enqueue(new Track( event: 'Signed Up', userId: 'user-123', )); $client->close();
The client automatically flushes any pending messages when the PHP process exits (via a registered shutdown function), so an explicit close() call is only needed when you want to guarantee delivery before the script continues.
Message Types
All six Segment-compatible message types are supported:
use Origamy\Messages\Track; use Origamy\Messages\Identify; use Origamy\Messages\Page; use Origamy\Messages\Screen; use Origamy\Messages\Group; use Origamy\Messages\Alias; use Origamy\Properties; use Origamy\Traits as OrigamyTraits; // Track an action $client->enqueue(new Track( event: 'Order Completed', userId: 'user-123', properties: (new Properties()) ->set('orderId', 'ORD-9999') ->setRevenue(99.99) ->setCurrency('USD'), )); // Identify a user with traits $client->enqueue(new Identify( userId: 'user-123', traits: (new OrigamyTraits()) ->setEmail('alice@example.com') ->setName('Alice Smith') ->set('plan', 'pro'), )); // Track a page view $client->enqueue(new Page( userId: 'user-123', name: 'Pricing', properties: (new Properties()) ->set('url', 'https://example.com/pricing') ->set('title', 'Pricing Plans'), )); // Track a mobile screen view $client->enqueue(new Screen( userId: 'user-123', name: 'Dashboard', properties: (new Properties())->set('tab', 'overview'), )); // Associate a user with a group/company $client->enqueue(new Group( groupId: 'company-acme', userId: 'user-123', traits: (new OrigamyTraits()) ->setName('Acme Corp') ->setWebsite('https://acme.com'), )); // Alias an anonymous ID to an identified user $client->enqueue(new Alias( previousId: 'anon-session-abc', userId: 'user-123', ));
Anonymous Users
Pass anonymousId instead of (or in addition to) userId for anonymous tracking:
$client->enqueue(new Track( event: 'Page Scrolled', anonymousId: 'anon-browser-xyz', properties: (new Properties())->set('depth', 75), ));
Configuration
Configuration is passed as a Config object to newWithConfig:
use Origamy\AnalyticsClient; use Origamy\Config; [$client, $err] = AnalyticsClient::newWithConfig('your-write-key', new Config( endpoint: 'https://events.origamy.io', batchSize: 100, verbose: true, ));
Development Mode (Noop Dispatcher)
For local development, use NoopDispatcher to log events to the console instead of sending them:
use Origamy\AnalyticsClient; use Origamy\Config; use Origamy\Dispatcher\DispatcherConfig; use Origamy\Dispatcher\NoopDispatcher; use Origamy\Messages\Track; use Origamy\Properties; $dispatcher = new NoopDispatcher(new DispatcherConfig(verbose: true)); [$client, $err] = AnalyticsClient::newWithConfig('your-write-key', new Config( dispatcher: $dispatcher, )); $client->enqueue(new Track( event: 'button_clicked', userId: 'user-123', properties: (new Properties())->set('button', 'signup'), )); $client->close();
Custom Queue
use Origamy\Config; use Origamy\Queue\InMemoryQueue; [$client, $err] = AnalyticsClient::newWithConfig('your-write-key', new Config( queue: new InMemoryQueue(capacity: 1000), ));
Custom Dispatcher
Implement the DispatcherInterface for custom transport:
use Origamy\Dispatcher\DispatcherInterface; interface DispatcherInterface { public function send(string $payload): void; public function close(): void; }
use Origamy\Config; use Origamy\Dispatcher\DispatcherInterface; class MyGrpcDispatcher implements DispatcherInterface { public function send(string $payload): void { // Send via gRPC } public function close(): void {} } [$client, $err] = AnalyticsClient::newWithConfig('your-write-key', new Config( dispatcher: new MyGrpcDispatcher(), ));
Success / Failure Callbacks
use Origamy\CallbackInterface; use Origamy\Config; use Origamy\MessageInterface; class MyCallback implements CallbackInterface { public function success(MessageInterface $message): void { // Message delivered successfully } public function failure(MessageInterface $message, \Throwable $error): void { error_log('Delivery failed: ' . $error->getMessage()); } } [$client, $err] = AnalyticsClient::newWithConfig('your-write-key', new Config( callback: new MyCallback(), ));
Full Configuration
use Origamy\AnalyticsClient; use Origamy\Config; use Origamy\StdLogger; [$client, $err] = AnalyticsClient::newWithConfig('your-write-key', new Config( endpoint: 'https://events.origamy.io', batchSize: 250, verbose: true, logger: new StdLogger(), queueCapacity: 500, retryAfter: fn (int $attempt) => min(100 * 2 ** $attempt, 10_000), )); if ($err !== null) { throw $err; }
List Segment Members
A list (manual) segment can be filled by naming people. SegmentsClient takes a
secret key (sk_) — public keys are refused — and its calls are synchronous:
use Origamy\Exceptions\SegmentException; use Origamy\SegmentsClient; $segments = new SegmentsClient(getenv('ORIGAMY_SECRET_KEY')); try { $result = $segments->addMembers(42, [ ['email' => 'jane@example.com', 'traits' => ['first_name' => 'Jane']], ['phone' => '0803 123 4567'], ['userId' => 'user-42'], ], phoneRegion: 'NG'); echo $result->added, ' added; rejected: ', json_encode($result->rejected), "\n"; $segments->removeMembers(42, [['email' => 'old@example.com']]); } catch (SegmentException $e) { if ($e->errorCode === 'segment_not_list') { // the segment is computed from conditions and can't take people by name } throw $e; }
Each added person goes through the event pipeline as an identify: someone new becomes a profile, and segment-entered journeys start, normally within seconds. Removals apply before the call returns and start segment-exited journeys.
Lists longer than 1000 rows are sent in several requests and their results
combined; each rejected row's index is its position in the array you passed.
If a later request fails, $e->result holds what the earlier ones did. Requests
that are rate limited (429) or find the service unavailable (503) are retried up
to 3 times. The constructor takes endpoint, timeoutSeconds and retryAfter.
Publishing
Prerequisites
- Write access to the
origamy/php-sdkpackage on Packagist - Packagist API token or webhook configured on the repository
Steps
1. Update the version constant in src/Config.php:
public const VERSION = '3.0.1';
2. Run tests to confirm everything passes:
composer test
3. Commit and tag the release following semver with a v prefix:
git add . git commit -m "release: v3.0.1" git tag v3.0.1 git push origin main --tags
Packagist picks up new tags automatically if a webhook is configured. Otherwise trigger a manual update:
4. (Optional) Trigger a Packagist update via the API:
curl -XPOST -H 'content-type:application/json' \ "https://packagist.org/api/update-package?username=YOUR_USER&apiToken=YOUR_TOKEN" \ -d '{"repository":{"url":"https://github.com/qubely/origamy-php-sdk"}}'
Once the tag is published, the new version is available via:
composer require origamy/php-sdk:^3.0.1
Useful Commands
composer install # Install dependencies (vendor/ is git-ignored; it was committed until 2026-09) composer test # Run the full test suite ./vendor/bin/phpunit # Run tests directly ./vendor/bin/phpunit --group http # Run HTTP integration tests only
HTTP Wire Format
Events are batched and sent as a single HTTP POST to /v1/batch. The request body follows the same format as the Origamy Web SDK:
{
"batch": [
{
"type": "track",
"messageId": "uuid",
"userId": "user-123",
"event": "Order Completed",
"timestamp": "2024-01-15T10:30:00Z",
"properties": { "revenue": 99.99 },
"context": {
"library": { "name": "origamy-php", "version": "3.0.0" }
}
}
],
"sentAt": "2024-01-15T10:30:00.123Z"
}
Context is attached per-event (not at the batch level). sentAt uses ISO 8601 with milliseconds, matching new Date().toISOString() from the Web SDK.
Authentication uses HTTP Basic Auth with the write key as the username and an empty password.
Flush Behaviour
PHP is single-threaded, so there is no background goroutine or interval timer. Messages are flushed:
- Automatically when the batch size is reached (default: 250 messages).
- On
close()— call this before the script exits to guarantee delivery. - On shutdown — a
register_shutdown_functionflushes any remaining messages when the PHP process ends normally.
Available Configuration
| Option | Type | Description |
|---|---|---|
endpoint |
string |
API endpoint URL |
batchSize |
int |
Max messages per batch |
dispatcher |
DispatcherInterface |
Custom dispatcher (HTTP, Noop, gRPC, etc.) |
queue |
QueueInterface |
Custom message queue |
queueCapacity |
int |
Capacity for the default in-memory queue |
verbose |
bool |
Enable verbose logging |
logger |
LoggerInterface |
Custom logger |
callback |
CallbackInterface |
Success/failure delivery callbacks |
defaultContext |
Context |
Default context merged into every message |
retryAfter |
callable(int): int |
Retry delay in ms; receives the attempt index |
Defaults
| Setting | Default |
|---|---|
| Endpoint | https://events.origamy.io |
| Batch size | 250 messages |
| Queue capacity | 100 messages |
| Request timeout | 10 seconds |
| Retry attempts | 10 (exponential backoff) |
License
The library is released under the MIT license.