Filament Ban Manager Laravel Package

Getting Started

This is a Filament plugin (rectitude-open/filament-ban-manager) that adds a BanResource to your Filament admin panel for managing banned users/IPs. Start here:

1. Install via Composer: composer require rectitude-open/filament-ban-manager
2. Publish and run migrations (the package ships its own ban table): php artisan vendor:publish --tag="filament-ban-manager-migrations" then php artisan migrate
3. Register the plugin in your Panel provider (->plugins([BanManagerPlugin::make()]))
4. Publish translations if you need to customise or add locales (new in v1.11.0 — see README instructions): php artisan vendor:publish --tag="filament-ban-manager-translations"

Your first use case is almost always: visit the "Bans" resource in the panel, create a ban for an abusive user, and confirm the middleware/guard integration actually blocks them. Check the config file after publishing (filament-ban-manager.php) to understand how bans are enforced in your app — that's the file you'll touch before writing any custom code.

Implementation Patterns

Resource-first administration. Treat BanResource as the operator UI and your application code as the enforcement layer. Model your ban records against whatever the package's Ban model exposes (user relation, IP, reason, expiry) rather than adding parallel banned_at columns to users.

Programmatic banning. Wrap ban creation in a small service or action class so the same logic powers both the Filament UI and your own code (registration checks, API middleware). This keeps reason/expiry semantics consistent and avoids duplicating validation that BanResource already encodes in its form.

Scheduled/unban workflows. If bans carry expiry, drive unbanning from a scheduled command rather than relying on the panel — the resource is for human action, not lifecycle management.

Localisation (v1.11.0). Labels and notifications in BanResource actions and forms now resolve through translation strings. If you maintain a non-English panel, publish the translation files and override keys in your app's lang/vendor/ directory instead of forking the package. This is also the clean way to reword "Ban"/"Unban" terminology to match your domain.

Navigation badges (v1.11.0). Badge configuration is now exposed. Use it to surface active-ban counts in the sidebar so moderators don't need to open the resource to see whether anything needs attention — pair it with a scoped query that excludes expired bans, otherwise the badge becomes noise.

Multi-panel setups. Register the plugin per panel and lean on the new badge/label config to differentiate contexts (e.g. a support panel showing only user bans, an ops panel showing everything).

Gotchas and Tips

Enforcement is not automatic. The plugin gives you a management UI; whether a banned user is actually blocked depends on your guard/middleware wiring. Verify with a real login attempt before shipping. This is the single most common source of "the package doesn't work" reports.

Publish before you customise. Config, migrations, and now translations all live behind publish tags. Editing files inside vendor/ will be silently wiped on composer update. Re-run vendor:publish after upgrading if new config keys appear.

Upgrading to v1.11.0 is low-risk. The release is additive: new translations, translation-string adoption in existing labels/notifications, and optional navigation badge configuration. No breaking changes are signalled. The one behavioural nuance is that labels/notifications you previously overrode by editing the resource now resolve through translations — if you had forked or extended BanResource to hardcode English strings, reconcile that with the new translation keys to avoid duplicated or conflicting copy.

Watch translation key drift. Now that UI strings are translation-driven, a custom locale file that's missing keys will fall back to the package default (typically English) mid-interface. Diff your published translation files against the package's after each release; missing keys fail silently rather than erroring.

Debugging bans that "don't apply". Check in this order: (1) is the record expired or soft-deleted, (2) is your middleware actually registered on the route/guard in question, (3) is the ban matched on the identifier you expect (user ID vs. email vs. IP — these are different columns and easy to mix up). Add logging at the enforcement point rather than the resource.

Cache and session invalidation. If you cache user state or keep long-lived sessions, a ban created in the panel won't take effect until that cache/session is refreshed or invalidated. Decide explicitly whether banning should force logout, and implement it in your action class, not in the resource.

Extension points. Prefer subclassing BanResource and overriding methods (form schema, table query, badge callback) over editing published copies — subclassing survives package updates, published copies don't. Register your subclass in the panel in place of the package resource.