Download the PHP package iamgerwin/nova-spatie-role-permission without Composer

Laravel 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

• 🔐 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

• 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

Step 1: Install the package

Install the package via composer:

Step 2: Publish Configuration (Optional but Recommended)

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

Step 3: Clear Caches

After installation, clear all caches to ensure proper loading:

Step 4: Set up Spatie Permissions

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

Step 5: Register the Tool

Register the tool in your NovaServiceProvider:

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

Quick Setup (Alternative)

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

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:

Configuration

Publish the configuration file to customize the package:

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

Verify Installation

After installation, verify everything is properly configured:

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

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

Using MorphToMany Field (Recommended)

Using Boolean Group Fields

For a checkbox-style interface:

Using Select Field for Single Role

Advanced Configuration

Custom Resources

You can use your own Nova resources:

Custom Policies

Define your own authorization policies:

Guard Configuration

Specify custom guards for roles and permissions:

Middleware

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

Bulk Actions

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

Localization

The package supports internationalization. Publish the language files:

Available languages:

• English (en)

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

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

The package's policies check for these 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

• 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

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

Custom Authorization Policies

To override the default policies with your own logic:

1. Create custom policy classes:

2. Register your custom policies with the tool:

Testing

Development

Code Quality

Run code formatting:

Run static analysis:

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

Common Issues and Solutions

"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):

2. Clear all caches:

Package Not Working After Installation

If the package isn't working after installation:

Missing Permissions or Roles

If permissions or roles aren't showing up:

1. Check if migrations have been run:

2. Clear the permission cache:

3. Verify your models are configured correctly:

Authorization Not Working

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

1. Ensure the user has the correct permissions:

2. Clear permission cache:

3. Check if super-admin role is configured:

Verification Command

Use the verification command to diagnose installation issues:

This command checks:

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

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
3. Review the CHANGELOG for recent changes
4. Ensure you're using compatible versions (see Requirements section)

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• iamgerwin
• All Contributors

This package is based on the original work by vyuldashev/nova-permission and has been updated and enhanced for modern Laravel, Nova, and PHP versions.

License

The MIT License (MIT). Please see License File for more information.