Laravel Mongo Permission Filament Laravel Package

Getting Started

• Install the MongoDB PHP extension and configure a mongodb connection in config/database.php before touching the package. This stack stores roles/permissions in MongoDB, not SQL.
• Require the package plus its permission backend: composer require <package> webrek/laravel-mongo-permission:^1.5. The ^1.5 constraint matters — it contains the legacy flat-data fix and cache invalidation improvements this release depends on.
• Publish any package/webrek config (php artisan vendor:publish) and review the guard/model settings. There are no SQL migrations to run; MongoDB collections are created on first write.
• Add the permission trait from webrek/laravel-mongo-permission (e.g. HasRoles) to your authenticatable model, typically App\Models\User. Confirm the model extends the MongoDB Eloquent base model expected by webrek.
• Register the plugin on your Filament panel provider, e.g. ->plugins([...]) in AdminPanelProvider. This registers the Role and Permission resources bound to the Mongo models.
• First use case: log into the panel, create a few permissions via the Permission resource, then create a role and select those permissions in the permissions select on the Role form. Assign the role to a user in code ($user->assignRole('admin')) and verify with $user->can('...').

Implementation Patterns

• Treat the Filament resources as the admin UI and seeders/commands as the source of truth for stable permission names. Create permissions idempotently in a seeder with firstOrCreate(['name' => 'posts.publish', 'guard_name' => 'web']), then sync them to roles.
• Use the package’s resource forms for day-to-day role editing, but keep permission definitions in code so renames are reviewed. The permissions select is convenient for ad-hoc changes; seeders prevent drift across environments.
• Assign roles in application code and check abilities through Laravel’s Gate ($user->can(...), @can, policies). Avoid querying the Mongo role collections directly in controllers.
• For Filament resource authorization, define policies against your User model and let Filament’s canViewAny/canCreate etc. call $user->can(...). This keeps panel access aligned with the same permission data edited in the UI.
• Customize the resources by extending the package resource classes and overriding the form/table schema rather than editing vendor files. Common changes: making the permissions select searchable, grouping permissions by prefix, or restricting visible roles by guard.
• If you support multiple guards, set guard_name explicitly everywhere — in seeders, in resource forms, and on the User model’s guard. Filament panel guards must match the permission backend’s guard.
• In tests, mirror the package’s own approach: Livewire/Filament form tests for creating roles and permissions, and assertions that the resources are bound to the Mongo models. Use the MongoDB connection for cleanup rather than RefreshDatabase (which is SQL-oriented).
• For long-running processes (queue workers, Octane), assume permission caches may persist between requests. The ^1.5 backend adds cache invalidation, but explicitly forgetting cached permissions after programmatic bulk changes is still a safe pattern.

Gotchas and Tips

• Hard requirements: Laravel 12 and PHP 8.2+ only. This is not a drop-in for Laravel 10/11 apps. Check composer why-not before upgrading an existing project.
• MongoDB, not SQL: There are no migrations for roles/permissions. Backups, indexing, and data lifecycle are your responsibility. Ensure the MongoDB connection is configured in every environment, including CI.
• Legacy data: The ^1.5 backend includes a legacy flat-data fix. If you are migrating from an older Mongo permission schema, test role/permission reads carefully and inspect documents for old shapes before relying on the UI.
• Cache invalidation: The release specifically calls out cache invalidation. After bulk imports or direct Mongo writes, call the permission registrar’s cache flush (or restart workers). Do not assume a UI edit invalidates caches in separate queue/Octane processes.
• Guard mismatch: The most common cause of “permission exists but can() returns false” is a guard mismatch between the role/permission documents, the User model, and the Filament panel. Keep guard_name consistent.
• Large permission sets: The permissions select can become unwieldy. Make it searchable and consider grouping by domain prefix. For very large sets, prefer seeding and restrict who can edit permissions in the panel.
• No SQL RefreshDatabase: Use MongoDB-specific cleanup in tests. The package’s new test suite is a good reference for asserting resource/model binding without assuming SQL migrations.
• PHPStan level 5 covers the package, not your application. Do not treat it as a guarantee of strict typing in your integration code; add your own static analysis if you rely heavily on dynamic role names.
• Extension points: Prefer extending the package’s Filament resource classes and models over forking. If you need custom permission logic, bind your own implementation through the container where the backend allows it, and keep the Filament plugin registration as the single integration point.