Filament Access Management

Role & permission management for Filament, powered by spatie/laravel-permission — with a path-based access gate, a database-driven navigation menu, and a one-command super-admin setup.

✨ Features

• 👥 Users, Roles & Permissions resources ready to use out of the box.
• 🛡️ Path-based access control — bind permissions to HTTP paths (/users, /users/*/edit), methods, or route aliases.
• 👑 Super-admin bypass — a configurable super-admin role that skips every gate.
• 🌳 Database-driven navigation menu — optional tree menu that can replace Filament's default navigation.
• ⚡ One-command setup — filament-access-management:install scaffolds everything and creates your first super admin.
• 🔀 Filament v3, v4 & v5 support (see the compatibility table below).

📋 Compatibility

[!NOTE] This plugin depends on guava/filament-icon-picker for the icon selection UI. If you encounter any errors related to the icon picker, consult the icon picker documentation.

Known issue with Filament v5: see GuavaCZ/filament-icon-picker#70.

📦 Installation

1. Ensure you have already installed a Filament panel.

2. Install the package via Composer:

3. Add the necessary trait to your User model:

   Panel access (production): the trait provides the permission helpers but does not implement Filament's FilamentUser contract. Outside the local environment Filament denies panel access (HTTP 403) to any user whose model doesn't implement it, so also add canAccessPanel() — see the Upgrade Guide.

4. Clear your config cache:

5. Register the plugin in your panel provider (required from v2.x onwards):

6. Run the installer:

   If you don't already have a user named admin, this creates a Super Admin User:

   Field	Value
   Name	admin
   Email	admin@("slug" pattern from config("app.name")).com
   Password	admin

   You can also create one anytime with:

7. If you are upgrading data from before v2.2.0, run:

🗂️ Publish Configs, Views, Translations and Migrations

Then run the migrations:

🔼 Upgrade Guide

[!CAUTION]

⚠️ BACK UP YOUR DATABASE FIRST ⚠️

Upgrading runs migrations and the filament-access-management:upgrade command rewrites menu data in place. Always take a full backup of your database (and code) before you start. Test the upgrade on a staging copy first, and never run it against production without a verified, restorable backup. This operation can modify or delete rows and is not automatically reversible.

This plugin follows the Filament major it targets. Upgrade the plugin together with Filament in a single Composer command, because the 2.x line pins filament/filament: ^3.0 and will block a Filament v4/v5 install. The steps below were verified against a real Laravel app upgraded in place (same database file) from Filament v3 → v4 → v5.

Requirements on your User model (all versions)

Add the FilamentUser contract and canAccessPanel() so the panel isn't 403'd outside local:

Filament v3 (plugin 2.x) → Filament v4 (plugin 3.x)

1. Move Filament and the plugin together:

   This also moves solution-forest/filament-tree (2 → 3) and guava/filament-icon-picker (2 → 3).

2. Follow the official Filament v3 → v4 upgrade guide for your own app code (namespace changes, Form → Schema, action namespaces).

3. Run migrations (no new column is added — is_filament_panel already ships in the upgrade_menu_table migration) and rewrite any legacy /admin/... menu URIs:

   filament-access-management:upgrade strips the /admin prefix from menu uris and sets is_filament_panel = true. It only touches rows whose uri is /admin or /admin/% and is_filament_panel = false, so external URLs are left untouched and the command is idempotent (a re-run with nothing to migrate exits cleanly).

Filament v4 → Filament v5 (both on plugin 3.x)

Filament v5 requires Laravel 12 (and pulls in Livewire 4), so bump them in the same step:

Then follow the official Filament v4 → v5 and Laravel 11 → 12 upgrade guides for your own code, run php artisan migrate (no-op) and re-run php artisan filament-access-management:upgrade.

Notes

• Clearing the permission cache: the plugin caches per-user permissions. When you change a user's roles/permissions outside the plugin's own resource pages (e.g. via a seeder or Eloquent), call \SolutionForest\FilamentAccessManagement\Facades\FilamentAuthenticate::clearPermissionCache() so the change takes effect. The plugin's own Role/Permission pages clear it automatically on save.
• After each upgrade, verify: the login page renders, the super admin can reach the User / Role / Permission resources and the Menu page, a normal user is denied a protected page without the matching permission and allowed with it, and storage/logs/laravel.log is clean.

🚀 Usage

Upon installation, Menu, Users, Roles and Permissions pages are created. Each user has roles, and each role has permissions.

Routing control

Permissions and routes are bound together. On the edit-permission page, set the routes a permission can access: choose the method in the HTTP method select box, and fill the accessible path in HTTP path.

Super Administrator

Create a super admin user:

Check a permission:

Get the current user:

🧩 Advanced Usage

By default the plugin's menu co-exists with Filament's native navigation. To replace the native navigation with the database-driven menu from this package, edit /config/filament-access-management.php and set filament.navigation.enabled => true:

🧪 Testing

The quick-test CI workflow runs the Pest suite against both Filament v4 and Filament v5 (PHP 8.4, Ubuntu) on every push, PR and tag. A tag whose suite fails is deleted automatically.

📝 Changelog

Please see CHANGELOG for more information on what has changed recently.

🤝 Contributing

Please see CONTRIBUTING for details.

🔒 Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

👏 Credits

• Carly
• All Contributors

🌲 About Solution Forest

Solution Forest is a web development agency based in Hong Kong. We help customers solve their problems — and we ❤️ open source.

Our products

• Vxero Neo — Deploy to any VPS from your terminal.
• Vxero — Deploy without DevOps complexity.
• InspireCMS — A full-featured Laravel CMS with everything you need out of the box.
• Filaletter — Filament newsletter plugin.
• Website CMS Management — A hands-on Filament CMS plugin.

Open source

• ForgeDesk — Zero-config developer tools. One click to install, one click to run.
• Watchdog — An uptime monitor desktop application.
• ocpp-php — PHP implementation of the Open Charge Point Protocol (OCPP).
• Filament plugins — Our Filament plugin collection.

You can also sponsor our open source work via GitHub Sponsors. 💚

📄 License

The MIT License (MIT). Please see the License File for more information.