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
sodiumextension (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-site/
blockbots-standalone.php
index.php
Step 2 — Include it
Add two lines at the very top of index.php, before anything is printed:
<?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:
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:
curl "https://your-site.com/?bb-selftest=pick-a-long-secret"
A healthy install answers like this:
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:
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:
<?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:
<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>
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
- A visitor with a valid cookie passes through instantly — no network call.
- 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. - 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.
| Constant | Default | What 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_RETRIES | 1 | Verification attempts in the browser |
BLOCKBOTS_DELAY | 1000 | Milliseconds between attempts |
BLOCKBOTS_DEBUG | false | Skip the IP check on the cookie — for local development |
BLOCKBOTS_CACHE_TTL | 3600 | How long a crawler verdict is cached, in seconds |
BLOCKBOTS_CACHE_DIR | system temp | Where file-based cache entries live |
BLOCKBOTS_CHALLENGE_STATUS | 200 | Use 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:
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