PHP SDK

Use perkamo/sdk from trusted PHP backends. Do not expose Perkamo server API keys to browser or mobile code.

Install

composer require perkamo/sdk

Create a client

use Perkamo\Client;

$perkamo = new Client(
    apiKey: getenv('PERKAMO_SECRET_KEY'),
);

The PHP SDK defaults to the hosted Perkamo API. Pass baseUrl only for a custom, staging or private endpoint.

Identify a customer

Use your application's stable user id as the Perkamo customer id. Send e-mail, name and internal customer metadata as trusted customer traits from backend code:

$perkamo->identify('customer_123', [
    'email' => 'customer@example.test',
    'name' => 'Customer Test',
    'crm_id' => 'crm_123',
]);

Only send non-secret facts your application is allowed to share with Perkamo. Calling identify() again updates traits for the same customer.

Emit one event

use Perkamo\EventInput;

$event = EventInput::create('customer_123', 'purchase.completed')
    ->withTransactionId('order_1092')
    ->withContextValue('order_id', 'order_1092')
    ->withContextValue('amount', 12900)
    ->withContextValue('currency', 'CZK');

$result = $perkamo->emitEvent($event);

if ($result->applied) {
    foreach ($result->delta as $delta) {
        printf("%+g %s\n", $delta->amount, $delta->wallet);
    }
}

Use stable business ids as transaction ids for retriable events. For example, use an order id for checkout events or a lesson id plus user id for learning progress events.

For simple one-off events, emit() remains available and builds the same typed event internally:

$result = $perkamo->emit(
    userId: 'customer_123',
    event: 'purchase.completed',
    context: ['order_id' => 'order_1092'],
    transactionId: 'order_1092',
);

Both emitEvent() and emit() return Perkamo\EventIngestResult, with typed properties such as $result->applied, $result->delta, $result->walletState, $result->level and toArray() for the raw API payload.

Read the event catalog

Use program() or eventCatalog() from trusted backend code when an internal admin tool needs configured event keys and labels:

$events = $perkamo->eventCatalog();

foreach ($events as $event) {
    printf("%s\n", $event['event']);
}

program() returns the active Space program blueprint, metrics and usage summary. Do not treat either method as a wallet editing API.

Handle API errors

Non-2xx responses throw Perkamo\Exception\PerkamoApiException with the HTTP status, parsed body and operational metadata when available:

use Perkamo\Exception\PerkamoApiException;

try {
    $perkamo->emit('customer_123', 'purchase.completed', transactionId: 'order_1092');
} catch (PerkamoApiException $error) {
    error_log(json_encode([
        'status' => $error->statusCode(),
        'request_id' => $error->requestId(),
        'retry_after' => $error->retryAfter(),
        'rate_limit' => $error->rateLimit(),
    ]));
}

Create a browser token

Authenticate the user in your PHP backend first, then ask Perkamo to issue a short-lived browser token for the browser SDK:

$token = $perkamo->createBrowserToken(
    browserKey: getenv('PERKAMO_BROWSER_KEY'),
    userId: 'customer_123',
    ttlSeconds: 600,
);

return new JsonResponse([
    'token' => $token->token,
    'token_type' => $token->tokenType,
    'expires_at' => $token->expiresAt->format(DATE_ATOM),
    'expires_in' => $token->expiresIn,
]);

This uses the server API key configured on Perkamo\Client; no separate browser token signing secret is needed in the customer application. Browser key access policy is configured in Perkamo and enforced server-side. The PHP SDK token request does not send scopes or event allowlists. Use * on the browser key to allow all current and future configured events. New browser keys default to the full browser SDK policy: customer reads, allowed browser events and customer streams.

Validate the integration

Use Events to confirm emitted events and Customers to inspect customer state after rules apply.

Symfony applications that need both backend event emission and browser SDK token endpoints can use Symfony Bundle.