Jaga

• 📸 Preview
• ✨ Features
  • 🎭 Roles
  • 👤 UserRolesField
  • 🔑 Permissions
• 📋 Requirements
• 🚀 Installation
• ⚙️ Configuration
• 🎨 Customising the Plugin
• 👤 UserRolesField
• 🗄️ Cache & Sync
• 🌐 Publishing Translations
• 📦 Related
• License

A FilamentPHP v5 plugin for managing roles and permissions, powered by laraditz/jaga. Simple to set up. Easy to extend.

#📸 Preview

#✨ Features

#🎭 Roles

• Create roles with a name and auto-generated slug
• Assign permissions via checkbox list grouped by permission group
• Add wildcard patterns (e.g. posts.*) for broad permission grants
• Edit or delete existing roles

#👤 UserRolesField

• Drop a single form field into your own User resource to assign roles
• Checkbox list with role name and slug hint, bulk-toggle support
• Zero extra wiring — saves automatically when the form saves

#🔑 Permissions

• Tabs — switch between All, Route (auto-discovered), and Custom permissions
• Grouping — table rows grouped by permission group for easy scanning
• Filters — filter by access level (public, auth, restricted) or show soft-deleted records
• Edit — update the group, description, and access level of any permission
• Create — add custom permissions not tied to any route
• Delete — remove custom permissions (auto-discovered route permissions cannot be deleted)
• Roles tab — view, attach, and detach roles assigned to a permission
• Users tab — view, attach, and detach users assigned directly to a permission
• Sync button — trigger a permission sync from the panel without touching the CLI

#📋 Requirements

#🚀 Installation

1. Install via Composer:

composer require laraditz/filament-jaga

2. Publish the migrations and run them:

php artisan vendor:publish --tag=jaga-migrations
php artisan migrate

3. Add the HasRoles trait to your User model:

use Laraditz\Jaga\Traits\HasRoles;

class User extends Authenticatable
{
    use HasRoles;
}

4. Register the plugin and protect your panel in your Filament panel provider:

use Laraditz\FilamentJaga\FilamentJagaPlugin;
use Laraditz\Jaga\Middleware\JagaMiddleware;

public function panel(Panel $panel): Panel
{
    return $panel
        ->plugin(FilamentJagaPlugin::make())
        ->authMiddleware([JagaMiddleware::class]);
}

5. Run the installer:

php artisan jaga:install

This will:

• Publish the config file
• Seed the jaga.access permission and super-admin role
• Assign the super-admin role to a user of your choice

To assign the role to an existing user non-interactively:

php artisan jaga:install --email=admin@example.com

To re-assign the role without re-seeding:

php artisan jaga:install --assign --email=admin@example.com

6. Protect your app routes with the jaga middleware:

// routes/web.php
Route::middleware(['auth', 'jaga'])->group(function () {
    Route::resource('posts', PostController::class);
});

7. Sync your named routes to the permissions table:

php artisan jaga:sync

After syncing, all your named routes will appear as permissions in the Filament panel, ready to be assigned to roles.

#⚙️ Configuration

Publish the config file:

php artisan vendor:publish --tag=filament-jaga-config

config/filament-jaga.php:

return [
    'navigation' => [
        'group' => 'Roles & Permissions', // sidebar group label
        'icon'  => 'heroicon-o-shield-check',
        'sort'  => 10,
    ],

    'resources' => [
        'roles'       => true, // set false to hide the Roles resource
        'permissions' => true, // set false to hide the Permissions resource
    ],

    // Permission required to access any page in this plugin
    'permission' => 'jaga.access',

    // Your app's User model
    'user_model' => \App\Models\User::class,
];

#🎨 Customising the Plugin

All options are available via a fluent API:

FilamentJagaPlugin::make()
    ->navigationGroup('Access Control')
    ->navigationIcon('heroicon-o-lock-closed')
    ->navigationSort(5)
    ->permission('admin.access')
    ->userModel(\App\Models\Admin::class)
    ->disableResource('permissions') // hide the Permissions resource

#👤 UserRolesField

Drop UserRolesField into your own User resource to let admins assign roles from the User edit form — no extra observers or lifecycle hooks needed.

use Filament\Schemas\Schema;
use Laraditz\FilamentJaga\Forms\Components\UserRolesField;

public static function form(Schema $schema): Schema
{
    return $schema->components([
        // ... your other fields ...
        UserRolesField::make('jaga_roles'),
    ]);
}

The field renders a Roles checkbox list (name + slug hint, with bulk-toggle). All changes are persisted automatically when the form saves.

#🗄️ Cache & Sync

Jaga caches permission data for performance. After making changes to permissions or roles, manage the cache with:

php artisan jaga:sync    # discover and sync route permissions to the database
php artisan jaga:cache   # rebuild the permission cache
php artisan jaga:clear   # clear the permission cache

You can also trigger a sync directly from the Filament panel — head to the Permissions page and click the Sync Permissions button. This dispatches the sync job to the queue without needing CLI access.

#🌐 Publishing Translations

php artisan vendor:publish --tag=filament-jaga-lang

Language files will be published to lang/vendor/filament-jaga.

#📦 Related

This plugin is a UI layer on top of laraditz/jaga. Head over there for the full documentation on permissions, roles, middleware usage, and more.

#License

MIT