PHPackages                             aiarmada/filament-authz - 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. aiarmada/filament-authz

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

aiarmada/filament-authz
=======================

Filament v5 permissions suite powered by Spatie laravel-permission with multi-guard, panel-aware gating, and admin UX.

v0.1.33(4w ago)0914↓53.3%1MITPHPPHP ^8.4

Since May 21Pushed 3w agoCompare

[ Source](https://github.com/AIArmada/filament-authz)[ Packagist](https://packagist.org/packages/aiarmada/filament-authz)[ Docs](https://github.com/aiarmada/commerce)[ RSS](/packages/aiarmada-filament-authz/feed)WikiDiscussions main Synced 3w ago

READMEChangelogDependencies (33)Versions (40)Used By (1)

Filament Authz
==============

[](#filament-authz)

A comprehensive Filament v5 authorization package extending Spatie laravel-permission with wildcard permissions, multi-panel support, and automatic entity discovery.

Features
--------

[](#features)

- **Super Admin Bypass** — Configure a role that automatically bypasses all permission checks via `Gate::before`
- **Wildcard Permissions** — Support for patterns like `orders.*` to match `orders.view`, `orders.create`, etc.
- **Role & Permission Resources** — Clean Filament UI for managing roles and permissions with tabbed interface
- **Automatic Discovery** — Discovers Resources, Pages, and Widgets to generate permissions automatically
- **Multi-Panel Support** — Configure different authorization settings per Filament panel
- **Policy Generation** — CLI command to scaffold Laravel Policies based on discovered permissions
- **Authz Scopes + Tenant Scoping** — Scope roles to any model (institutions, speakers, etc.) with central app support and optional commerce-support integration
- **UUID-First Schema** — Permissions, roles, and pivot tables use UUID keys and follow Spatie Permission's documented UUID approach

Requirements
------------

[](#requirements)

- PHP 8.4+
- Laravel 13+
- Filament 5.0+
- Spatie laravel-permission 7.2+

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

[](#installation)

```
composer require aiarmada/filament-authz
```

Publish the configuration:

```
php artisan vendor:publish --tag=filament-authz-config
```

Run migrations:

```
php artisan migrate
```

> `filament-authz` ships UUID-based migrations for Spatie Permission tables (`permissions`, `roles`, `model_has_permissions`, `model_has_roles`, and `role_has_permissions`) plus its own `authz_scopes` migration. The schema, models, and pivot keys are all UUID-based together.

Setup
-----

[](#setup)

### Add HasRoles Trait

[](#add-hasroles-trait)

Add the `HasRoles` trait to your User model:

```
use Spatie\Permission\Traits\HasRoles;

class User extends Authenticatable
{
    use HasRoles;
}
```

### Register Plugin

[](#register-plugin)

```
use AIArmada\FilamentAuthz\FilamentAuthzPlugin;
use Filament\Panel;

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

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

[](#configuration)

```
// config/filament-authz.php
return [
    // Authentication guards to support
    'guards' => ['web', 'api'],

    // Role that bypasses all permission checks
    'super_admin_role' => 'super_admin',

    // Enable wildcard permission patterns like 'orders.*'
    'wildcard_permissions' => true,

    // Scope roles and permissions to a tenant/scope (Spatie teams)
    'scoped_to_tenant' => true,

    // Allow managing roles across scopes in a central panel
    'central_app' => false,

    // Optional authz scopes (institutions, speakers, etc.)
    'authz_scopes' => [
        'enabled' => false,
        'auto_create' => true,
    ],

    'role_resource' => [
        'scope_options' => null,
    ],

    'user_resource' => [
        'form' => [
            'role_scope_mode' => 'all', // all, global_only, scoped_only
        ],
    ],

    // Permission key format
    'permissions' => [
        'separator' => '.',
        'case' => 'camel', // snake, kebab, camel, pascal, upper_snake, lower
    ],

    // Navigation settings
    'navigation' => [
        'group' => 'Authz',
        'sort' => 99,
    ],

    // Custom permissions beyond resources/pages/widgets
    'custom_permissions' => [
        // 'approve_posts' => 'Approve Posts',
    ],
];
```

Usage
-----

[](#usage)

### Permission Macros

[](#permission-macros)

```
use Filament\Actions\Action;

// Require a specific permission
Action::make('export')
    ->requiresPermission('order.export');

// Require a role
Action::make('admin-settings')
    ->requiresRole('Admin');

// Require any of multiple roles
Action::make('analytics')
    ->requiresRole(['Admin', 'Analyst']);

// Require any of multiple permissions
Action::make('reports')
    ->requiresAnyPermission(['report.view', 'report.export']);
```

### Wildcard Permissions

[](#wildcard-permissions)

```
// Grant 'orders.*' to a role
$role->givePermissionTo('orders.*');

// This now passes for any 'orders.X' check
$user->can('orders.view');   // true
$user->can('orders.create'); // true
$user->can('orders.delete'); // true
```

### Super Admin Bypass

[](#super-admin-bypass)

Users with the configured super admin role automatically bypass all permission checks:

```
// User with 'super_admin' role passes all gates
Gate::allows('any-permission'); // true
```

Authz Scopes (Optional)
-----------------------

[](#authz-scopes-optional)

Use Authz scopes to attach roles/permissions to any model (institutions, speakers, events, etc.).

```
// config/filament-authz.php
'authz_scopes' => [
    'enabled' => true,
    'auto_create' => true,
],

// config/permission.php
'teams' => true,
'team_foreign_key' => 'authz_scope_id',
```

```
use AIArmada\FilamentAuthz\Concerns\HasAuthzScope;
use AIArmada\FilamentAuthz\Facades\Authz;

class Workspace extends Model
{
    use HasAuthzScope;
}

Authz::userCanInScope($user, 'project.update', $workspace);
```

### Limiting Role Scope Options

[](#limiting-role-scope-options)

If your central panel should only expose a subset of scopes in the Role resource, provide an explicit options map.

```
use AIArmada\FilamentAuthz\FilamentAuthzPlugin;

FilamentAuthzPlugin::make()
    ->roleScopeOptionsUsing([
        'scope-id-1' => 'Team Members',
        'scope-id-2' => 'Support Team',
    ]);
```

Or through config:

```
'role_resource' => [
    'scope_options' => [
        'scope-id-1' => 'Team Members',
        'scope-id-2' => 'Support Team',
    ],
],
```

### Restricting User Role Editing By Scope

[](#restricting-user-role-editing-by-scope)

The User resource can expose:

- `all`
- `global_only`
- `scoped_only`

```
FilamentAuthzPlugin::make()
    ->userRoleScopeMode('global_only');
```

Or through config:

```
'user_resource' => [
    'form' => [
        'role_scope_mode' => 'global_only',
    ],
],
```

Commands
--------

[](#commands)

### Sync Permissions

[](#sync-permissions)

Sync roles and permissions from configuration:

```
php artisan authz:sync
```

### Doctor

[](#doctor)

Diagnose permission configuration issues:

```
php artisan authz:doctor
```

### Cache

[](#cache)

Manage permission cache:

```
php artisan authz:cache --flush
php artisan authz:cache --warm
```

Permission Naming Convention
----------------------------

[](#permission-naming-convention)

Use `{resource}.{ability}` format:

PermissionDescription`user.viewAny`View user list`user.view`View individual user`user.create`Create users`user.update`Update users`user.delete`Delete usersLicense
-------

[](#license)

MIT License. See [LICENSE](LICENSE) for details.

###  Health Score

46

—

FairBetter than 92% of packages

Maintenance94

Actively maintained with recent releases

Popularity18

Limited adoption so far

Community11

Small or concentrated contributor base

Maturity53

Maturing project, gaining track record

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 ~2 days

Total

39

Last Release

29d ago

Major Versions

v1.0.0 → v13.0.12026-03-20

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/1634949?v=4)[Saiffil Fariz](/maintainers/sairiz)[@sairiz](https://github.com/sairiz)

### Embed Badge

![Health badge](/badges/aiarmada-filament-authz/health.svg)

```
[![Health](https://phpackages.com/badges/aiarmada-filament-authz/health.svg)](https://phpackages.com/packages/aiarmada-filament-authz)
```

###  Alternatives

[althinect/filament-spatie-roles-permissions

3461.1M10](/packages/althinect-filament-spatie-roles-permissions)[stephenjude/filament-two-factor-authentication

Filament Two Factor Authentication: Google 2FA + Passkey Authentication

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

Profile & MFA starter kit for filament.

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

Use passkeys in your filamentphp app

6643.3k1](/packages/marcelweidum-filament-passkeys)

PHPackages © 2026

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