Hiddenfieldantispam Bundle Laravel Package

Getting Started

This is the initial release (v1.0.1), so treat it as a first-look, not a stable dependency. The stated core is present: it detects bots and returns an error message to them while leaving normal traffic alone. Translation of that message is explicitly unfinished, which tells you the user-facing surface is small and still moving.

1. Install and read the README first. The package is brand new, so the README is the only real API contract. Look for: how the middleware is registered, whether a config file is published, and what constitutes a "bot" (user-agent matching, IP lists, or both).
2. Publish and inspect config. Run the package's publish command (usually php artisan vendor:publish --tag=<vendor>-config) and read the config end-to-end before touching anything. The defaults define your allow/deny baseline.
3. First use case: protect one route group. Do not roll it out globally on day one. Attach the middleware to a narrow group (e.g. a contact form or a login POST) and watch the logs for a day.
4. Verify behavior with curl. Confirming the block path is trivial and should be your first smoke test:

# Should return the package's bot error
curl -i -A "curl/8.0" https://your-app.test/protected

# Should pass through
curl -i -A "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) ..." https://your-app.test/protected

If the second command also gets blocked, stop and fix the matcher before going further.

Implementation Patterns

Route-scoped middleware is the safe default. Global middleware on a v1.0.x bot filter is a good way to block your own uptime monitor. Prefer:

Route::post('/contact', ContactController::class)
    ->middleware('bot-block');

Layer it with throttling, don't replace it. Bot filtering complements throttle: — it does not substitute for rate limiting. A spoofed user-agent defeats UA matching entirely, so keep the rate limiter in front.

Centralize the allowlist in config, not code. Health checks, synthetic monitors, Stripe webhooks, and your own CI all look like bots. Keep them in the published config's allow/allowlist section (or an env-driven override) so ops can adjust without a deploy:

'allow' => array_filter(explode(',', env('BOT_BLOCK_ALLOW', ''))),

Test the block path in feature tests. Use Laravel's header helpers to pin behavior:

$this->withHeader('User-Agent', 'Googlebot/2.1')
     ->get('/protected')
     ->assertStatus(/* whatever the package returns */);

Write one test for the blocked case and one for the passthrough case. When v1.x changes the response code (likely, given the release is a first cut), the test tells you immediately.

Log every block, at least initially. Wrap or observe the middleware so you can answer "did we block a real customer?" Bot filters fail silently by design; without a log you won't know you have false positives until someone complains.

Keep it behind a toggle. An env flag read in the config lets you disable blocking instantly during an incident without reverting a deploy.

Gotchas and Tips

• Translation is incomplete — do not build UX on the error message. The release notes say translation is still pending and the message is only ever seen by bots. That's fine for the block path, but it means: (a) the message is probably hardcoded or English-only, and (b) the string may move or be wrapped in a translation key in a later 1.x. If you need a localized response, override the message yourself at the middleware/config level rather than relying on the package.
• Decide deliberately between 403 and 404. A 403 tells the bot it was detected; a 404 is quieter. The release doesn't settle this. If SEO crawlers are in scope, verify which one you're returning and whether it's configurable — a 403 to Googlebot is a serious problem.
• Trusted proxies. If you're behind a load balancer or CDN, $request->ip() is the proxy unless TrustProxies is configured. IP-based bot rules will match or miss the wrong thing entirely. Check config/trustedproxy before you trust any IP logic.
• Cache interactions. Full-page caches (Cloudflare, Laravel response cache) may serve a blocked response to everyone or a normal response to a bot. Ensure the middleware runs before the cache layer, and check whether blocked responses carry cache headers.
• Middleware priority. In Laravel 11+ the priority list is configured in bootstrap/app.php. If the bot middleware runs after session/auth middleware, blocked requests still touch the database and session store. Move it early to get the cheap-rejection benefit.
• User-agent matching has a long tail. curl, python-requests, Go-http-client, axios, and empty UA strings are the common offenders — but so is your own queue worker hitting an internal endpoint. Test your own infrastructure before enabling globally.
• v1.0.x is pre-stabilization. The author has flagged unfinished work in the very first release note. Pin the version ("vendor/package": "1.0.*") and read the changelog before minor bumps; expect the config keys and the public middleware name to be the most likely things to shift.
• Extension points to check first: (1) the publishable config, (2) whether the middleware is resolvable/replaceable via the container, (3) whether the response is built from a view or a translation key — that last one is where the unfinished translation work will land, and it's your best hook for customizing the message without forking.