PHPackages                             iamgerwin/nova-spatie-role-permission - 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. iamgerwin/nova-spatie-role-permission

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

iamgerwin/nova-spatie-role-permission
=====================================

A Laravel Nova tool for managing roles and permissions via Spatie Laravel Permission

v1.1.7(5mo ago)22.3k3[3 PRs](https://github.com/iamgerwin/nova-spatie-role-permission/pulls)MITPHPPHP ^8.3CI passing

Since Sep 26Pushed 1mo agoCompare

[ Source](https://github.com/iamgerwin/nova-spatie-role-permission)[ Packagist](https://packagist.org/packages/iamgerwin/nova-spatie-role-permission)[ Docs](https://github.com/iamgerwin/nova-spatie-role-permission)[ GitHub Sponsors](https://github.com/:vendor_name)[ RSS](/packages/iamgerwin-nova-spatie-role-permission/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (1)Dependencies (13)Versions (36)Used By (0)

Laravel Nova Spatie Role Permission
===================================

[](#laravel-nova-spatie-role-permission)

[![Latest Version on Packagist](https://camo.githubusercontent.com/52d13cea3260712d6eff6e9b0651690af7bc890f6252ce34924fd05766443c86/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f69616d67657277696e2f6e6f76612d7370617469652d726f6c652d7065726d697373696f6e2e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/iamgerwin/nova-spatie-role-permission)[![GitHub Tests Action Status](https://camo.githubusercontent.com/c319bff1ba817d221416ed8ec0a04dac76cc65607b7c5c7edd394e5780ebcfdd/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f69616d67657277696e2f6e6f76612d7370617469652d726f6c652d7065726d697373696f6e2f72756e2d74657374732e796d6c3f6272616e63683d6d61696e266c6162656c3d7465737473267374796c653d666c61742d737175617265)](https://github.com/iamgerwin/nova-spatie-role-permission/actions?query=workflow%3Arun-tests+branch%3Amain)[![Total Downloads](https://camo.githubusercontent.com/c8fbcbb9e00d92cf362a443d722ea7ff525711b44acec3d1818785098929e835/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f69616d67657277696e2f6e6f76612d7370617469652d726f6c652d7065726d697373696f6e2e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/iamgerwin/nova-spatie-role-permission)

A comprehensive Laravel Nova tool for managing roles and permissions with Spatie's Laravel Permission package. Built for Laravel 11-12, Nova 5, and PHP 8.3+.

Features
--------

[](#features)

- 🔐 **Complete Role & Permission Management** - Full CRUD operations for roles and permissions
- 🎨 **Nova 5 Compatibility** - Built specifically for the latest Laravel Nova
- 🚀 **Laravel 12 Ready** - Supports both Laravel 11 and 12
- 🔧 **Flexible Configuration** - Customize resources, policies, and guards
- 🌍 **Multi-language Support** - Ready for internationalization
- ⚡ **Performance Optimized** - Automatic cache management for permissions
- ✅ **Fully Tested** - Comprehensive test coverage with Pest
- 📱 **User-friendly Interface** - Intuitive boolean groups and select fields

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

[](#requirements)

- PHP 8.3 or higher
- Laravel 11.0 or 12.0
- Laravel Nova 5.0 (required at runtime, not during installation)
- Spatie Laravel Permission 6.0

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

[](#installation)

### Step 1: Install the package

[](#step-1-install-the-package)

Install the package via composer:

```
composer require iamgerwin/nova-spatie-role-permission
```

### Step 2: Publish Configuration (Optional but Recommended)

[](#step-2-publish-configuration-optional-but-recommended)

The package includes default configuration, but you can publish it for customization:

```
php artisan vendor:publish --provider="Iamgerwin\NovaSpatieRolePermission\ToolServiceProvider"
```

### Step 3: Clear Caches

[](#step-3-clear-caches)

After installation, clear all caches to ensure proper loading:

```
php artisan config:clear
php artisan cache:clear
```

### Step 4: Set up Spatie Permissions

[](#step-4-set-up-spatie-permissions)

Publish and run the migrations from Spatie Laravel Permission if you haven't already:

```
php artisan vendor:publish --provider="Spatie\Permission\PermissionServiceProvider"
php artisan migrate
```

### Step 5: Register the Tool

[](#step-5-register-the-tool)

Register the tool in your `NovaServiceProvider`:

```
// app/Providers/NovaServiceProvider.php

use Iamgerwin\NovaSpatieRolePermission\NovaSpatieRolePermissionTool;

public function tools()
{
    return [
        new NovaSpatieRolePermissionTool(),
    ];
}
```

> **Note:** Laravel Nova must be installed and configured in your application before using this package's features.

### Quick Setup (Alternative)

[](#quick-setup-alternative)

For a faster setup, use the installation command which handles most of the above steps:

```
php artisan nova-permission:install
```

This command will:

- Publish the configuration file
- Clear permission cache
- Seed default permissions (optional)
- Create super-admin role with all permissions (optional)
- Assign super-admin role to a user (optional)

You can also use command options for non-interactive installation:

```
# Install with default permissions and super-admin role
php artisan nova-permission:install --seed

# Install and assign super-admin to a specific user
php artisan nova-permission:install --seed --super-admin=admin@example.com
```

### Configuration

[](#configuration)

Publish the configuration file to customize the package:

```
php artisan vendor:publish --tag=nova-permission-config
```

This will create `config/nova-permission.php` where you can customize:

- Default guard for roles and permissions
- Super admin role name
- Enable/disable permission checking
- Cache settings
- Default permissions for seeding
- Custom models, resources, and policies

Usage
-----

[](#usage)

### Verify Installation

[](#verify-installation)

After installation, verify everything is properly configured:

```
php artisan nova-permission:verify
```

This command will check:

- Configuration file status
- Nova and Spatie Permission installation
- Database migrations
- Model configurations
- Nova resource registrations

### Adding Roles and Permissions to User Resource

[](#adding-roles-and-permissions-to-user-resource)

You can add role and permission fields to your User Nova resource in multiple ways:

#### Using MorphToMany Field (Recommended)

[](#using-morphtomany-field-recommended)

```
// app/Nova/User.php

use Laravel\Nova\Fields\MorphToMany;
use Iamgerwin\NovaSpatieRolePermission\Nova\Role;
use Iamgerwin\NovaSpatieRolePermission\Nova\Permission;

public function fields(NovaRequest $request)
{
    return [
        // ... other fields

        MorphToMany::make('Roles', 'roles', Role::class),
        MorphToMany::make('Permissions', 'permissions', Permission::class),
    ];
}
```

#### Using Boolean Group Fields

[](#using-boolean-group-fields)

For a checkbox-style interface:

```
use Iamgerwin\NovaSpatieRolePermission\Fields\RoleBooleanGroup;
use Iamgerwin\NovaSpatieRolePermission\Fields\PermissionBooleanGroup;

public function fields(NovaRequest $request)
{
    return [
        // ... other fields

        RoleBooleanGroup::make('Roles', 'roles')
            ->options(app(config('permission.models.role'))->pluck('name', 'id')->toArray()),

        PermissionBooleanGroup::make('Permissions', 'permissions')
            ->options(app(config('permission.models.permission'))->pluck('name', 'id')->toArray()),
    ];
}
```

#### Using Select Field for Single Role

[](#using-select-field-for-single-role)

```
use Iamgerwin\NovaSpatieRolePermission\Fields\RoleSelect;

public function fields(NovaRequest $request)
{
    return [
        // ... other fields

        RoleSelect::make('Role', 'role')
            ->options(app(config('permission.models.role'))->pluck('name', 'id')->toArray())
            ->displayUsingLabels(),
    ];
}
```

### Advanced Configuration

[](#advanced-configuration)

#### Custom Resources

[](#custom-resources)

You can use your own Nova resources:

```
use App\Nova\CustomRole;
use App\Nova\CustomPermission;

public function tools()
{
    return [
        (new NovaSpatieRolePermissionTool())
            ->roleResource(CustomRole::class)
            ->permissionResource(CustomPermission::class),
    ];
}
```

#### Custom Policies

[](#custom-policies)

Define your own authorization policies:

```
use App\Policies\CustomRolePolicy;
use App\Policies\CustomPermissionPolicy;

public function tools()
{
    return [
        (new NovaSpatieRolePermissionTool())
            ->rolePolicy(CustomRolePolicy::class)
            ->permissionPolicy(CustomPermissionPolicy::class),
    ];
}
```

#### Guard Configuration

[](#guard-configuration)

Specify custom guards for roles and permissions:

```
public function tools()
{
    return [
        (new NovaSpatieRolePermissionTool())
            ->roleGuard('admin')
            ->permissionGuard('api'),
    ];
}
```

### Middleware

[](#middleware)

The package includes automatic permission cache clearing. To enable it, add the middleware to your Nova middleware group:

```
// app/Http/Kernel.php

protected $middlewareGroups = [
    'nova' => [
        // ... other middleware
        \Iamgerwin\NovaSpatieRolePermission\Http\Middleware\ForgetCachedPermissions::class,
    ],
];
```

### Bulk Actions

[](#bulk-actions)

The package includes a bulk action to attach permissions to roles:

```
use Iamgerwin\NovaSpatieRolePermission\Actions\AttachToRole;

public function actions(NovaRequest $request)
{
    return [
        new AttachToRole,
    ];
}
```

Localization
------------

[](#localization)

The package supports internationalization. Publish the language files:

```
php artisan vendor:publish --tag="nova-spatie-role-permission-translations"
```

Available languages:

- English (en)

You can add your own translations in the `resources/lang/vendor/nova-spatie-role-permission` directory.

Authorization
-------------

[](#authorization)

As of version 1.1.0, the package includes secure default policies that check for actual permissions. The policies support granular permissions and a super admin role that bypasses all checks.

### Default Permission Structure

[](#default-permission-structure)

The package's policies check for these permissions:

#### Role Management Permissions

[](#role-management-permissions)

- `view-roles` - View role listings and details
- `create-roles` - Create new roles
- `edit-roles` - Update existing roles
- `delete-roles` - Delete roles
- `restore-roles` - Restore soft-deleted roles
- `force-delete-roles` - Permanently delete roles
- `assign-permissions` - Attach permissions to roles
- `revoke-permissions` - Detach permissions from roles
- `manage-roles` - Full role management (grants all role permissions)

#### Permission Management Permissions

[](#permission-management-permissions)

- `view-permissions` - View permission listings and details
- `create-permissions` - Create new permissions
- `edit-permissions` - Update existing permissions
- `delete-permissions` - Delete permissions
- `restore-permissions` - Restore soft-deleted permissions
- `force-delete-permissions` - Permanently delete permissions
- `assign-roles` - Attach roles to permissions
- `revoke-roles` - Detach roles from permissions
- `manage-permissions` - Full permission management (grants all permission permissions)

#### Super Admin Role

[](#super-admin-role)

- Users with the `super-admin` role bypass all authorization checks

### Custom Authorization Policies

[](#custom-authorization-policies)

To override the default policies with your own logic:

1. Create custom policy classes:

```
// app/Policies/RolePolicy.php
namespace App\Policies;

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

class RolePolicy
{
    public function before(User $user, $ability): ?bool
    {
        // Super admin bypasses all checks
        if ($user->hasRole('super-admin')) {
            return true;
        }

        return null;
    }

    public function viewAny(User $user): bool
    {
        return $user->hasPermissionTo('view-roles');
    }

    public function create(User $user): bool
    {
        return $user->hasPermissionTo('create-roles');
    }

    // ... other methods
}
```

2. Register your custom policies with the tool:

```
public function tools()
{
    return [
        (new NovaSpatieRolePermissionTool())
            ->rolePolicy(App\Policies\RolePolicy::class)
            ->permissionPolicy(App\Policies\PermissionPolicy::class),
    ];
}
```

Testing
-------

[](#testing)

```
composer test
```

Development
-----------

[](#development)

### Code Quality

[](#code-quality)

Run code formatting:

```
composer format
```

Run static analysis:

```
composer analyse
```

> **Note:** Static analysis excludes Nova-dependent files since Nova is not available during package development. These files are fully functional when Nova is installed in your application.

Troubleshooting
---------------

[](#troubleshooting)

### Common Issues and Solutions

[](#common-issues-and-solutions)

#### "Class name must be a valid object or a string" Error

[](#class-name-must-be-a-valid-object-or-a-string-error)

This error occurs when the configuration file is not properly loaded. Solutions:

1. **Publish the configuration file** (if not using defaults):

```
php artisan vendor:publish --provider="Iamgerwin\NovaSpatieRolePermission\ToolServiceProvider"
php artisan config:clear
```

2. **Clear all caches**:

```
php artisan config:clear
php artisan cache:clear
php artisan route:clear
php artisan view:clear
```

#### Package Not Working After Installation

[](#package-not-working-after-installation)

If the package isn't working after installation:

```
# Clear all caches
composer dump-autoload
php artisan config:clear
php artisan cache:clear
php artisan nova:publish

# Verify installation
php artisan nova-permission:verify
```

#### Missing Permissions or Roles

[](#missing-permissions-or-roles)

If permissions or roles aren't showing up:

1. Check if migrations have been run:

```
php artisan migrate:status
```

2. Clear the permission cache:

```
php artisan permission:cache-reset
```

3. Verify your models are configured correctly:

```
php artisan nova-permission:verify
```

#### Authorization Not Working

[](#authorization-not-working)

If users can't access roles/permissions despite having the right permissions:

1. Ensure the user has the correct permissions:

```
// Check in tinker
php artisan tinker
>>> User::find(1)->hasPermissionTo('manage-roles')
```

2. Clear permission cache:

```
php artisan permission:cache-reset
```

3. Check if super-admin role is configured:

```
php artisan nova-permission:verify
```

### Verification Command

[](#verification-command)

Use the verification command to diagnose installation issues:

```
php artisan nova-permission:verify
```

This command checks:

- ✓ Configuration file status
- ✓ Nova installation
- ✓ Spatie Permission installation
- ✓ Database migrations
- ✓ Model configurations
- ✓ Nova resource registrations

### Getting Help

[](#getting-help)

If you're still experiencing issues:

1. Run the verification command and include the output in your issue report
2. Check the [GitHub Issues](https://github.com/iamgerwin/nova-spatie-role-permission/issues)
3. Review the [CHANGELOG](CHANGELOG.md) for recent changes
4. Ensure you're using compatible versions (see Requirements section)

Changelog
---------

[](#changelog)

Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently.

Contributing
------------

[](#contributing)

Please see [CONTRIBUTING](CONTRIBUTING.md) for details.

Security Vulnerabilities
------------------------

[](#security-vulnerabilities)

Please review [our security policy](../../security/policy) on how to report security vulnerabilities.

Credits
-------

[](#credits)

- [iamgerwin](https://github.com/iamgerwin)
- [All Contributors](../../contributors)

This package is based on the original work by [vyuldashev/nova-permission](https://github.com/vyuldashev/nova-permission) and has been updated and enhanced for modern Laravel, Nova, and PHP versions.

License
-------

[](#license)

The MIT License (MIT). Please see [License File](LICENSE.md) for more information.

###  Health Score

49

—

FairBetter than 95% of packages

Maintenance82

Actively maintained with recent releases

Popularity28

Limited adoption so far

Community12

Small or concentrated contributor base

Maturity62

Established project with proven stability

 Bus Factor1

Top contributor holds 86.1% 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 ~3 days

Recently: every ~18 days

Total

23

Last Release

153d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/8f6f1736b8e2833ccb6c4098e4ecb5081d9cd5db2af370fde0365d441fbfbf59?d=identicon)[iamgerwin](/maintainers/iamgerwin)

---

Top Contributors

[![iamgerwin](https://avatars.githubusercontent.com/u/1331683?v=4)](https://github.com/iamgerwin "iamgerwin (31 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (3 commits)")[![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4)](https://github.com/github-actions[bot] "github-actions[bot] (1 commits)")[![timdiels1](https://avatars.githubusercontent.com/u/7079398?v=4)](https://github.com/timdiels1 "timdiels1 (1 commits)")

---

Tags

spatielaravelauthorizationaclrolespermissionsnova

###  Code Quality

TestsPest

Static AnalysisPHPStan

Code StyleLaravel Pint

### Embed Badge

![Health badge](/badges/iamgerwin-nova-spatie-role-permission/health.svg)

```
[![Health](https://phpackages.com/badges/iamgerwin-nova-spatie-role-permission/health.svg)](https://phpackages.com/packages/iamgerwin-nova-spatie-role-permission)
```

###  Alternatives

[spatie/laravel-permission

Permission handling for Laravel 12 and up

12.9k89.8M1.0k](/packages/spatie-laravel-permission)[santigarcor/laratrust

This package provides a flexible way to add Role-based Permissions to Laravel

2.3k5.4M43](/packages/santigarcor-laratrust)[bezhansalleh/filament-shield

Filament support for `spatie/laravel-permission`.

2.8k2.9M88](/packages/bezhansalleh-filament-shield)[silvanite/novatoolpermissions

Laravel Nova Permissions (Roles and Permission based Access Control (ACL))

100256.7k2](/packages/silvanite-novatoolpermissions)[pktharindu/nova-permissions

Laravel Nova Grouped Permissions (ACL)

136387.1k](/packages/pktharindu-nova-permissions)[hasinhayder/tyro

Tyro - The ultimate Authentication, Authorization, and Role & Privilege Management solution for Laravel 12 & 13

6712.1k2](/packages/hasinhayder-tyro)

PHPackages © 2026

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