Persons and events — Voidhash Docs

Create and update persons, capture events, describe groups and send push notifications from PHP.

PHP code for persons, events and push notifications, using a configured client.

Persons

Create a person

use Voidhash\Generated\Core\Model\CreatePersonBodyJsonEncoding;

$person = $voidhash->persons->create(
    (new CreatePersonBodyJsonEncoding())
        ->setDistinctId('user_123')
        ->setEmail('ada@example.com')
        ->setName('Ada'),
);

echo $person->getId(); // person_…

getEmail() and getName() can return null.

Find a person

getByDistinctId returns null for an unknown distinct ID:

$person = $voidhash->persons->getByDistinctId('user_123');

get throws an ApiException (person_not_found) for an unknown or erased ID.

$person = $voidhash->persons->get('person_k2v9x4m8q1r3');

getEntitlements takes the same ID, and list returns every person in the project.

Update attributes

setAttributes sets attributes and creates the person when the distinct ID is new.

$voidhash->persons->setAttributes([
    'distinctId' => 'user_123',
    'traits' => ['plan' => 'team', 'seats' => 5],
    'setOnce' => ['signupSource' => 'website'],
]);

Capture events

eventCapture->capture takes timestamp as a DateTimeInterface.

Create the client with 'ingestUrl' => 'https://api.voidhash.com'; the default capture host doesn't answer yet.

$voidhash->eventCapture->capture([
    'distinctId' => 'user_123',
    'event' => 'report_exported',
    'timestamp' => new DateTimeImmutable(),
    'properties' => ['format' => 'csv', 'rows' => 1200],
]);

eventCapture->batch sends an array in one request:

$result = $voidhash->eventCapture->batch([
    ['distinctId' => 'user_123', 'event' => 'trial_reminder_sent', 'timestamp' => new DateTimeImmutable()],
    ['distinctId' => 'user_456', 'event' => 'trial_reminder_sent', 'timestamp' => new DateTimeImmutable()],
]);

echo $result['accepted'], ' accepted, ', $result['rejected'], ' rejected';

Errors throw an ApiException whose getErrorCode() is an event capture code.

Groups

Groups are what your users belong to, such as their company. Name an event's groups with groups, by group type; they are sent as its $groups property:

$voidhash->eventCapture->capture([
    'distinctId' => 'user_123',
    'event' => 'report_exported',
    'timestamp' => new DateTimeImmutable(),
    'groups' => ['company' => 'acme'],
]);

eventCapture->groupIdentify sets a group's properties, such as what your backend knows of a company's plan and seats. setOnce fills only properties the group has no value for, and a later change of a property wins. timestamp defaults to now.

$voidhash->eventCapture->groupIdentify([
    'groupType' => 'company',
    'groupKey' => 'acme',
    'properties' => ['name' => 'Acme', 'plan' => 'pro', 'seats' => 40],
    'setOnce' => ['first_plan' => 'trial'],
]);

The $groupidentify event it sends belongs to no person.

Send push notifications

Early access

Push notifications are in early access. Ask us on Discord, or email support@voidhash.com on a paid plan, to turn them on for your team.

notifications->send sends no idempotency key, so a retry after a timeout can notify twice.

use Voidhash\Generated\Core\Model\CreatePushNotificationBodyJsonEncoding;

$sent = $voidhash->notifications->send(
    (new CreatePushNotificationBodyJsonEncoding())
        ->setDistinctIds(['user_123'])
        ->setTitle('Your trial ends tomorrow')
        ->setBody('Keep Pro for $9.99 a month.')
        ->setData(['screen' => 'paywall']),
);

echo $sent->getId(), ' ', $sent->getDeviceCount();

The optional setters are setSound, setBadge, setPriority, setTtlSeconds, setChannelId and setCollapseId; see Send a push.

Next steps