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.txt auto‑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, default 0) — Minimum time between repeated API checks per session. 0 means “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, default 10) — 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 baseDir and stores its path in .baseUrl.php.
  • It ensures a robots.txt exists in baseDir and adds a Disallow: /<blackhole> rule to discourage compliant crawlers.
  • Normal requests:
    • The kit calls GET https://api.banthebots.cloud/v1/bad-bots/read with your visitor’s IP and User‑Agent (plus throttle).
    • If the API responds that this is a bad bot, the session is marked as banned.
  • Blackhole hits:
    • Requests to the blackhole file call GET https://api.banthebots.cloud/v1/bad-bots/create to register the bot, then immediately 403 and redirect to a hosted explanation page.
  • Blocking mode (apply()):
    • For banned sessions, a 403 Forbidden is sent and the user is redirected to the hosted blackhole page; a styled error message is output if execution continues.
  • Advisory mode (validate()):
    • Returns true for banned sessions; you handle the response.

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 userAgent on 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 baseDir if your app has a different writable directory than the script location.
  • Frequency of checks: increase checkInterval to 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.cloud are allowed.
  • My robots.txt wasn’t updated
    • Confirm the process can write to baseDir and that robots.txt isn’t locked read‑only.
  • Nothing happens
    • Make sure you call $btb->apply() (blocking) or $btb->validate() (advisory) before your app outputs content.

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