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

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:

   composer require solution-forest/filament-access-management
   

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

4. Clear your config cache:

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

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

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

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

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

   php artisan filament-access-management:upgrade
   

#🗂️ 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)

1. 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).

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:

   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.

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

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

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