Download the PHP package shieldlabs/shieldlabs-php without Composer

ShieldLabs PHP SDK

Read ShieldLabs identification verdicts on your PHP backend, verify webhooks and turn Risk Scores into decisions.

ShieldLabs identifies visitors with device intelligence and scores every identification from 300+ risk signals. New to ShieldLabs? Start free and read the documentation.

How it fits

1. Browser. The ShieldLabs agent (loaded with @shieldlabs-ai/js or one of the framework packages) runs an identification and hands your page a requestId. The browser never sees a Risk Score or a device ID.
2. Your backend (this SDK). The page sends the requestId with the protected action (signup, login, checkout). Your backend reads the verdict for it from the History API, or receives it in a signed identification.scored webhook.
3. Decision. Your backend acts on the Risk Score, the risk band, the detection flags and the identifiers (for example: how many accounts one device ID has used).

Install

Requirements: PHP 8.1 or newer, and ext-curl unless your project already has Guzzle 7 or Symfony HttpClient (see HTTP client and timeouts).

Keys come from the ShieldLabs analytics dashboard at app.shieldlabs.ai. Keep all three on the server (the browser only ever uses the Public Key):

Quick start

Save this as signup.php next to your vendor/ folder. It reads the verdict for the requestId your frontend sent with the form, then decides:

Try it with php -S localhost:8000 signup.php and a request ID from your browser integration: curl -X POST localhost:8000 -d requestId=<requestId>. With the placeholder key the SDK logs a warning that the key does not look like a Private API Key; use your own key.

Verify a webhook delivery (webhook.php):

A complete runnable app is in examples/.

Guide

Waiting for the verdict

Scoring is asynchronous. The History row of an identification appears about 1-3 seconds after the browser call and can be refined for up to about 10 seconds while follow-up checks finish. Start the identification in the browser when the user begins the action (for example with identifyOnInteraction() from @shieldlabs-ai/js, which starts it when the signup form gets focus), not when the form is submitted, so the verdict is usually stored by the time your backend asks for it. identifications->get() polls for the row and returns the first version it sees. Its timeout option (10 seconds by default) is the total time budget of the call:

• Schedule. The first poll runs at once. The SDK then waits 250 ms, 500 ms, 1 s, 1.5 s and then 2 s between polls, and the last poll runs when the budget ends. With another poll_interval p the waits are p, 2p, 4p, 6p and then 8p, each at most 2 seconds, or at most p when p is longer: a 1-second interval waits 1, 2, 2, 2 seconds, and a 3-second interval polls every 3 seconds.
• One request per poll. Each poll is a single HTTP request without retries of its own. It may take the time left in the budget, but at least 1 second and never longer than the client's timeout.
• Temporary errors keep the wait going. After a 429, a 5xx response, a connection error or a timeout, the SDK polls again on the same schedule. If the last poll fails, its exception is thrown when the budget ends: RateLimitException, ServerException, ApiConnectionException or ApiTimeoutException.
• Rate limits. Inside the wait, a 429 is always followed by at least 1 second before the next poll: the SDK takes the longest of the next wait of the schedule, 1 second and Retry-After (up to 10 seconds). Retry-After: 0 or a date in the past counts as 0, so it still waits 1 second. A wait that would pass the end of the budget is cut short, and the last poll runs then. When Retry-After (up to 10 seconds) asks for more than the time left, the RateLimitException is thrown at once. Calls outside the wait (history->search(), history->iterate() and 'wait' => false) follow Retry-After as sent (see Errors and retries).
• Errors that stop at once. Any other error, such as a 400, 401, 403 or 404, ends the wait at once and is thrown: a wrong request, key or base URL does not heal.
• null means the last poll found no identification for that request ID. Treat it as unverified, never as clean.

The limit per poll applies to the built-in CurlClient, whether the SDK created it or you passed it, and to the Guzzle or Symfony HttpClient that the SDK creates. Another PSR-18 client that you pass as http_client keeps its own timeout (PSR-18 has no way to change it per request), so with such a client the call can end up to one request timeout after the budget.

null also covers an identification that was never stored: when a visitor's IP goes over the per-IP limit of identifications, the browser still receives a request ID, but no row is written for it.

With 'wait' => false the SDK makes one lookup, with the client's timeout and the usual retries. To read the refined version of a row, for example to log the final risk signals, make such a lookup again after about 10 seconds.

The agent also runs background identifications on its own (on clicks and navigation). Their request IDs never reach your page, so the History API can show extra rows for the same visitor. Always look up the request ID that arrived with the action.

Deciding

An Identification carries:

• risk_score: 0-100. A value above 100 (999) is the rate-limit marker, never a score.
• the risk band from $identification->riskBand() or Risk::band($score): trusted 0-29, suspicious 30-59, dangerous 60-100, plus RiskBand::RateLimited for the marker.
• detection_flags: 19 stable booleans such as vpn, proxy, tor, anti_detect_browser and browser_automation.
• signals: the weighted risk signals behind the score, for display and logging.

Branch on the score, the band and the flags. Signal names are an open set and weights can be negative, so never add them up yourself.

Risk::evaluate() runs the guard checks from our integration guides. The first failing check gives the reason:

Defaults: max_age 300, block_bands [RiskBand::Dangerous], block_flags ['browser_automation', 'javascript_disabled']. They are a starting point; tune them per protected action. For example, a login could ask for a second factor on the suspicious band:

Storing used request IDs

Pass is_replay so that one identification authorizes one action. The SDK stores nothing itself: record each request ID in your database with a unique key, and treat a duplicate-key error as "already used". Keep the rows a little longer than max_age, for example one day: older identifications are refused as stale anyway.

PDO throws exceptions by default since PHP 8.0. With Redis, SET shieldlabs:used:<request ID> 1 NX EX 86400 does the same in one command: a null reply means the request ID was used before.

Searching history for account-abuse checks

Lookup types: ip (dotted IPv4), user_hid, visitor_id, request_id, device_id, session_id and cookie_id. The SDK checks every lookup before sending it: an unknown type, a malformed UUID, an IPv6 address, an empty User HID or a limit outside 1-100 throws ValidationException and sends nothing.

A User HID is sent as one URL path segment in canonical form, so values with @, +, = or spaces (an email address, a base64 string) match exactly. A value that contains /, and the values . and .., cannot be searched and throw ValidationException. User HIDs from UserHid::fromUserId() are 64 hex characters and always work.

history->iterate() returns a lazy generator over every row. It pages with offset, skips rows it already returned (paging while new rows arrive can repeat a row) and stops at the total, at an empty page or after max_items rows (with 'max_items' => 0 it yields nothing and sends no request):

Look up LookupType::UserHid to count the devices behind one account, or LookupType::Ip for one address. Each page is one request, so keep the rate limit below in mind.

Linking identifications to your users

Pass a User HID to the browser agent instead of a raw email or database ID, and compute it on the server:

The result is HMAC-SHA256 as 64 lowercase hex characters: stable for a user and irreversible. Keep the secret on the server; changing it changes every User HID.

Webhooks

• Verify the raw body: file_get_contents('php://input') in plain PHP, $request->getContent() in Laravel and Symfony. Never verify JSON that you decoded and encoded again: the server escapes & as \u0026 and the bytes would differ.
• The header is X-Shield-Signature: sha256=<hex>, the HMAC-SHA256 of the raw body keyed with the full signing secret, whsec_ prefix included.
• To rotate a secret without downtime, pass both: Webhook::constructEvent($payload, $header, [$newSecret, $oldSecret]). A delivery is valid when any secret matches.
• Events: IdentificationScoredEvent ($event->data is an Identification), WebhookPingEvent (sent when you verify an endpoint) and UnknownWebhookEvent for event types newer than this SDK (acknowledge them with a 2xx). SignatureVerificationException means the delivery is not authentic; WebhookParseException means a correctly signed body is not a valid event.
• Today each identification is delivered once per endpoint: one attempt with a 1-second timeout and no retries. Respond with a 2xx quickly and do slow work afterwards. Future retries will resend identical bytes, so make handlers idempotent on data.request_id ($event->data->request_id) now.
• For guaranteed reads, use the History API: a missed delivery is not sent again, and a History row can be refined after its webhook was sent.
• The "Test" button in the analytics dashboard sends a sample with 17 of the 19 flags and second-precision timestamps. It parses normally; missing flags are false.
• Webhook::verifySignature() returns a boolean without parsing, for custom flows.

Domain profile (Management API)

The Management API allows about 15 requests per minute per client IP and then blocks that IP for 10 minutes. The client never retries a 429: cache the profile rather than reading it on every request.

Errors and retries

Every exception extends ShieldLabs\Exception\ShieldLabsException:

ApiException has getStatusCode(), getBody() (decoded JSON, or the raw text), getRawBody(), getErrorMessage() and getHeaders(); RateLimitException::getRetryAfter() gives the Retry-After value in seconds. Error bodies differ between endpoints (empty, a bare JSON string, an object, plain text), and the SDK parses all of them without failing.

Error messages never include keys or secrets. A key, secret or domain with characters that cannot be sent in an HTTP header (line breaks, NUL, spaces, non-ASCII) throws ValidationException when the client is created, without repeating the value.

Retries use exponential backoff with jitter (0.5 s base, doubling, at most 8 s), for at most max_retries retries (2 by default). When a 429 or 5xx response carries Retry-After, the retry follows it as sent, up to 10 seconds: Retry-After: 0 or a date in the past retries at once. A 429 without Retry-After is retried after at least 1 second, because the History API counts requests per second. identifications->get() sends no retries while it waits: the next poll takes their place, and after a 429 it waits at least 1 second whatever Retry-After says (see Waiting for the verdict).

Rate limits

HTTP client and timeouts

timeout (10 seconds by default) limits every HTTP attempt the SDK sends. While identifications->get() waits, a poll is also limited to the time left in its budget (at least 1 second) when the SDK can change the client's timeout. With no http_client option, the SDK picks the client that applies it:

1. Guzzle 7 or Symfony HttpClient, when php-http/discovery finds one of them in your project. The SDK creates its own instance with the timeout set and redirects turned off.
2. Otherwise its built-in client on ext-curl, ShieldLabs\Http\CurlClient, which never follows redirects and only speaks HTTP and HTTPS.
3. Without ext-curl, any other PSR-18 client that discovery finds. The SDK cannot pass the timeout to it, so it logs a warning; pass a configured client instead.

A client that you pass as http_client is used as is, with its own settings, so give it a timeout. With the built-in CurlClient a poll still gets the shorter timeout described above; with another client each poll can take that client's full timeout:

The SDK writes its warnings (an API key in an unexpected format, a timeout it cannot apply, a plain http base URL allowed with allow_insecure_http) to the PHP error log with error_log(), so they never end up in a response. Each warning is logged once per process; under PHP-FPM or php -S that is once per request that creates a client.

A client keeps no mutable state after construction: share one instance, for example as a singleton in your service container, including in long-running PHP workers.

Configuration

new ShieldLabs(array $options):

new ShieldLabsManagement(array $options) takes secret_key (SHIELDLABS_SECRET_KEY, visible ASCII characters only), domain (SHIELDLABS_DOMAIN; an international domain in its punycode form, xn--...), base_url (SHIELDLABS_MANAGEMENT_BASE_URL, else https://api.shieldlabs.ai; a trailing /v1 is removed; https, or plain http on a loopback host) and the same allow_insecure_http, timeout, max_retries, http_client and request_factory. Unknown option names throw ValidationException. A key, domain or URL option that is missing, null or false (what getenv() returns for an unset variable) falls back to its environment variable.

Reference

Enums: LookupType, RiskBand (Trusted, Suspicious, Dangerous, RateLimited) and EvaluationReason. Constants: SignalName (known signal names), ConnectionType (known connection types), ShieldLabs::VERSION. All classes live in the ShieldLabs\ namespace.

Compatibility

• PHP 8.1, 8.2, 8.3, 8.4 and 8.5.
• Any PSR-18 client (Guzzle 7, Symfony HttpClient and others), or the built-in cURL client.
• Webhook schema version 2026-06-01. Unknown fields, event types and schema versions are accepted; new signal names arrive as plain strings.
• Semantic Versioning: breaking changes only in a new major version.

Development

Refresh the generated client when the API description changes. This does not replace the supported library in this repository.

Without a local PHP:

tests/data/ holds the shared test fixtures that every ShieldLabs server SDK passes. See CONTRIBUTING.md.

Support

• Documentation: docs.shieldlabs.ai
• Analytics dashboard: app.shieldlabs.ai
• Email: [email protected]

License

MIT