Download the PHP package botbye/botbye-php-sdk without Composer

BotBye PHP SDK

PHP SDK for the BotBye Unified Protection Platform — unifying fraud prevention and real-time event monitoring in one platform.

BotBye goes beyond fixed bot/ATO checks. Risk dimensions and metrics are fully dynamic — you define what to measure and what rules to apply per project. This means the same platform covers bot detection, account takeover, multi-accounting, payment fraud, promotion abuse, or any custom fraud scenario specific to your business.

Requirements

• PHP 8.1 or higher
• Composer
• Any PSR-18 compatible HTTP client (Guzzle, Symfony HttpClient, Buzz, etc.)

Installation

You also need a PSR-18 HTTP client and PSR-17 factories. Install one of the ready-made implementations:

Guzzle (most common):

Symfony HttpClient:

Buzz:

Or write a custom adapter for your HTTP transport (e.g. WordPress wp_remote_request) — in that case you only need a PSR-17 factory:

Overview

The SDK provides three request types for different integration levels:

All requests go to a single endpoint (POST /api/v1/protect/evaluate) and return a unified response with a decision (ALLOW, CHALLENGE, BLOCK), risk scores per dimension, and triggered signals. Dimensions are dynamic — the platform ships with built-in ones (bot, ato, abuse) but you can define custom dimensions (e.g., payment_fraud, promotion_abuse) per project without code changes.

Every evaluation call is also recorded as a protection event — logged to the analytics pipeline and used to compute real-time metrics that feed the rules engine. Metrics are fully configurable per project: the platform ships with built-in ones (failed logins, distinct IPs per account, device reuse, etc.) and you can define custom metrics for your specific use case (e.g., "failed transactions over $1000 per account in 1 hour"). This means BotbyeRiskScoringEvent serves a dual purpose: it both evaluates risk and logs the event for future analysis and metric aggregation.

Quick Start

1. Initialize the Client

The SDK uses PSR-18 / PSR-17 interfaces — bring your own HTTP client and message factories.

With Guzzle:

With Symfony HttpClient:

Custom adapter (e.g. WordPress wp_remote_request):

2. Bot Validation (Level 1)

Validate device tokens where user identity is not yet available — at the proxy layer or in a middleware before authentication.

3. Risk Scoring & Event Logging (Level 2)

Evaluate risk and log events when user identity is known. Each call both scores the request and feeds the real-time metrics engine, so you should call evaluate() for every significant user action — not just when you need a decision.

When botbyeResult is null (no Level 1 upstream), bot validation is automatically bypassed.

Event Types

eventType is an arbitrary string — the server accepts any value. Pass any string that matches your business domain:

Using Level 2 for Event Logging

Even when you don't need to act on the decision, sending events builds the metrics profile for the account. This enables rules like "more than 5 failed logins in 10 minutes" or "distinct devices per account in 1 hour":

4. Full Evaluation (Level 1+2 Combined)

Use when there is no separate proxy layer — validates the device token and evaluates risk in a single call.

5. Phishing Image Tracking

The phishing tracking pixel is embedded on a protected site; when a phishing clone copies the markup, the pixel is requested with the clone's Origin, which lets BotBye record a phishing candidate.

Phishing lives in its own dedicated BotbyePhishingClient — separate from the evaluate BotbyeClient. The project is identified by a public, browser-safe clientKey in the URL path, so the client needs no server key; you can construct it standalone (it only needs a PSR-18 client and a PSR-17 request factory). On construction it fires a best-effort server-integration init handshake (POST /api/v1/phishing/init-request/v1/{clientKey}, guarded to run once per process) reporting this module, and fetchImage proxies the pixel via the server /server route so the backend can attribute it to this module even when the browser never reaches BotBye directly.

fetchImage returns BotbyePhishingResponse:

Response

BotbyeEvaluateResponse contains:

Level 1 to Level 2 Propagation

When using both levels, propagate the Level 1 result to Level 2 via the botbyeResult field from the response. This allows the platform to link both evaluations by requestId and combine bot score from Level 1 with risk scores from Level 2 into a single unified result:

Configuration

Timeouts are configured on the HTTP client you provide:

PSR-3 Logger

Error Handling

The SDK follows a fail-open strategy. On network or server errors, evaluate() returns a default response (Decision::ALLOW with error details) instead of throwing:

BotbyeException is only thrown for unrecoverable errors during sendPayload() — the client catches these internally and returns the bypass response.

Request Extractors (framework integration)

Instead of building events field-by-field at every call site, describe once how to turn your framework's request into a BotbyeRequestInfo, then pass only the raw request to the evaluate* methods. Build the client with BotbyeClient::withExtractor(...) — the extractor is any callable(mixed): BotbyeRequestInfo:

Now call sites pass only the raw request (plus user/event for Level 2):

An explicit token argument overrides the one returned by the extractor. The explicit-event API (new BotbyeClient(...) + evaluate(new BotbyeValidationEvent(...))) remains available with no extractor.

Laravel Middleware

Register the extractor-bound BotbyeClient in a service provider:

Symfony Event Subscriber

Phishing from a raw request

The phishing client mirrors the same pattern — bind an Origin extractor once, then pass the raw request to fetchImageFromRequest:

Helpers

Testing

License

MIT

Support

For support, visit botbye.com or contact [email protected].