PHPackages                             abdulrahim/filament-modular-permissions - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Authentication & Authorization](/categories/authentication)
4. /
5. abdulrahim/filament-modular-permissions

ActiveLibrary[Authentication & Authorization](/categories/authentication)

abdulrahim/filament-modular-permissions
=======================================

Modular Roles and Permissions for Filament v5 with easy publishing and syncing.

v1.5.5(3w ago)014MITPHPPHP ^8.2

Since May 13Pushed 3w agoCompare

[ Source](https://github.com/AbdulrahimAl-Ghazi/filament-modular-permissions)[ Packagist](https://packagist.org/packages/abdulrahim/filament-modular-permissions)[ Docs](https://abaad.dev)[ RSS](/packages/abdulrahim-filament-modular-permissions/feed)WikiDiscussions main Synced 1w ago

READMEChangelogDependencies (2)Versions (11)Used By (0)

Filament Modular Permissions
============================

[](#filament-modular-permissions)

[![Latest Version on Packagist](https://camo.githubusercontent.com/b0266b69e240b8aea15b4d2e744f302c08f031f3e39108a1fc7d187f3519c9e7/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f616264756c726168696d2f66696c616d656e742d6d6f64756c61722d7065726d697373696f6e732e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/abdulrahim/filament-modular-permissions)[![Total Downloads](https://camo.githubusercontent.com/9fb6ba7d37fcdfac0127a68f974a30262790a0970eef4a22e9c8028a8b78267c/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f616264756c726168696d2f66696c616d656e742d6d6f64756c61722d7065726d697373696f6e732e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/abdulrahim/filament-modular-permissions)[![License](https://camo.githubusercontent.com/0ec30715ff43addec1ce30e685c196b5f707f39eaacd24bea1594104a0a2945a/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f616264756c726168696d2f66696c616d656e742d6d6f64756c61722d7065726d697373696f6e732e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/abdulrahim/filament-modular-permissions)

A professional Laravel package for modular roles and permissions in **Filament v5**. Supporting multi-panel, auto-syncing, and **Global Zero-Config Protection**.

> **Latest Stable Version**: v1.5.5 **Requirements**: PHP 8.2+, Laravel 11+, Filament 5.x, spatie/laravel-permission ^6|^7

---

[English Documentation](#english-documentation) | [التوثيق العربي](#%D8%A7%D9%84%D8%AA%D9%88%D8%AB%D9%8A%D9%82-%D8%A7%D9%84%D8%B9%D8%B1%D8%A8%D9%8A)

---

English Documentation
=====================

[](#english-documentation)

Table of Contents
-----------------

[](#table-of-contents)

- [Features](#features)
- [Installation](#installation)
- [Initial User (Seeding)](#initial-user-seeding)
- [Configuration](#configuration)
    - [Custom Permissions](#custom-permissions)
    - [Excluding Panels](#excluding-panels)
- [Advanced Features](#advanced-features)
    - [Widget Auto-Protection](#widget-auto-protection)
    - [Diagnostics](#diagnostics)
    - [Advanced Concepts](#advanced-concepts)
- [Manual Control](#manual-control)
- [Available Commands](#available-commands)
- [Contact](#contact)

---

Features
--------

[](#features)

- **Global Zero-Config Shield**: Protect and hide all resources **and widgets** automatically — no traits needed on any file.
- **Smart Sync**: Sync all resources, widgets, and custom permissions with Spatie in one command.
- **Custom Permissions**: Define standalone permissions (e.g. `export_reports`) directly in config.
- **Multi-panel Support**: Publish and manage permissions for each panel independently.
- **Panel Exclusion**: Exclude specific panels from automatic syncing via config; override explicitly with `--panel`.
- **Super Admin Gate**: Automatically grants full access to the `super_admin` role via `Gate::before`.
- **Interactive CLI**: Select your target panel via an interactive CLI menu.
- **Safe Publishing**: Publish commands skip existing files by default; use `--force` to overwrite.
- **Diagnostics**: Inspect any user's roles and permissions with `permissions:check`.
- **Panel User Management**: Pre-configured PanelUserResource with role management and automatic guard-based filtering.
- **Separated Widget Permissions**: Widget permissions appear in a dedicated section in the Role form.
- **Dynamic Resource Labels**: Role permissions sections automatically use the resource's `getNavigationLabel()`.
- **Multi-Panel Isolation**: Resource labels are prioritized by current panel to avoid cross-panel naming conflicts.

Installation
------------

[](#installation)

**Step 1** — Install via Composer:

```
composer require abdulrahim/filament-modular-permissions
```

**Step 2** — Register the plugin in your Panel Provider:

```
use Abdulrahim\FilamentModularPermissions\FilamentModularPermissionsPlugin;

public function panel(Panel $panel): Panel
{
    return $panel
        ->plugins([
            FilamentModularPermissionsPlugin::make(),
        ]);
}
```

**Step 3** — Run the installer:

```
php artisan permissions:install
```

This command does three things automatically:

1. Publishes the **Role Management** Resource
2. Publishes the **Panel User Management** Resource
3. Syncs all permissions from your Filament panels to the database

Then register both published resources in your Filament panel.

> Or run each step individually if you need more control:
>
> ```
> php artisan permissions:publish-role-resource  # Step 1: publish Role Resource
> php artisan permissions:publish-user-resource  # Step 2: publish User Resource
> php artisan permissions:sync                   # Step 3: sync permissions
> ```

Important

Re-run `php artisan permissions:sync` every time you add a new Resource or Widget to register its permissions in the database.

Tip

To publish to a specific panel, or to re-publish and overwrite existing files:

```
php artisan permissions:install --panel=admin --force
```

Initial User (Seeding)
----------------------

[](#initial-user-seeding)

To create your first Super Admin user, add this to your `DatabaseSeeder.php`:

```
use App\Models\User;
use Spatie\Permission\Models\Role;

public function run(): void
{
    Role::firstOrCreate(['name' => 'super_admin', 'guard_name' => 'web']);

    $admin = User::firstOrCreate(
        ['email' => 'admin@admin.com'],
        [
            'name' => 'Admin',
            'password' => bcrypt('12345678'),
        ]
    );

    $admin->assignRole('super_admin');
}
```

Configuration
-------------

[](#configuration)

### Custom Permissions

[](#custom-permissions)

To add standalone permissions not tied to any resource, define them in your config:

```
// config/filament-modular-permissions.php
'custom_permissions' => [
    'export_reports',
    'access_api',
    'view_dashboard',
],
```

Then run `php artisan permissions:sync` to register them.

### Excluding Panels from Sync

[](#excluding-panels-from-sync)

Exclude specific panels from automatic syncing — useful for API panels, customer portals, or any panel that manages its own permissions separately:

```
// config/filament-modular-permissions.php
'excluded_panels' => [
    'api',
    'customer_portal',
],
```

Excluded panels are skipped by default; use `--panel` to bypass the exclusion explicitly:

```
# Normal sync — skips excluded panels
php artisan permissions:sync

# Force-sync a specific panel (bypasses exclusion)
php artisan permissions:sync --panel=api

# Same via the installer
php artisan permissions:install --panel=api
```

Advanced Features
-----------------

[](#advanced-features)

### Widget Auto-Protection

[](#widget-auto-protection)

Widgets are automatically hidden from users who don't have the required permission — **no trait needed on any widget class**.

The package uses a `Filament::serving()` hook to filter the widget list per-panel before rendering. The permission name follows the pattern `view_{snake_widget_name}`.

Run `php artisan permissions:sync` to register widget permissions, then assign them to roles via the Role form.

In the Role form, widget permissions are displayed in a **dedicated section** below the resource sections, with a wider horizontal layout (4 columns) for easy scanning.

Note

If you set `auto_hide_resources => false` in config, widget auto-protection is also disabled. You can then use the `HandlesWidgetPermissions` trait manually on each widget.

### Diagnostics

[](#diagnostics)

Inspect a user's roles and effective permissions:

```
php artisan permissions:check --user=1
php artisan permissions:check --user=1 --guard=admin
```

### Advanced Concepts

[](#advanced-concepts)

#### 1. Multi-Guard Architecture

[](#1-multi-guard-architecture)

The package handles multi-panel environments where each panel uses a different Auth Guard. Permissions are always isolated per guard.

#### 2. Intelligent Super Admin

[](#2-intelligent-super-admin)

The `super_admin` role is granted full access via a global `Gate::before` check. This hook returns `null` (not `false`) when denying, so your own Policies always remain active.

#### 3. Policy Compatibility

[](#3-policy-compatibility)

The `Gate::before` hook only intercepts known Filament abilities (`viewAny`, `view`, `create`, `update`, `delete`, etc.) on Eloquent models. All other policy checks are unaffected.

#### 4. Model Instance Support

[](#4-model-instance-support)

The gate check handles both class strings (used by `viewAny`/`create`) and model instances (used by `update`/`delete`/`restore`), ensuring all permission types are enforced correctly across all actions.

Manual Control
--------------

[](#manual-control)

Disable the global shield in `config/filament-modular-permissions.php`:

```
'auto_hide_resources' => false,
```

Then use the traits manually in each Resource or Widget:

```
use Abdulrahim\FilamentModularPermissions\Traits\HandlesResourcePermissions;
use Abdulrahim\FilamentModularPermissions\Traits\HandlesWidgetPermissions;
```

Available Commands
------------------

[](#available-commands)

CommandDescription`permissions:install [--panel=] [--force] [--skip-user]`All-in-one installer (publish + sync)`permissions:sync [--panel=]`Sync permissions (skips excluded panels unless `--panel` is set)`permissions:publish-role-resource [--panel=] [--force]`Publish Role Resource files`permissions:publish-user-resource [--panel=] [--force]`Publish User Resource files`permissions:publish-config [--force]`Publish the package config file`permissions:publish-lang [--force] [--lang=]`Publish translation files (optionally one language only)`permissions:check [--user=] [--guard=]`Diagnose user roles and permissionsContact
-------

[](#contact)

Email:
Website: [abaad.dev](https://abaad.dev)

---

التوثيق العربي
==============

[](#التوثيق-العربي)

> **آخر إصدار مستقر**: v1.5.5 **المتطلبات**: PHP 8.2+، Laravel 11+، Filament 5.x، spatie/laravel-permission ^6|^7

فهرس المحتويات
--------------

[](#فهرس-المحتويات)

- [المميزات الرئيسية](#%D8%A7%D9%84%D9%85%D9%85%D9%8A%D8%B2%D8%A7%D8%AA-%D8%A7%D9%84%D8%B1%D8%A6%D9%8A%D8%B3%D9%8A%D8%A9)
- [التثبيت](#%D8%A7%D9%84%D8%AA%D8%AB%D8%A8%D9%8A%D8%AA-1)
- [إنشاء المستخدم الأول](#%D8%A5%D9%86%D8%B4%D8%A7%D8%A1-%D8%A7%D9%84%D9%85%D8%B3%D8%AA%D8%AE%D8%AF%D9%85-%D8%A7%D9%84%D8%A3%D9%88%D9%84)
- [الإعدادات](#%D8%A7%D9%84%D8%A5%D8%B9%D8%AF%D8%A7%D8%AF%D8%A7%D8%AA-1)
    - [الصلاحيات المخصصة](#%D8%A7%D9%84%D8%B5%D9%84%D8%A7%D8%AD%D9%8A%D8%A7%D8%AA-%D8%A7%D9%84%D9%85%D8%AE%D8%B5%D8%B5%D8%A9-1)
    - [استثناء اللوحات](#%D8%A7%D8%B3%D8%AA%D8%AB%D9%86%D8%A7%D8%A1-%D8%A7%D9%84%D9%84%D9%88%D8%AD%D8%A7%D8%AA)
- [المميزات المتقدمة](#%D8%A7%D9%84%D9%85%D9%85%D9%8A%D8%B2%D8%A7%D8%AA-%D8%A7%D9%84%D9%85%D8%AA%D9%82%D8%AF%D9%85%D8%A9-1)
    - [الحماية التلقائية للويدجت](#%D8%A7%D9%84%D8%AD%D9%85%D8%A7%D9%8A%D8%A9-%D8%A7%D9%84%D8%AA%D9%84%D9%82%D8%A7%D8%A6%D9%8A%D8%A9-%D9%84%D9%84%D9%88%D9%8A%D8%AF%D8%AC%D8%AA-1)
    - [تشخيص الأذونات](#%D8%AA%D8%B4%D8%AE%D9%8A%D8%B5-%D8%A7%D9%84%D8%A3%D8%B0%D9%88%D9%86%D8%A7%D8%AA-1)
- [التحكم اليدوي](#%D8%A7%D9%84%D8%AA%D8%AD%D9%83%D9%85-%D8%A7%D9%84%D9%8A%D8%AF%D9%88%D9%8A-1)
- [الأوامر المتاحة](#%D8%A7%D9%84%D8%A3%D9%88%D8%A7%D9%85%D8%B1-%D8%A7%D9%84%D9%85%D8%AA%D8%A7%D8%AD%D8%A9-1)
- [التواصل](#%D8%A7%D9%84%D8%AA%D9%88%D8%A7%D8%B5%D9%84-1)

---

المميزات الرئيسية
-----------------

[](#المميزات-الرئيسية)

- **الحماية الشاملة التلقائية**: حماية المسارات وإخفاء الموارد **والويدجت** من القائمة الجانبية تلقائياً — دون الحاجة لأي Trait.
- **نظام مزامنة ذكي**: أمر واحد لمزامنة جميع الموارد والويدجت والصلاحيات المخصصة.
- **صلاحيات مخصصة**: تعريف صلاحيات مستقلة مثل `export_reports` من الـ config مباشرةً.
- **دعم تعدد اللوحات**: إدارة الصلاحيات لكل لوحة تحكم بشكل مستقل تماماً.
- **استثناء اللوحات**: استثناء لوحات معينة من المزامنة التلقائية مع إمكانية تجاوز الاستثناء بـ `--panel`.
- **السوبر أدمن**: نظام `Gate::before` يعطي كافة الصلاحيات لدور `super_admin` تلقائياً.
- **نشر آمن**: أوامر النشر تتجاوز الملفات الموجودة افتراضياً؛ استخدم `--force` للكتابة فوقها.
- **تشخيص الأذونات**: فحص أدوار وصلاحيات أي مستخدم عبر `permissions:check`.
- **إدارة المستخدمين**: مورد إدارة مستخدمين جاهز مع إمكانية ربط الأدوار.
- **قسم منفصل للويدجت**: صلاحيات الويدجت تُعرض في قسم خاص بها في نموذج إنشاء الأدوار.

التثبيت
-------

[](#التثبيت)

**الخطوة الأولى** — تحميل المكتبة عبر Composer:

```
composer require abdulrahim/filament-modular-permissions
```

**الخطوة الثانية** — تسجيل الإضافة في مسببات اللوحة (Panel Provider):

```
use Abdulrahim\FilamentModularPermissions\FilamentModularPermissionsPlugin;

public function panel(Panel $panel): Panel
{
    return $panel
        ->plugins([
            FilamentModularPermissionsPlugin::make(),
        ]);
}
```

**الخطوة الثالثة** — تشغيل المثبت:

```
php artisan permissions:install
```

يقوم هذا الأمر بثلاثة أشياء تلقائياً:

1. نشر **واجهة إدارة الأدوار**
2. نشر **واجهة إدارة مستخدمي اللوحة**
3. مزامنة جميع الصلاحيات من لوحات Filament إلى قاعدة البيانات

بعد ذلك، سجّل الـ Resources المنشورة في لوحة Filament الخاصة بك.

> أو نفّذ كل خطوة بشكل منفرد:
>
> ```
> php artisan permissions:publish-role-resource  # الخطوة 1: نشر واجهة الأدوار
> php artisan permissions:publish-user-resource  # الخطوة 2: نشر واجهة المستخدمين
> php artisan permissions:sync                   # الخطوة 3: مزامنة الصلاحيات
> ```

Important

أعد تشغيل `php artisan permissions:sync` في كل مرة تضيف فيها مورداً (Resource) أو ويدجت (Widget) جديداً.

Tip

للنشر على لوحة محددة أو لإعادة النشر فوق الملفات الموجودة:

```
php artisan permissions:install --panel=admin --force
```

إنشاء المستخدم الأول
--------------------

[](#إنشاء-المستخدم-الأول)

لإنشاء مستخدم "سوبر أدمن" أول، أضف الكود التالي لملف `DatabaseSeeder.php`:

```
use App\Models\User;
use Spatie\Permission\Models\Role;

Role::firstOrCreate(['name' => 'super_admin', 'guard_name' => 'web']);

$admin = User::firstOrCreate(['email' => 'admin@admin.com'], [
    'name' => 'Admin',
    'password' => bcrypt('12345678'),
]);

$admin->assignRole('super_admin');
```

الإعدادات
---------

[](#الإعدادات)

### الصلاحيات المخصصة

[](#الصلاحيات-المخصصة)

لإضافة صلاحيات مستقلة غير مرتبطة بمورد معين، قم بتعريفها في ملف الإعدادات:

```
// config/filament-modular-permissions.php
'custom_permissions' => [
    'export_reports',
    'access_api',
],
```

ثم شغّل: `php artisan permissions:sync`

### استثناء اللوحات

[](#استثناء-اللوحات)

مفيد للوحات API أو البوابات الخارجية التي تدير صلاحياتها بشكل مستقل:

```
// config/filament-modular-permissions.php
'excluded_panels' => [
    'api',
    'customer_portal',
],
```

```
# مزامنة عادية — يتخطى اللوحات المستثناة
php artisan permissions:sync

# إجبار مزامنة لوحة محددة (يتجاوز الاستثناء)
php artisan permissions:sync --panel=api

# نفس الشيء عبر المثبت
php artisan permissions:install --panel=api
```

المميزات المتقدمة
-----------------

[](#المميزات-المتقدمة)

### الحماية التلقائية للويدجت

[](#الحماية-التلقائية-للويدجت)

يتم إخفاء الويدجت تلقائياً عن المستخدمين غير المصرح لهم — **بدون أي Trait** على الويدجت. تعمل الحماية عبر `Filament::serving()` الذي يفلتر قائمة الويدجت لكل لوحة قبل العرض.

اسم الصلاحية: `view_{اسم_الويدجت_بـ_snake_case}` — شغّل `permissions:sync` لتسجيلها.

في نموذج الأدوار، تظهر صلاحيات الويدجت في **قسم منفصل** أسفل صلاحيات الأقسام بتخطيط أفقي (4 أعمدة).

### تشخيص الأذونات

[](#تشخيص-الأذونات)

لفحص أدوار وصلاحيات مستخدم معين:

```
php artisan permissions:check --user=1
php artisan permissions:check --user=1 --guard=admin
```

التحكم اليدوي
-------------

[](#التحكم-اليدوي)

إذا أردت تعطيل الحماية التلقائية واستخدام الـ Traits يدوياً:

```
// في ملف config/filament-modular-permissions.php
'auto_hide_resources' => false,

// ثم استخدم الـ Traits في الموارد أو الويدجت
use Abdulrahim\FilamentModularPermissions\Traits\HandlesResourcePermissions;
use Abdulrahim\FilamentModularPermissions\Traits\HandlesWidgetPermissions;
```

الأوامر المتاحة
---------------

[](#الأوامر-المتاحة)

الأمرالوصف`permissions:install [--panel=] [--force] [--skip-user]`المثبت الموحد (نشر + مزامنة)`permissions:sync [--panel=]`مزامنة الصلاحيات (يتخطى المستثناة ما لم يُحدد `--panel`)`permissions:publish-role-resource [--panel=] [--force]`نشر ملفات إدارة الأدوار`permissions:publish-user-resource [--panel=] [--force]`نشر ملفات إدارة المستخدمين`permissions:publish-config [--force]`نشر ملف الإعدادات (config)`permissions:publish-lang [--force] [--lang=]`نشر ملفات الترجمة (اختياريًا لغة محددة فقط)`permissions:check [--user=] [--guard=]`تشخيص أدوار وصلاحيات مستخدمالتواصل
-------

[](#التواصل)

البريد الإلكتروني:
الموقع الإلكتروني: [abaad.dev](https://abaad.dev)

License
-------

[](#license)

MIT License.

###  Health Score

43

—

FairBetter than 89% of packages

Maintenance95

Actively maintained with recent releases

Popularity8

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity52

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~0 days

Total

10

Last Release

24d ago

PHP version history (2 changes)v1.0.0PHP ^8.1

v1.2.0PHP ^8.2

### Community

Maintainers

![](https://www.gravatar.com/avatar/de78bc8783aaac26243bfa8b9ad2ef2f2e0e1d217fa034723e6f7a13439bce6c?d=identicon)[abaad](/maintainers/abaad)

---

Top Contributors

[![AbdulrahimAl-Ghazi](https://avatars.githubusercontent.com/u/56230780?v=4)](https://github.com/AbdulrahimAl-Ghazi "AbdulrahimAl-Ghazi (16 commits)")

### Embed Badge

![Health badge](/badges/abdulrahim-filament-modular-permissions/health.svg)

```
[![Health](https://phpackages.com/badges/abdulrahim-filament-modular-permissions/health.svg)](https://phpackages.com/packages/abdulrahim-filament-modular-permissions)
```

###  Alternatives

[bezhansalleh/filament-shield

Filament support for `spatie/laravel-permission`.

2.8k3.5M115](/packages/bezhansalleh-filament-shield)[althinect/filament-spatie-roles-permissions

3441.1M10](/packages/althinect-filament-spatie-roles-permissions)[jeffgreco13/filament-breezy

A custom package for Filament with login flow, profile and teams support.

1.0k1.9M52](/packages/jeffgreco13-filament-breezy)[chiiya/filament-access-control

Admin user, role and permission management for Laravel Filament

21851.1k](/packages/chiiya-filament-access-control)[stephenjude/filament-two-factor-authentication

Filament Two Factor Authentication: Google 2FA + Passkey Authentication

84192.9k7](/packages/stephenjude-filament-two-factor-authentication)[rawilk/profile-filament-plugin

Profile & MFA starter kit for filament.

3913.7k](/packages/rawilk-profile-filament-plugin)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)