Download the PHP package botect/botect-php without Composer

Botect PHP SDK

The official PHP SDK for Botect, a bot-detection platform that scores visitor sessions and helps your application decide how to handle automated traffic.

Use the same package in plain PHP or Laravel. The core works without a framework; Laravel adds automatic service discovery, a facade, Blade integration, middleware, configuration publishing, and queue support.

Documentation · Report an issue

Choose a delivery mode

Start with deferred (the default). It needs no queue worker, cron job, or delivery files. Choose spool or queue when you want persistent delivery with retries.

These are the exact supported configuration values:

Where to set it:

For plain PHP spool mode, also pass storageDirectory. In Laravel, BOTECT_DELIVERY=queue inherits the application's default connection and that connection's default queue from config/queue.php. Leave BOTECT_QUEUE_CONNECTION and BOTECT_QUEUE unset unless you want to override them. The synchronous sync connection is not supported.

On hosts without PHP-FPM's fastcgi_finish_request(), deferred falls back to shutdown processing and may delay the browser response. Even on PHP-FPM, sending still occupies a PHP worker briefly. Buffered deliveries are not persisted in this mode.

This setting controls server deliveries and cached-verdict refreshes. Browser events sent directly to Botect bypass it; lookupVerdict() always makes an immediate request and waits for a response.

Setup guides: Configuration reference

What the SDK does

• Renders the Botect browser collector with your project's site key.
• Reads cached session verdicts and schedules background refreshes.
• Queues assertions that a visitor has authenticated in your application.
• Supports optional server page tracking and forwarding browser events through your application.
• Sends server requests after the browser response by default, with optional file-spool and Laravel queue delivery.
• Allows requests when verdict evidence is unavailable. Enforcement is opt-in.

The browser collector gathers signals; Botect's API computes scores. This package integrates those capabilities into your PHP application. It does not implement the scoring engine or wrap every Botect management API.

Requirements

Enable scoring for a project in Botect to obtain its site key (pk_…) and private key (sk_…). The site key can appear in browser markup. Keep the private key on your server; it is required for verdicts, logged-in assertions, and server ingest. An account API token is a different credential—see Authentication.

Installation

The package is currently available from GitHub as a development version. Until it is published to Packagist, add the repository to your application's Composer configuration:

Commit your application's composer.lock to keep deployments on the same revision. Laravel support is included in this package; no separate Laravel package is needed.

Plain PHP quickstart

1. Configure the client

Create botect.php in your application root, outside the public directory:

Provide the environment variables through your application's environment or existing configuration loader. The SDK does not load .env files itself. The default delivery mode does not require a storage directory or background worker.

2. Add the browser collector

In your page template, render the collector once, before </head> or </body>:

By default, the collector loads from https://cdn.botect.ai/v1/sdk.js and sends browser events directly to https://api.botect.ai/v1/events.

For a Content Security Policy nonce, use $botect->collector(cspNonce: $nonce). Your policy must also permit the collector's script source and event destination.

3. Let the SDK send after the response

This quickstart uses deferred. No additional worker setup is needed. When you call loggedIn(), recordPage(), or forwardEvents(), the SDK buffers the delivery in memory. At the end of the request, it releases an active PHP session lock and calls fastcgi_finish_request() when available, then attempts each buffered delivery once.

On PHP-FPM, the browser receives the completed response before delivery starts. The PHP worker remains occupied briefly while sending. Failed deliveries are discarded: this mode does not persist or retry them, and a killed process can lose pending deliveries.

On hosts without fastcgi_finish_request(), the fallback runs during PHP shutdown and may delay the browser response. In long-running plain PHP processes, call $botect->sendPending() at the end of each request or unit of work, after your host has sent its response. PHP shutdown happens only when the process exits.

The buffer accepts up to 10 distinct deliveries and 1 MiB of serialized data per drain. A 1,000 ms budget is checked between attempts; an attempt already in progress can run until its configured HTTP timeout. Remaining deliveries are discarded when the budget is exhausted. Calls return false if a delivery cannot fit in the buffer.

Optional: file-spool delivery

For persistence and retries, opt into the existing file-spool mode:

Keep that directory outside the public web root. The web application and worker must use the same configuration and storage directory. Run $botect->flush(limit: 100) from a CLI worker or cron; see the worker example. Never flush the file spool during a visitor's request. Browser events sent directly to Botect do not use either delivery buffer.

Laravel quickstart

1. Publish configuration

Laravel discovers the service provider automatically:

Set your project's keys in .env:

The complete configuration is in config/botect.php. Tracking and enforcement are disabled by default.

2. Add the collector to Blade

Place the directive once in your layout:

For a CSP nonce, use @botect($nonce).

The client is also available through the container as Botect\Botect and through the Botect\Laravel\Facades\Botect facade.

3. Set up your chosen delivery mode

Use the delivery-mode table to choose a value for BOTECT_DELIVERY. The setup for each mode follows.

Deferred (default): nothing else to configure. Laravel drains the in-memory delivery buffer through its application-termination hook after the response is sent. No Laravel queue connection or worker is required. The same best-effort limits and non-FPM caveat described above apply.

File spool: set BOTECT_DELIVERY=spool, add this to routes/console.php, and run your application's Laravel scheduler:

Spool files are stored under storage/app/private/botect, separated by project and API URL. Each local spool needs a worker that can access it. Schedule more frequent flushing if you need prompt verdict refreshes.

Asynchronous queue: use your application's existing Laravel queue setup by setting just:

The SDK uses queue.default (normally configured by Laravel's QUEUE_CONNECTION) and the default queue configured for that connection in config/queue.php. Your existing workers process Botect jobs alongside application jobs; no separate Botect queue or worker is required. Those workers must consume the selected connection's default queue.

The sync driver is not supported for queue delivery; use deferred when you do not have an asynchronous queue worker. With queue delivery, use your existing worker instead of botect:flush.

Optional queue customization

Set these only if you deliberately want different routing for Botect jobs:

For example, to use an existing Redis connection with a dedicated queue:

Both overrides are independent. If you set either, make sure a worker consumes the selected connection and queue.

Laravel verdicts use your configured cache store. Web processes and queue workers must share that cache for background refreshes to be useful; set BOTECT_CACHE_STORE when needed.

Reading verdicts

A verdict needs a response from Botect, so the SDK provides two explicit choices.

Immediate lookup

Use lookupVerdict() when you need evidence for the current request:

In Laravel:

This method makes one immediate HTTP request and waits up to the lookup timeout (1,000 ms by default). It does not retry or buffer a refresh. Invalid input, a missing private key, network failures, and unavailable evidence return an allow verdict.

Cached lookup

$botect->verdict($sessionToken) reads cached evidence without making an inline HTTP request. On a miss, it schedules a refresh through your chosen delivery driver and returns action: allow, verdict: not_computed, and score: 0. Cached verdicts expire after 10 seconds by default.

The default plain PHP cache exists only for the current request. A refresh after the response cannot benefit the next request unless you configure a persistent cache. Use lookupVerdict() for the simplest plain PHP integration. For cached lookups, pass a private storageDirectory to Botect::create() to enable the file verdict cache without changing the delivery mode, or supply your own VerdictCache implementation through the cache argument. For the optional file verdict cache, periodically call $botect->pruneVerdictCache() from CLI to remove expired files; spool flush() already does this. No cache maintenance is needed for the default request-local cache. Laravel uses its configured cache store automatically.

Both lookup methods accept the context keys path, ip, country, and ua; values must be strings. Cached lookups use separate entries for different contexts.

In direct browser mode, the collector's session token lives in browser local storage. Your application must explicitly pass that token to its server when using verdicts or logged-in assertions; the SDK does not discover it from a PHP session. With server tracking enabled, use the signed session cookie described below.

See Verdict API and Score bands for response fields and scoring behavior.

Marking a visitor as logged in

After your application has authenticated a visitor, schedule an assertion for their Botect session:

Or with the Laravel facade:

A true result means the configured dispatcher accepted the assertion, not that Botect has accepted it yet. The default mode sends it after the response; spool and queue modes use their workers. The SDK invalidates the local verdict cache for that session and sends no application user ID or email address with the assertion.

See Logged-in visitors for how assertions interact with your rules.

Optional server tracking

Server tracking records page observations and routes browser events through an endpoint on your application. Enable it only when your Botect backend supports and has enabled the server-ingest endpoints. It is disabled by default.

Tracked pages must not be cached. Every tracked response carries a page token and a session cookie minted for one visitor, and is sent with Cache-Control: private, no-store. A CDN or full-page cache that stores a tracked response anyway serves that visitor's token to everyone who receives the cached copy: their browser events are attributed to the first visitor's session, and once the token expires (15 minutes) they are rejected. The ingest endpoint catches the second case when it can: a batch whose page token was minted for a different visitor than the one sending it is rejected with HTTP 409 instead of being attributed, and one warning per page token is logged with the page id and path, so a cached tracked page shows up in your log rather than as another visitor's session. The check uses the visitor's own botect_server_session cookie, which the current collector sends to same-origin endpoints; browsers still holding an older cached collector send none and are accepted on the token alone. Exclude cached pages with tracking.except, or track only specific routes with tracking.scope (below).

For Laravel, set:

Then change the existing tracking settings in config/botect.php:

With scope set to web, the provider adds tracking to the web middleware group and registers POST /_botect/events. Eligible successful HTML GET responses receive a signed HttpOnly session cookie and a collector configured to use that local endpoint. Browser forwarding and page observations use the configured delivery mode.

Tracking injects the collector automatically. If you render @botect yourself, set tracking.inject_collector to false. For automatic injection under a nonce-based CSP, supply a csp_nonce request attribute.

Rebuild Laravel's configuration and route caches after changing the server-ingest setting, the tracking settings, or the ingest path.

Which address is reported

Page hits and forwarded events carry the visitor's IP address as your server observed it (observed_ip), so Botect can attribute what it sees to the network a request really came from. Getting that address right matters: behind a CDN, load balancer or container overlay network the raw connection comes from the proxy, and reporting that would make every visitor look like one.

The SDK never sends a private or reserved address. What it sends otherwise is decided by botect.client_ip (BOTECT_CLIENT_IP):

auto is a guess, and Botect treats guessed addresses accordingly: the events are still scored, but the address is kept for diagnostics only. It is never used for IP-based signals, never becomes the session's address, and cannot get an address listed for enforcement. Botect's dashboard shows a warning while a project's deliveries arrive with guessed or missing addresses. When auto has to guess, the SDK logs one warning naming the header it used and the setting that would make it explicit. A named header is only safe if the proxy in front of you overwrites it on every request; a header a client can set itself lets anyone report any address.

Plain PHP applications pass the address as the last argument to recordPage() and forwardEvents(), either as a string or as a Botect\ClientIp. A string counts as explicit.

Tracking only some routes

Sites that cache most of their pages should track only the routes that are never cached, such as sign-in, search, and account pages. Set scope to manual and attach the botect.track middleware to those routes:

No other route is tracked. tracking.except still applies to the routes you attach it to, and the ingest endpoint is registered in both scopes. Keep @botect in your layout: on tracked routes it renders the collector bound to that visitor's page token, and everywhere else it renders the standard collector that reports directly to Botect, which is safe to cache.

Resolve a session token from the signed cookie in Laravel:

An absent or invalid cookie returns null; check for a token before calling loggedIn() or verdict().

Plain PHP applications can build the same integration using page(), sessionCookie(), recordPage(), collector($page), and forwardEvents(). Set serverIngestEnabled: true in Configuration, and implement the local POST handler at ingestPath to pass the signed page token and decoded collector body to forwardEvents(). Pass the raw value of the visitor's session cookie as its fourth argument and answer Botect\Exceptions\SessionMismatchException (an InvalidArgumentException) with HTTP 409; a missing or unverifiable cookie is ignored. The plain PHP core does not register routes or set cookies for you.

Optional Laravel enforcement

Enable enforcement.enabled in config/botect.php, then apply the middleware to the routes you want to protect:

Use your application's controller. The middleware uses cached verdict() reads, so choose a persistent Laravel cache store for evidence to survive between requests. It needs a valid Botect server session cookie or a botect.session_token request attribute supplied by your integration; adding it alone does not connect a direct browser session to Laravel.

The default handler returns HTTP 403 for block and HTTP 429 with Retry-After: 5 for delay. It allows allow, log, challenge, and unavailable evidence. To implement an actual challenge flow or different responses, provide a class implementing Botect\Laravel\Contracts\VerdictHandler and configure enforcement.handler to use it.

Configuration reference

API and collector URLs must be absolute HTTPS URLs. See config/botect.php for Laravel delivery, cache, cookie, and tracking settings.

Timeouts

The SDK makes two kinds of request, and they have different budgets.

• Immediate lookups (lookupVerdict()) run inside a visitor's request, so the lookup timeouts stay short: 200 ms to connect and 1,000 ms in total by default. If Botect does not answer in time, the request continues with an allow verdict.
• Background deliveries (page hits, forwarded events, logged-in assertions, and cached-verdict refreshes) run in a queue or spool worker where nothing waits on them, so they use the delivery timeouts: 1,000 ms to connect and 5,000 ms in total by default. A delivery that times out or gets a 5xx response is retried by the worker, with backoff, up to five attempts. Retries are not reported to your error tracker; only a delivery that finally fails is logged, once, with its reason, age and attempt count, so a limit that is too short shows up as slower deliveries rather than error reports.
• Deferred delivery holds a PHP-FPM worker after the response has been sent, so it keeps the lookup timeouts. Its 1,000 ms drain budget is separate and is checked between deliveries.

Both pairs are capped at 10,000 ms. Laravel's delivery job allows 15 seconds per attempt, so keep the delivery request timeout below that. A custom transport receives the delivery limits only if it implements TimeoutAwareTransport; one that implements only HttpTransport uses the limits it was built with for every request.

Delivery values, defaults, and configuration locations are listed in Choose a delivery mode. Supplying a storage directory alone enables file verdict caching; it does not select spool delivery.

For custom infrastructure, the core accepts implementations of TimeoutAwareTransport as well to receive the delivery timeouts). Laravel applications can bind those contracts in their own service provider.

Documentation and examples

• Botect documentation — product guides and API reference.
• Quickstart — create a project and start collecting signals.
• Authentication — site keys, private keys, and account tokens.
• How scoring works — the scoring model.
• Rules — configure how Botect handles visitors.
• Cloudflare enforcement — enforce decisions at the edge.
• Laravel example.

Development

composer check runs the test suite and a standalone integration check that rejects any Laravel or Symfony class loading in the plain PHP core. The CI matrix covers PHP 8.3–8.5 and Laravel 12–13, excluding Laravel 13 on PHP 8.3.

Run php tests/fpm.php for an isolated PHP-FPM smoke test that verifies response completion before delivery. Set PHP_FPM_BINARY if the binary is not at the default system path.

Report SDK bugs and feature requests in GitHub Issues. Include your PHP/Laravel versions and a minimal reproduction, with credentials removed.

Contributing

See contributing.md for setup, testing, and the pull request workflow.

License

This package is available under the MIT license.