README

Role and permission management for Vendra applications.

Features

• Filament cluster on the admin panel for permission management
• Role and permission CRUD resources
• Manage role-permission relations from role pages
• Tenant-scoped Pennant feature flags for module/resource access
• Feature toggle Artisan command per tenant
• Policy classes and enums for role/permission actions
• Translation files for en and fa
• Configurable Gate::after() superadmin bypass role

Requirements

• PHP 8.2+
• Laravel 12
• Filament 5
• Livewire 4
• Pest 4
• Tailwind CSS 4
• laravel/pennant
• misaf/vendra-tenant
• misaf/vendra-user
• misaf/vendra-activity-log
• awcodes/filament-badgeable-column
• mokhosh/filament-jalali
• spatie/laravel-permission

Installation

composer require misaf/vendra-permission

Publish Spatie permission config and migrations (if not already published in your app):

php artisan vendor:publish --provider="Spatie\Permission\PermissionServiceProvider" --tag=permission-config
php artisan vendor:publish --provider="Spatie\Permission\PermissionServiceProvider" --tag=permission-migrations
php artisan migrate

Optional: publish module translations:

php artisan vendor:publish --tag=vendra-permission-translations

Optional: publish module config:

php artisan vendor:publish --tag=vendra-permission-config

If you use Pennant with the database driver, ensure Pennant storage is migrated in your application.

Configuration

If you want Spatie to use this module's models everywhere in your app, set config/permission.php:

'models' => [
    'permission' => Misaf\VendraPermission\Models\Permission::class,
    'role' => Misaf\VendraPermission\Models\Role::class,
],

Superadmin bypass role is configurable in config/vendra-permission.php:

'super_admin_role' => env('VENDRA_PERMISSION_SUPER_ADMIN_ROLE', 'superadmin'),

The config key is super_admin_role (short and local to this file). The env var remains VENDRA_PERMISSION_SUPER_ADMIN_ROLE (prefixed to avoid global collisions). This value is used for both Gate::after() superadmin bypass and excluding that role from the roles table query.

Pennant feature behavior is configured in config/vendra-permission.php:

'features' => [
    'enabled' => env('VENDRA_PERMISSION_FEATURES_ENABLED', false),
    'discover' => env('VENDRA_PERMISSION_FEATURES_DISCOVER', false),
    'defaults' => [
        'vendra-permission.module-enabled' => false,
        'vendra-permission.role-management' => false,
        'vendra-permission.permission-management' => false,
        'vendra-permission.bulk-role-assignment' => false,
    ],
],

When features.discover is enabled, the package calls:

Feature::discover('Misaf\\VendraPermission\\Features', __DIR__ . '/Features');

if the directory exists.

Filament

Resources are registered on the admin panel through PermissionPlugin:

• Roles
• Permissions

Navigation cluster: permissions

Access is feature-gated per tenant using Feature::for(Tenant::current()):

• vendra-permission.module-enabled controls cluster access
• vendra-permission.role-management controls role resource access
• vendra-permission.permission-management controls permission resource access
• vendra-permission.bulk-role-assignment controls attach/detach role bulk actions

Permission Bulk Actions

AttachRolesAction and DetachRolesAction share role-resolution logic via:

• Misaf\VendraPermission\Filament\Clusters\Resources\Permissions\Actions\Concerns\ResolvesSelectedRoles

The trait provides:

• getRoleSelectOptions() for the roles multiselect options (name (guard_name))
• resolveRoleIdsByGuardFromPayload() to load selected roles with whereKey(...) and group by guard_name

This keeps attach/detach behavior consistent and prevents cross-guard role operations when processing selected Permission records.

Pennant Features

Feature keys are defined in:

• Misaf\VendraPermission\Enums\PermissionFeatureEnum

Resolver registration lives in:

• Misaf\VendraPermission\Providers\PermissionServiceProvider::packageBooted()

Resolver behavior:

• non-tenant scopes are denied (false)
• features.enabled must be true
• unresolved values fall back to features.defaults

Feature map:

Artisan Commands

Toggle tenant features with:

php artisan vendra-permission:feature {activate|deactivate} {feature|all} {tenant}

feature accepts:

• enum case name, e.g. ROLE_MANAGEMENT
• full key, e.g. vendra-permission.role-management
• short key, e.g. role-management
• all

tenant accepts:

• tenant id
• tenant slug

The command requires vendra-permission.features.enabled to be true.

Examples:

php artisan vendra-permission:feature activate module-enabled 1
php artisan vendra-permission:feature activate permission-management acme
php artisan vendra-permission:feature deactivate all acme

Per-feature console reference (<tenant> can be tenant id or slug):

# MODULE_ENABLED
php artisan vendra-permission:feature activate MODULE_ENABLED <tenant>
php artisan vendra-permission:feature deactivate MODULE_ENABLED <tenant>

# ROLE_MANAGEMENT
php artisan vendra-permission:feature activate ROLE_MANAGEMENT <tenant>
php artisan vendra-permission:feature deactivate ROLE_MANAGEMENT <tenant>

# PERMISSION_MANAGEMENT
php artisan vendra-permission:feature activate PERMISSION_MANAGEMENT <tenant>
php artisan vendra-permission:feature deactivate PERMISSION_MANAGEMENT <tenant>

# BULK_ROLE_ASSIGNMENT
php artisan vendra-permission:feature activate BULK_ROLE_ASSIGNMENT <tenant>
php artisan vendra-permission:feature deactivate BULK_ROLE_ASSIGNMENT <tenant>

Usage

Use this package's tenant feature flags and console command to control access in each tenant:

• vendra-permission.module-enabled
• vendra-permission.role-management
• vendra-permission.permission-management
• vendra-permission.bulk-role-assignment

Role/permission CRUD and assignment semantics follow Spatie Permission. See: https://spatie.be/docs/laravel-permission

Development

composer analyse
composer format

Keeping This README Updated

Update this file whenever these change:

• composer.json requirements
• Pennant feature keys, defaults, or resolver behavior
• feature command signature or behavior
• Filament resources, pages, or cluster names
• Translation keys/files in resources/lang
• Authorization behavior in policies or PermissionServiceProvider
• Installation steps (especially migration/config behavior)

Testing

composer test

License

MIT. See LICENSE.