Check access from your backend

Use the PHP library to decide, on your server, whether a customer may use a feature. The check asks Voidhash for the customer's active perk grants, so nothing a customer reaches through your API depends on a client-side decision. Set up the PHP library with a secret key first.

Check a perk

hasActivePerk answers one question: does this customer hold an active grant for this perk? The handler below gates an export route on the premium perk.

$app->get("/reports/export", function (Request $request, Response $response) {
    $hasPremium = $voidhash->persons->entitlements->hasActivePerk([
        "distinctId" => $request->getAttribute("user_id"),
        "perkSlug" => "premium",
    ]);

    if (!$hasPremium) {
        return $response->withStatus(402)->withJson(["error" => "premium_required"]);
    }

    return $response->withJson(buildExport($request->getAttribute("user_id")));
});

distinctId is the same identifier your app passed to identify(). Pass exactly one of perkId or perkSlug. If you pass both or neither, the call throws Voidhash\Exception\ApiException with the code configuration_error before any request is made.

Read the grants yourself

hasActivePerk only returns a boolean. When you need to render an account page, show an expiry date, or branch on where access came from, read the grants directly. They are every perk the customer can use now.

$grants = $voidhash->persons->entitlements->grantsByDistinctId("user_123");

Each grant has these fields, each read with its getter, such as getPerkId().

Unlike hasActivePerk, this call treats an unknown distinctId as an error. That leaves the decision to you: whether "never seen" and "seen, but bought nothing" should mean the same thing.

The same lookup is available as two separate calls, which helps when you already hold the person's id. getByDistinctId returns null for an unknown distinctId.

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

$entitlements = $voidhash->persons->getEntitlements($person->getId());

Person is intentionally thin. It carries id, distinctId, email, name and isIdentified, because it identifies the customer. It does not describe what they paid for.

Handle errors deliberately

When an API call fails, the library throws Voidhash\Exception\ApiException carrying the API's error body. Branch on getType() and getErrorCode(), never on the message. getParam() names the field at fault, getStatus() is the HTTP status, and getRequestId() identifies the request when you contact support. Transport failures (DNS, TLS, timeouts) throw the HTTP client's PSR-18 Psr\Http\Client\ClientExceptionInterface instead.

The example below treats an unknown person as "no access", treats a bad key as your own bug, rethrows every other API error, and treats an unreachable API as an unknown answer.

use Psr\Http\Client\ClientExceptionInterface;
use Voidhash\Exception\ApiException;

try {
    $grants = $voidhash->persons->entitlements->grantsByDistinctId("user_123");

    foreach ($grants as $grant) {
        if ($grant->getPerkId() === $premiumPerkId) {
            return true;
        }
    }
    return false;
} catch (ApiException $error) {
    if ($error->getErrorCode() === "person_not_found") {
        // Never identified from a client: nothing was ever bought.
        return false;
    }
    if (in_array($error->getType(), ["unauthenticated", "permission_denied"], true)) {
        // Our key is wrong. Our bug, not the customer's. Do not lock them out.
        throw new RuntimeException("Voidhash secret key is invalid or lacks access.");
    }
    throw $error;
} catch (ClientExceptionInterface) {
    // Unknown, not "no access": serve the last known good value or fail the request.
    throw new RuntimeException("Voidhash is unreachable.");
}

The types you are most likely to see are unauthenticated (401), permission_denied (403), not_found (404, such as person_not_found) and invalid_request (400, with getParam() naming the field).

Live and development data

Grants are scoped to an environment. The server picks the scope from the x-environment request header.

Sandbox purchases count as production so that TestFlight, Google Play testers, and App Review get access in your published app. A project can turn that off. Then no key or x-environment value returns store sandbox grants.

The library never sends this header for you, so a plain client always reads production grants. To read development purchases, create a second client that sets the header.

$voidhashDevelopment = VoidhashClient::create(
    getenv("VOIDHASH_SECRET_KEY"),
    ["headers" => ["x-environment" => "development"]],
);

Secret keys are not scoped to an environment. Which key you use does not change the answer. Only the header does.

Caching and failures

The library does not cache, retry, or de-duplicate. Every call is a live HTTP round trip.

If you check access on every request, cache the result yourself for a short window and refresh it in the background. 60 seconds is a reasonable starting point. A PSR-6 or PSR-16 cache pool works well here. Keep the TTL short enough that a revoked grant expires from the cache quickly.

When a call fails with a transport error or a 5xx, treat the answer as unknown, not as no access. Serve the last known good value, or fail the request. Revoking a paying customer's access because of a network blip is worse than serving a slightly stale cache.

To keep the cache warm without polling, subscribe to webhooks and invalidate the cached entry when a subscription or purchase event arrives for that person.

Next steps

• Receive webhooks
• Persons in the API reference