BlockBots

PHP – Quick Start

Integrate BlockBots into any PHP site using blockbots-standalone.php — no framework or plugin required.

Overview

blockbots-standalone.php is a single-file PHP integration that protects any PHP page from bots, VPNs, and fake traffic. Drop it into your project, define your API key, and require it — the file runs automatically with no function calls needed.

Requirements

  • PHP 7.2 or higher
  • The sodium extension (enabled by default since PHP 7.2)
  • A BlockBots API key from panel.blockbots.org

Installation

1. Download the file

Download blockbots-standalone.php from your dashboard at panel.blockbots.org under Settings → Integrations → PHP Standalone.

2. Place it in your project

/your-site/
  blockbots-standalone.php
  index.php

3. Add two lines before any output

<?php
define('BLOCKBOTS_API_KEY', 'YOUR_API_KEY');
require_once __DIR__ . '/blockbots-standalone.php';

That's it. The file runs detection automatically the moment it is required — no function calls, no extra setup.

Get your API key from the dashboard at panel.blockbots.org under Settings → API Keys.

How it works

  1. On each request the file checks for a valid __bbjwt cookie. Verified humans pass through instantly — no network call made.
  2. If no valid cookie exists, the visitor is served a verification page. The BlockBots JS library runs a silent cloud check in the browser.
  3. Verified humans receive a signed JWT cookie and the page reloads automatically. The process typically takes under 1–2 seconds.
  4. Visitors with a __bb_decision block cookie receive a 403 Access Denied page and never see your content.

XHR / fetch requests bypass the verification page automatically so your API calls are never interrupted.

Full example

<?php
define('BLOCKBOTS_API_KEY', 'YOUR_API_KEY');
require_once __DIR__ . '/blockbots-standalone.php';
?>
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8" />
  <title>My Site</title>
</head>
<body>
  <h1>Welcome!</h1>
  <!-- Protected content — bots never reach this -->
</body>
</html>

Configuration

Set any of these constants before the require_once to override the defaults:

define('BLOCKBOTS_API_KEY',    'YOUR_API_KEY');
define('BLOCKBOTS_DEBUG',        false);   // true = skip IP-binding check on the JWT
define('BLOCKBOTS_RETRIES',      2);       // JS SDK retry attempts
define('BLOCKBOTS_DELAY',        1000);    // delay between retries (ms)
define('BLOCKBOTS_TIMEOUT',      30000);   // verification timeout (ms)
define('BLOCKBOTS_SHOW_LOADING', true);    // show loading overlay during verification

require_once __DIR__ . '/blockbots-standalone.php';
ConstantTypeDefaultDescription
BLOCKBOTS_API_KEYstring—Required. Your API key
BLOCKBOTS_DEBUGboolfalseSkip IP binding check on the JWT cookie — useful for local dev behind NAT
BLOCKBOTS_RETRIESint2Number of JS SDK retry attempts if verification fails
BLOCKBOTS_DELAYint1000Milliseconds between retries
BLOCKBOTS_TIMEOUTint30000Maximum time (ms) to wait for cloud verification
BLOCKBOTS_SHOW_LOADINGbooltrueShow animated loading overlay while verification runs

Disabling protection conditionally

Define BLOCKBOTS as false before the require_once to bypass all checks for that request — useful for admin routes or health-check endpoints:

define('BLOCKBOTS', false); // skip all bot checks
require_once __DIR__ . '/blockbots-standalone.php';

Next steps