- How do I install and set up mchev/banhammer in a Laravel application?
- Install it with composer require mchev/banhammer, then publish the config file and migration, run php artisan migrate, add the Bannable trait to the model you want to ban (usually User), and register the middleware alias in your HTTP kernel or bootstrap/app.php. Finally, point the package at a cache store so ban lookups stay off the hot path. The whole end-to-end flow, including tests, is typically under a day of work for a Laravel developer. No external services, queue workers, or vendor accounts are required.
- Does Banhammer support temporary bans with automatic expiry?
- Yes. Banhammer supports both temporary and permanent bans, and each ban can carry a reason alongside the bannable entity. Temporary bans are stored with an expiry value so the ban stops applying once it lapses. Check your installed version's source to confirm whether expiry is evaluated at lookup time or requires a scheduled cleanup job, since that determines how quickly an expired ban stops blocking requests.
- Can Banhammer ban IP addresses and countries, not just user IDs?
- Yes. Banhammer can ban models by ID or UUID as well as by IP address or country, all through the same polymorphic ban record. That means you can gate a specific account, an abusive IP range source, or an entire region using one consistent mechanism. Because the ban model is polymorphic, it also covers banning by email or any other custom bannable entity you register.
- Does the Banhammer middleware work correctly behind a load balancer or reverse proxy?
- The middleware resolves the request IP through Laravel's request object, so correct behaviour behind a proxy depends on your TrustProxies configuration and whether X-Forwarded-For is honoured. If TrustProxies is misconfigured, Banhammer will see the load balancer's address instead of the client's and IP bans will either miss attackers or block innocent users. Verify this explicitly in staging before enabling IP-based bans in production, and consider testing both the socket address and the forwarded header path.
- Which Laravel and PHP versions does mchev/banhammer support?
- Version 2.5.0 is a compatibility release that adds Laravel 13.x support and includes PHP 8.5 in the test matrix. The release notes describe no API or behavioural changes, but you should confirm from the composer.json diff whether Laravel 12 remains supported or whether the floor was raised to 13. Also confirm whether the Laravel 13 entry refers to a GA release or forward-compatibility testing against a pre-release branch before upgrading a production application.
- Where should I register the Banhammer middleware in my Laravel routes?
- Register the middleware alias in bootstrap/app.php (Laravel 11+) or app/Http/Kernel.php, then apply it to the route groups that actually need identity gating rather than globally. Applying it broadly is convenient but puts the ban check in front of every request, including health checks and public endpoints. It runs early in the request lifecycle, which is exactly what you want for rejecting banned actors cheaply.
- Does Banhammer fire events when a user is banned or unbanned?
- Yes. The package dispatches lifecycle events for banned and unbanned transitions, which you can listen to for audit logging, notifications, cache invalidation, or triggering downstream actions such as revoking sessions and API tokens. Listening for the banned event is also a good place to record who performed the ban if you need an audit trail beyond the default table. Keep listeners lightweight or queue them so you do not slow down the ban operation itself.
- How does Banhammer caching affect performance and ban propagation speed?
- Banhammer caches ban lookups so the check does not hit the database on every request, which is what makes it viable as a middleware in a high-traffic application. The trade-off is propagation latency: after issuing or lifting a ban, the change may not take effect until the cache entry is invalidated or its TTL expires. Determine whether your version invalidates synchronously on ban and unban or relies on TTL, because that interval defines how long a banned user can still reach your app, and how long a mistakenly banned user stays locked out.
- Is there an audit trail showing who created a ban, why, and when it expires?
- The bans table stores the bannable entity, the reason, and the expiry, which supports appeals and expiry review. Whether the record also captures the actor who issued the ban depends on the version and configuration, so inspect the published migration before assuming it. If the actor is not recorded, add a banned_by column or capture it in a listener on the banned event, and treat that data as part of your compliance evidence rather than an afterthought.
- Should I use Banhammer in production, and what are the alternatives?
- Banhammer fits well when account or IP gating is a first-class requirement such as trust and safety, fraud prevention, free-tier abuse, or credential-stuffing response; for edge-case moderation a simple banned_at column with your own middleware is lighter and easier to remove. It is complementary to Laravel's rate limiter and a WAF, not a replacement: rate limiting throttles, a WAF blocks at the edge, and Banhammer enforces persistent identity-level bans inside the app. The main production risks are that it is a single-maintainer package and that a middleware sitting in front of application logic can fail closed on a cache issue, so pin versions, monitor releases, and review the cache and proxy configuration carefully.