PHPackages                             xqus/bad-bot - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Security](/categories/security)
4. /
5. xqus/bad-bot

ActiveLibrary[Security](/categories/security)

xqus/bad-bot
============

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.

v0.2.0-beta(7mo ago)136[2 PRs](https://github.com/xqus/bad-bot/pulls)MITPHPPHP ^8.4CI passing

Since Nov 30Pushed 2mo ago1 watchersCompare

[ Source](https://github.com/xqus/bad-bot)[ Packagist](https://packagist.org/packages/xqus/bad-bot)[ Docs](https://github.com/xqus/bad-bot)[ GitHub Sponsors](https://github.com/xqus)[ RSS](/packages/xqus-bad-bot/feed)WikiDiscussions main Synced today

READMEChangelog (2)Dependencies (14)Versions (6)Used By (0)

BadBot for Laravel
==================

[](#badbot-for-laravel)

[![Latest Version on Packagist](https://camo.githubusercontent.com/295ae2d2279c7b7719a7e4f8b2f3bc09025aed9146c190af813ca1543a61c370/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f787175732f6261642d626f742e7376673f7374796c653d666c6174)](https://packagist.org/packages/xqus/bad-bot)[![GitHub Tests Action Status](https://camo.githubusercontent.com/ff14bec01cf7806b298bc262a779fbc0657fb53d15c3f53c23b0f36abc9a83a3/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f787175732f6261642d626f742f72756e2d74657374732e796d6c3f6272616e63683d6d61696e266c6162656c3d7465737473267374796c653d666c6174)](https://github.com/xqus/bad-bot/actions?query=workflow%3Arun-tests+branch%3Amain)[![GitHub Code Style Action Status](https://camo.githubusercontent.com/0f129daeae385ea849fe9e4fad9380846d4b07feb9444a91d6410734027c877c/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f787175732f6261642d626f742f6669782d7068702d636f64652d7374796c652d6973737565732e796d6c3f6272616e63683d6d61696e266c6162656c3d636f64652532307374796c65267374796c653d666c6174)](https://github.com/xqus/bad-bot/actions?query=workflow%3A%22Fix+PHP+code+style+issues%22+branch%3Amain)[![Total Downloads](https://camo.githubusercontent.com/3dbaa3bc1d86aa6648e4b58f1bc9093b0488f029ae23d5ffe1f75a2630cec6ff/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f787175732f6261642d626f742e7376673f7374796c653d666c6174)](https://packagist.org/packages/xqus/bad-bot)

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
------------

[](#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
-----

[](#usage)

Add the middelware you want to run to your `bootstrap\app.php` file (see the [official documentation](https://laravel.com/docs/12.x/middleware#global-middleware))

```
->withMiddleware(function (Middleware $middleware): void {
    $middleware->appendToGroup('web', [
        xqus\BadBot\Middleware\BadBotMiddleware::class, // blocks marked ip addresses
        xqus\BadBot\Middleware\ThrottleMiddleware::class, // blocks noisy bots, but allows whitelisted bots (Google, Bing, etc)
        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

[](#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
xqus\BadBot\Exceptions\IpAddressBlockedException

```

Testing
-------

[](#testing)

```
composer test
```

Changelog
---------

[](#changelog)

Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently.

Contributing
------------

[](#contributing)

Please see [CONTRIBUTING](CONTRIBUTING.md) for details.

Credits
-------

[](#credits)

- [xqus](https://github.com/xqus)
- [All Contributors](../../contributors)

License
-------

[](#license)

The MIT License (MIT). Please see [License File](LICENSE.md) for more information.

###  Health Score

36

—

LowBetter than 79% of packages

Maintenance77

Regular maintenance activity

Popularity9

Limited adoption so far

Community10

Small or concentrated contributor base

Maturity42

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 96.1% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~3 days

Total

2

Last Release

210d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/203013?v=4)[Audun](/maintainers/xqus)[@xqus](https://github.com/xqus)

---

Top Contributors

[![xqus](https://avatars.githubusercontent.com/u/203013?v=4)](https://github.com/xqus "xqus (74 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (2 commits)")[![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4)](https://github.com/github-actions[bot] "github-actions[bot] (1 commits)")

---

Tags

laravelxqusbad-bot

###  Code Quality

TestsPest

Static AnalysisPHPStan

Code StyleLaravel Pint

### Embed Badge

![Health badge](/badges/xqus-bad-bot/health.svg)

```
[![Health](https://phpackages.com/badges/xqus-bad-bot/health.svg)](https://phpackages.com/packages/xqus-bad-bot)
```

###  Alternatives

[spatie/laravel-permission

Permission handling for Laravel 12 and up

12.9k102.4M1.4k](/packages/spatie-laravel-permission)[spatie/laravel-pdf

Create PDFs in Laravel apps

1.0k4.8M47](/packages/spatie-laravel-pdf)[dedoc/scramble

Automatic generation of API documentation for Laravel applications.

2.1k11.2M100](/packages/dedoc-scramble)[defstudio/telegraph

A laravel facade to interact with Telegram Bots

816333.3k3](/packages/defstudio-telegraph)[spatie/laravel-passkeys

Use passkeys in your Laravel app

471890.7k39](/packages/spatie-laravel-passkeys)[rawilk/profile-filament-plugin

Profile & MFA starter kit for filament.

3914.6k](/packages/rawilk-profile-filament-plugin)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)