Server

PHP

Protect any PHP site from bots with a single file — no framework, no Composer, no plugin.

Overview

This guide adds BlockBots to a plain PHP site. You will download one file, set your API key, and include it — detection then runs on every page before your own code does.

It takes about five minutes. No framework, no Composer, no database.

This guide covers server-side protection. If you want to verify visitors inside a single-page app instead, see the JavaScript guide.

Prerequisites

  • PHP 7.2 or higher with the sodium extension (on by default since 7.2)
  • Write access to your site's files
  • An API key — create one at panel.blockbots.org under Settings → API Keys

Step 1 — Download the file

In your dashboard, open Settings → Integrations → PHP Standalone and download blockbots-standalone.php.

Put it next to your entry point:

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

Step 2 — Include it

Add two lines at the very top of index.php, before anything is printed:

index.php
<?php
define('BLOCKBOTS_API_KEY', 'YOUR_API_KEY');
require_once __DIR__ . '/blockbots-standalone.php';
?>
<!DOCTYPE html>
<html lang="en">
<head><title>My Site</title></head>
<body>
  <h1>Welcome</h1>
</body>
</html>

There is nothing to call. The file runs the moment it is included.

Before any output matters. If your page prints something first, cookies can no longer be set and BlockBots quietly stands aside. It writes a line to your PHP error log when that happens, so check there if nothing seems to happen.

Step 3 — Check it works

Open your site in a private window. You should see a verification screen for a second, then your own page.

To confirm what is going on under the hood, switch on the self-test:

index.php
define('BLOCKBOTS_API_KEY', 'YOUR_API_KEY');
define('BLOCKBOTS_SELFTEST', 'pick-a-long-secret');
require_once __DIR__ . '/blockbots-standalone.php';

Then request any page with that secret:

terminal
curl "https://your-site.com/?bb-selftest=pick-a-long-secret"

A healthy install answers like this:

output
Blockbots self-test

environment
  php                    8.2.4
  sodium                 yes
  library active         yes
  headers sent           no

this request
  REMOTE_ADDR            203.0.113.9
  trusted proxy          no
  resolved client ip     203.0.113.9
  looks like a browser   yes

cache
  driver                 apcu
  entries                14

api
  url                    https://api.blockbots.org/v1/verify-bot
  round trip             86 ms
  reachable              yes

Remove the BLOCKBOTS_SELFTEST line when you are done — without it the page does not exist.

Step 4 — If you use a CDN

Cloudflare is recognised automatically. Any other CDN needs one line, otherwise every visitor arrives as the same address and nobody can pass verification:

index.php
define('BLOCKBOTS_TRUSTED_PROXIES', '203.0.113.0/24,198.51.100.7');

Use the address ranges your CDN connects from — your provider publishes them. Local reverse proxies and Docker networks are trusted without configuration.

In the self-test, trusted proxy should read yes and resolved client ip should be the visitor's real address, not your CDN's.

Step 5 — Install without editing your pages (optional)

If your site has many entry points — catalog.php, contact.php, about.php — let PHP include the file for you. Nothing in your own code changes, and a CMS update cannot undo it.

Move the two lines into their own file, outside the web root:

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

Then add both of these next to your index.php:

.htaccess
<IfModule mod_php.c>
    php_value auto_prepend_file "/home/user/blockbots-init.php"
</IfModule>
<IfModule mod_php7.c>
    php_value auto_prepend_file "/home/user/blockbots-init.php"
</IfModule>
.user.ini
auto_prepend_file = /home/user/blockbots-init.php

Two files because hosting differs: Apache with mod_php reads the first, PHP-FPM reads the second, and each ignores the other. The <IfModule> wrapper is what keeps the .htaccess safe on PHP-FPM.

How it works

  1. A visitor with a valid cookie passes through instantly — no network call.
  2. Anything that does not look like a browser is checked against the cloud. Crawlers you allow, such as Googlebot, get your content; impostors using their name get 403.
  3. Everyone else sees the verification page, gets a signed cookie, and the page reloads.

Verdicts are cached, so a crawler costs one cloud call per hour rather than one per page. fetch and XHR requests are never interrupted, and form submissions are never swallowed. If your API key stops working, the library steps aside and your site keeps serving.

Configuration

Everything except the key is optional. Set constants before the require_once.

ConstantDefaultWhat it does
BLOCKBOTS_API_KEY—Required. Your API key
BLOCKBOTS_TRUSTED_PROXIES—Your CDN or load balancer addresses, comma separated
BLOCKBOTS_SELFTEST—Secret that enables the self-test page
BLOCKBOTS_RETRIES1Verification attempts in the browser
BLOCKBOTS_DELAY1000Milliseconds between attempts
BLOCKBOTS_DEBUGfalseSkip the IP check on the cookie — for local development
BLOCKBOTS_CACHE_TTL3600How long a crawler verdict is cached, in seconds
BLOCKBOTS_CACHE_DIRsystem tempWhere file-based cache entries live
BLOCKBOTS_CHALLENGE_STATUS200Use 503 to have search engines treat the verification page as a temporary hold

Caching needs no setup: APCu, Redis or Memcached are used automatically when present, otherwise files.

To skip all checks for a request — health checks, internal endpoints:

health.php
define('BLOCKBOTS', false);
require_once __DIR__ . '/blockbots-standalone.php';

Next steps

  • WordPress Plugin — the same protection, installed from the admin panel
  • Node.js — the same protection for an Express or Fastify app
  • JavaScript — verify visitors inside a single-page app