niladam/livewire-ban
Ban users in your Laravel app with Livewire. Includes a ready-made Livewire component to ban and unban users, middleware to block banned accounts, and configurable ban reasons and durations.
Install and check compatibility. composer require niladam/livewire-ban, then read the package composer.json to confirm the supported Laravel and Livewire versions. With a small package (4 stars, 0 dependents), check the source before deploying rather than assuming broad version coverage.
Publish and read the config first. Run php artisan vendor:publish and select the package's config tag/provider from the output. The config file is the real documentation: identify the enable switch, cache store/key prefix, strike threshold, strike decay window, ban duration, allowlist, trusted-proxy settings, and which exception types are counted. Clear cached config afterward with php artisan config:clear.
Verify middleware registration. Determine whether the service provider auto-registers the blocking middleware or whether it must be added to the web group or globally. Middleware order matters: it must run before Livewire handles the request, but it also needs a trustworthy client IP. Confirm with php artisan route:list -v and by inspecting the kernel/bootstrap file.
Start disabled locally. Set the package disabled in local and enable it in staging/production via environment variables. If the config has an observe/log-only mode, use that for the first deploy; otherwise raise the strike threshold temporarily so you can watch counters without banning anyone.
First use case: protect one public Livewire surface. Pick a public form, login page, or search component. From a terminal, simulate a request a real browser would not produce — e.g. a malformed POST to Livewire's update endpoint with a missing or invalid payload/checksum. Then verify, in order: the suspicious request is logged, the cache strike key increments, the configured threshold is reached, and subsequent requests from that IP receive the banned response.
Where to look when behavior is unclear: the published config, the service provider, the middleware, the exception listener/detector, and the package tests. The tests are usually the most precise description of intended behavior.
Use a shared cache store in production. Strike counters and bans must survive across app servers. Redis or the database cache is appropriate; file cache on a load-balanced fleet means each node has its own ban list and strike count. Set a stable cache prefix so multiple apps sharing Redis do not collide.
Configure client IP resolution before enabling. Behind Cloudflare, an ALB, or nginx, REMOTE_ADDR is the proxy. Either configure Laravel's trusted proxies correctly or make the package read the forwarded header you control. Getting this wrong bans your proxy IP and takes the whole site down, or bans everyone behind a NAT/CGNAT gateway.
Maintain an explicit allowlist. Include health-check endpoints, uptime monitors, load-test runners, office/VPN egress ranges, CI smoke tests, and your own admin IPs. Treat the allowlist as environment-specific config, not something edited by hand in production.
Tune strikes and decay for humans, not just bots. A real user can produce a Livewire exception through a stale tab, a double submit, a broken JS extension, or a genuine app bug that returns a 500. Use a threshold greater than one, a decay window long enough to catch repeated probing, and a ban duration proportionate to the risk. Start conservative and tighten after observing real traffic.
Layer it with Livewire's own protections. Use #[Locked] properties, validation, authorization checks, signed URLs, and rate limiting at the web-server/proxy level. This package is defense-in-depth against non-browser request patterns, not a replacement for input validation or a WAF.
Add custom detection deliberately. If the package exposes a listener/detector extension point, subclass or configure it to count additional signals — malformed Livewire update paths, missing headers a browser always sends, repeated invalid component snapshots. Keep custom detection fast and side-effect free, because it runs on the request path.
Wire bans into observability. Log ban and strike events to a dedicated channel, emit metrics, and alert on sudden spikes. A spike usually means either an active probe campaign or a false-positive configuration mistake. Build a small operational command or admin screen to list recent bans and clear a specific IP's cache keys; do not rely on waiting out the TTL during an incident.
Test with explicit server variables. In feature tests, set the client IP per request (withServerVariables(['REMOTE_ADDR' => '203.0.113.10'])) and assert the strike counter, ban response, and allowlist bypass. Test the proxy-header path separately if you rely on forwarded IPs. Remember that test exceptions may be handled differently from production, so assert on observable HTTP behavior rather than assuming the listener ran.
Roll out in phases: disabled → observe/log only → high threshold on one route → production threshold. Review the ban log after each phase.
Exception-time detection is fragile by design. v1.1.1 specifically guards strike counting while an exception is unwinding, because an unreachable cache/database or a throwing listener could otherwise replace the original exception and lose the response the app owed. If you extend the detector, keep that same discipline: never let ban bookkeeping throw. Route internal failures through your exception handler instead.
Cache failure means no protection, not a broken app. If the cache store is down, strikes cannot be recorded. Decide explicitly whether that should fail open (allow the request) or closed; failing closed on a cache outage can ban legitimate traffic or take the site down.
Ban duration and cache TTL are two different clocks. If the ban key expires before your ban duration, users are unbanned early; if strike counters never expire, old mistakes accumulate into a ban. Verify both settings together.
IPv6 and NAT are real. IPv6 privacy addresses rotate, so a ban may not stick; CGNAT means one ban can affect many unrelated users. Consider whether the package normalizes addresses (e.g. /64 grouping) and log the full address for forensics.
Middleware ordering is the usual misconfiguration. If the ban middleware runs after the Livewire route or after session/auth middleware that already did expensive work, you get slow blocking. If it runs before trusted-proxy resolution is applied, you ban the wrong IP.
Do not ban on ordinary application exceptions. The premise is "a real browser never produces this." Generic 500s, validation failures, and authorization exceptions are produced by real browsers and by your own bugs. Keep the monitored exception list narrow and revisit it after each Livewire upgrade.
Stale pages and double submits look like attacks. Livewire snapshot/checksum failures happen with old tabs and deploys. Ensure the threshold tolerates normal deploy-window noise, and consider excluding authenticated users or trusted routes if the package supports it.
Watch out for shared infrastructure. Queue workers, cron probes, synthetic monitoring, and load balancers can all source requests from unexpected IPs. Add them to the allowlist before enabling.
Config cache and env changes. After changing thresholds or the allowlist, run php artisan config:clear (or your deploy's equivalent). Many "the ban isn't working" reports are stale config.
This is a small, young package. With 4 stars, 0 dependents, and a single recent release note, budget time to read the source, pin the version in composer.json, and keep the MIT license/security posture in mind. Prefer wrapping it behind your own thin service or config layer so you can swap it out if maintenance stalls.
How can I help you explore Laravel packages today?