README

Modern PHP SDK for bad_ip – detect, block and report malicious IPs, TOR traffic, bots and bad queries.

🚀 Installation

composer require bad-ip/bad-ip-php

Requires PHP 8.1+.

⚡️ Quick Start

use BadIp\Config;
use BadIp\Client;
use BadIp\RequestContext;
use BadIp\Detector;

$config = new Config(token: 'your-api-token');
$client = new Client($config);
$detector = new Detector($client);

$ctx = RequestContext::fromGlobals();

if ($detector->isBlockedIp($ctx)) {
    die('Access denied by Bad IP');
}

🔥 Features

• Detect and block malicious IPs
• Detect and block TOR exit nodes
• Basic bot detection
• Guard against bad queries
• Guard against brute force login attempts
• Report suspicious activity back to Bad IP API
• Fully extensible and testable

🧑‍💻 Usage Examples

Check if IP should be blocked

if ($detector->isBlockedIp($ctx)) {
    die('Blocked by Bad IP');
}

Block TOR traffic

use BadIp\TorGuard;

$torGuard = new TorGuard($detector);

try {
    $torGuard->enforce($ctx);
    echo "Welcome, not a TOR exit node!";
} catch (\RuntimeException $e) {
    http_response_code(403);
    echo $e->getMessage();
}

Login Guard

use BadIp\Reporter;
use BadIp\LoginGuard;

$reporter = new Reporter($client);
$guard = new LoginGuard($reporter, maxAttempts: 3);

$guard->check($ctx, $success); // $success = true or false

Query Guard

use BadIp\QueryGuard;

$queryGuard = new QueryGuard();
$queryGuard->allowQuery('/status');
$queryGuard->denyIp('1.2.3.4');

if (!$queryGuard->isAllowed($ctx)) {
    $reporter->reportQuery($ctx);
}

Report 404

$reporter->report404($ctx);

Manual report

$client->report('8.8.8.8', 'manual_block', 'my-app');

🧪 Testing

composer test

We recommend Pest or PHPUnit with coverage.

🤝 Contributing

Contributions are welcome! Please see the contributing guide.

📄 License

The MIT License (MIT). See LICENSE for more information.