README

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

Plugin version	Filament version
1.x	2.x
2.x	3.x
3.x	4.x / 5.x

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

Ensure you have already installed a Filament panel.

Install the package via Composer:

composer require solution-forest/filament-access-management

Add the necessary trait to your User model:
```
use SolutionForest\FilamentAccessManagement\Concerns\FilamentUserHelpers;

class User extends Authenticatable
{
    use FilamentUserHelpers;
}
```
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.

Clear your config cache:

php artisan optimize:clear
# or
php artisan config:clear

use SolutionForest\FilamentAccessManagement\FilamentAccessManagementPlugin;

public function panel(Panel $panel): Panel
{
    return $panel
        ->plugin(FilamentAccessManagementPlugin::make());
}

Run the installer:
```
php artisan filament-access-management:install
```
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:
```
php artisan make:super-admin-user
```
If you are upgrading data from before v2.2.0, run:
```
php artisan filament-access-management:upgrade
```

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

🗂️ Publish Configs, Views, Translations and Migrations

php artisan vendor:publish --tag="filament-access-management-config"
php artisan vendor:publish --tag="filament-access-management-views"
php artisan vendor:publish --tag="filament-access-management-translations"
php artisan vendor:publish --tag="filament-access-management-migrations"

Then run the migrations:

php artisan migrate

🔼 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:

use Filament\Models\Contracts\FilamentUser;
use Filament\Panel;
use SolutionForest\FilamentAccessManagement\Concerns\FilamentUserHelpers;

class User extends Authenticatable implements FilamentUser
{
    use FilamentUserHelpers;

    public function canAccessPanel(Panel $panel): bool
    {
        // Per-page permissions are still enforced by this plugin's middleware.
        return true;
    }
}

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

Move Filament and the plugin together:
```
composer require "filament/filament:^4.0" "solution-forest/filament-access-management:^3.0" -W
```
This also moves solution-forest/filament-tree (2 → 3) and guava/filament-icon-picker (2 → 3).
Follow the official Filament v3 → v4 upgrade guide for your own app code (namespace changes, Form → Schema, action namespaces).
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:
```
php artisan migrate
php artisan filament-access-management:upgrade
```
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:

composer require "filament/filament:^5.0" "laravel/framework:^12.0" \
  "solution-forest/filament-tree:^4.0" "solution-forest/filament-access-management:^3.0" -W

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.

Menu, Users, Roles & Permissions

Manage Menu

Manage Users and their roles

Manage Roles and their permissions

Manage 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.

Goal	HTTP path
Access`GET /admin/users`	`/users` (with `HTTP method` = `GET`)
Access everything under`/admin/users`	`/users*`
Access the edit page only	`/users/*/edit`
Different method per path	`GET:users/*`
Use a route alias	`admin.users.show`

Super Administrator

Create a super admin user:

php artisan make:super-admin-user

Check a permission:

// Check by permission's name
\SolutionForest\FilamentAccessManagement\Http\Auth\Permission::check($name);

// Check by http_path
\SolutionForest\FilamentAccessManagement\Http\Auth\Permission::checkPermission($path);

Get the current user:

\SolutionForest\FilamentAccessManagement\Facades\FilamentAuthenticate::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:

'filament' => [
    // ...
    'navigation' => [
        // Use db-based Filament navigation when true.
        'enabled'    => true,
        // Table name for the db-based navigation.
        'table_name' => 'filament_menu',
        // Filament Menu model.
        'model'      => Models\Menu::class,
    ],
    // ...
],

🧪 Testing

composer test

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

🌲 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.

solution-forest / filament-access-management

Maintainers

Package info

Statistics

Security

README

Filament Access Management

✨ Features

📋 Compatibility

📦 Installation

🗂️ Publish Configs, Views, Translations and Migrations

🔼 Upgrade Guide

⚠️ BACK UP YOUR DATABASE FIRST ⚠️

Requirements on your `User` model (all versions)

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

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

Notes

🚀 Usage

Routing control

Super Administrator

🧩 Advanced Usage

🧪 Testing

📝 Changelog

🤝 Contributing

🔒 Security Vulnerabilities

👏 Credits

🌲 About Solution Forest

📄 License

solution-forest / filament-access-management

Maintainers

Package info

Statistics

Security

README

Filament Access Management

✨ Features

📋 Compatibility

📦 Installation

🗂️ Publish Configs, Views, Translations and Migrations

🔼 Upgrade Guide

⚠️ BACK UP YOUR DATABASE FIRST ⚠️

Requirements on your User model (all versions)

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

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

Notes

🚀 Usage

Routing control

Super Administrator

🧩 Advanced Usage

🧪 Testing

📝 Changelog

🤝 Contributing

🔒 Security Vulnerabilities

👏 Credits

🌲 About Solution Forest

📄 License

Requirements on your `User` model (all versions)