README

A lightweight package that blocks unwanted crawlers, AI agents, scrapers, and high‑frequency visitors while allowing legitimate bots such as Googlebot and Bingbot to pass.

Installation

You can install the package via composer:

composer require xqus/bad-bot

You can publish the config file with:

php artisan vendor:publish --tag="bad-bot-config"

Optionally, you can publish the views using

php artisan vendor:publish --tag="bad-bot-views"

Usage

Add the middelware you want to run to your bootstrap\app.php file (see the official documentation)

->withMiddleware(function (Middleware $middleware): void {
    $middleware->append(xqus\BadBot\Middleware\BadBotMiddleware::class); // blocks marked ip addresses
    $middleware->append(xqus\BadBot\Middleware\ThrottleMiddleware::class); // blocks noisy bots, but allows whitelisted bots (Google, Bing, etc)
    $middleware->append(xqus\BadBot\Middleware\UserAgentMiddleWare::class); // blocks bots based on user-agent
})

To build a new robots.txt run

php artisan badbot:update-txt

Be aware that this command overwrites your current public/robots.txt file.

Custom error handling

By default an exception extending Symfony\Component\HttpKernel\Exception\HttpException will be called when an request is blocked. This will render the default HTTP error page for that error code.

If you want to handle errors differently the following exceptions exists:

xqus\BadBot\Exceptions\RequestRateLimitedException
xqus\BadBot\Exceptions\UserAgentBlockedException

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Credits

License

The MIT License (MIT). Please see License File for more information.

xqus / bad-bot

Maintainers

Details