Ban The Bots — PHP Kit
Take control back on the web. This lightweight PHP kit integrates with the Ban The Bots cloud to detect and block abusive traffic using your visitor's IP and User‑Agent. It can automatically set up a crawler “blackhole” trap, update robots.txt, and enforce a 403 block or let you decide how to handle suspicious requests.
Documentation: https://api.banthebots.cloud/documentation
Features
- Cloud verification against Ban The Bots using a simple HTTP API
- “Blackhole” trap file auto‑generated with a randomised path
robots.txtauto‑updated to disallow the blackhole path for compliant crawlers- Bots are banned from all websites using BanTheBots to give even better protection
- Configurable request throttling and recheck interval
- Zero external dependencies; PHP 5.4+ compatible
Requirements
- PHP >= 5.4
- cURL enabled (used to call the Ban The Bots API)
- Sessions enabled (the class starts a session if one isn’t active)
Installation
Install via Composer:
composer require youds/ban-the-bots
Quick start
There are two common integration patterns: blocking mode and advisory mode.
1) Blocking mode (auto‑block and show a friendly error)
Place this at the top of your front controller (e.g., index.php) before output:
<?php
require __DIR__ . '/vendor/autoload.php';
$btb = new BanTheBots([
// optional settings (see Configuration)
// 'checkInterval' => 0,
// 'baseDir' => __DIR__ . '/', // auto-detected by default
// 'throttle' => 10,
]);
// Will 403 + redirect to a hosted blackhole page if request is flagged
$btb->apply();
// ...rest of your application
2) Advisory mode (you decide how to respond)
<?php
require __DIR__ . '/vendor/autoload.php';
$btb = new BanTheBots();
if ($btb->validate()) {
// Suspicious/bad bot — decide your own response
header('HTTP/1.1 403 Forbidden');
exit('Access denied.');
}
// ...rest of your application
Optional: output the hidden blackhole link in your layout/footer (for crawlers to discover):
<?php $btb->outputBlackHole(); ?>
Configuration
You can pass an array to the constructor to override defaults:
checkInterval(int, seconds, default0) — Minimum time between repeated API checks per session.0means “check every request”.baseDir(string, default: derived from the running script) — Filesystem base directory where the kit writes helper files:.baseUrl.php(stores the randomly generated blackhole path)- The blackhole PHP file (randomized name)
robots.txt(created or updated to disallow the blackhole path)
throttle(int, default10) — Number of requests per 10 seconds used as a signal when checking/creating bot entries with the API.
How it works
- On first run, the kit generates a randomized “blackhole” PHP file in
baseDirand stores its path in.baseUrl.php. - It ensures a
robots.txtexists inbaseDirand adds aDisallow: /<blackhole>rule to discourage compliant crawlers. - Normal requests:
- The kit calls
GET https://api.banthebots.cloud/v1/bad-bots/readwith your visitor’s IP and User‑Agent (plusthrottle). - If the API responds that this is a bad bot, the session is marked as banned.
- The kit calls
- Blackhole hits:
- Requests to the blackhole file call
GET https://api.banthebots.cloud/v1/bad-bots/createto register the bot, then immediately 403 and redirect to a hosted explanation page.
- Requests to the blackhole file call
- Blocking mode (
apply()):- For banned sessions, a
403 Forbiddenis sent and the user is redirected to the hosted blackhole page; a styled error message is output if execution continues.
- For banned sessions, a
- Advisory mode (
validate()):- Returns
truefor banned sessions; you handle the response.
- Returns
API reference
For full API details and response schema, see the official docs:
https://api.banthebots.cloud/documentation
Endpoints used by this kit:
GET /v1/bad-bots/read?ip={ip}&userAgent={ua}&throttle={n}GET /v1/bad-bots/create?ip={ip}&userAgent={ua}&throttle={n}(triggered by the blackhole file)
Notes:
- The kit URL‑encodes the
userAgenton reads, and base64‑encodes it on create via the generated blackhole file. - The hosted blackhole page path is:
https://api.banthebots.cloud/blackhole?returnTo={host}{path}.
Security and privacy
- Data sent: IP address and User‑Agent only; used to classify abusive traffic.
- The kit uses PHP sessions to remember ban status for the current visitor.
- Ensure the generated helper files are writable by your PHP process in
baseDir.
Customization tips
- Error page:
apply()uses a built‑in, styled HTML error message. If you want a custom page, use advisory mode (validate()) and render your own response. - Storage paths: set
baseDirif your app has a different writable directory than the script location. - Frequency of checks: increase
checkIntervalto reduce API calls for long‑lived sessions.
Troubleshooting
- I see cURL errors in logs
- Ensure PHP cURL is enabled and outbound connections to
api.banthebots.cloudare allowed.
- Ensure PHP cURL is enabled and outbound connections to
- My
robots.txtwasn’t updated- Confirm the process can write to
baseDirand thatrobots.txtisn’t locked read‑only.
- Confirm the process can write to
- Nothing happens
- Make sure you call
$btb->apply()(blocking) or$btb->validate()(advisory) before your app outputs content.
- Make sure you call
Versioning and compatibility
- This library targets PHP 5.4+ and avoids modern language features for broad compatibility.
License
This project is licensed under the terms of the LICENSE file in the repository.
Support
- Service site: https://www.banthebots.cloud/
- API docs: https://api.banthebots.cloud/documentation
- Company: Youds Media Limited — https://www.youds.com/
Courtesy of Youds Media Ltd · All Rights Reserved
