Laravel Roles and Permissions: Build a System

Updated 6 November 2026 · Standard formula, shown below

This article explains how to build a database-driven roles and permissions system in Laravel. You will learn the core concepts, step-by-step implementation, and common pitfalls, so you can create a flexible authorization layer for your application.

Why You Need a Roles and Permissions System

Most web applications have users with different levels of access. A simple admin flag works for tiny projects, but as your app grows, you need granular control: who can create posts, edit users, view reports, or delete comments. A roles and permissions system lets you assign roles (e.g., admin, editor, subscriber) to users and permissions (e.g., create-post, edit-post) to roles. This decouples authorization from individual user records, making it easy to manage at scale.

Core Concepts: Roles, Permissions, and Gates

In Laravel, authorization is typically handled with Gates (closures that check abilities) and Policies (classes that group abilities for a model). A roles and permissions package like Spatie/laravel-permission builds on these by adding database tables for roles and permissions, and helper methods like hasRole() and hasPermissionTo(). The underlying data model is simple:

roles: id, name, guard_name
permissions: id, name, guard_name
model_has_roles: role_id, model_type, model_id
model_has_permissions: permission_id, model_type, model_id
role_has_permissions: role_id, permission_id

This many-to-many structure lets you attach permissions directly to a user or via a role. The guard_name column allows different guards (e.g., web, api) to have separate permission sets.

How to Build It: Step-by-Step

While you can write your own tables and logic, the recommended approach is to use the Spatie package, which is battle-tested and follows Laravel conventions. Here’s how to set it up:

Install the package via Composer: composer require spatie/laravel-permission
Publish the migration and config: php artisan vendor:publish --provider="Spatie\Permission\PermissionServiceProvider"
Run migrations: php artisan migrate
Add the HasRoles trait to your User model: use HasRoles;
Create roles and permissions in a seeder or via tinker: Role::create(['name' => 'admin']); Permission::create(['name' => 'edit articles']);
Assign permissions to roles: $role->givePermissionTo('edit articles');
Assign roles to users: $user->assignRole('admin');

Now you can check access in your code: $user->hasRole('admin') or $user->can('edit articles'). For Blade templates, use @can('edit articles').

How to Choose: Package vs. Custom Build

You might wonder whether to use a package or write your own. Here’s a quick comparison:

Package (Spatie): Pros – well-documented, actively maintained, includes blade directives, middleware, and caching. Cons – adds a dependency, may have features you don’t need.
Custom build: Pros – full control, no extra dependency, tailored to your exact needs. Cons – more code to maintain, you must handle edge cases (caching, multiple guards, etc.) yourself.

For most projects, the package is the pragmatic choice. If you only need a simple admin flag, skip both and use a boolean column.

Common Problems and Solutions

Here are frequent pitfalls and how to avoid them:

Cache issues: Permissions are cached by default. After changing roles/permissions, run php artisan permission:cache-reset or use the package’s built-in cache busting.
Guard mismatch: If you have multiple guards, ensure you specify the correct guard when creating roles/permissions. For API routes, you might need guard_name => 'api'.
Super admin bypass: Many apps want a “super admin� who bypasses all checks. Implement this by adding a check in your Gate::before or using a middleware that grants all permissions to that role.
Seeding order: When seeding, create permissions first, then roles, then attach. Use firstOrCreate to avoid duplicates.
Policy not working: If a policy isn’t being used, make sure you register it in AuthServiceProvider and that the model’s class name matches.

Best Practices for Managing Permissions

To keep your system maintainable:

Use a naming convention like verb-noun (e.g., create-post, edit-post).
Group permissions by feature in your UI to make admin panels easier.
Cache roles and permissions to avoid extra queries, but invalidate on changes.
Use middleware like role:admin or permission:edit articles for route protection.
Test your authorization with feature tests to ensure only the right users can access endpoints.

Alternatives and Comparisons

Besides Spatie, there are other packages like Laratrust and Bouncer. Laratrust offers teams support and a different API. Bouncer is more focused on simplicity and uses a similar table structure. If you prefer a more lightweight approach, you can use Laravel’s built-in Gates with a simple is_admin boolean. For complex enterprise needs, consider integrating with an external identity provider that handles authorization (e.g., OAuth scopes).

Costs and Performance Considerations

Using a package like Spatie adds a few database queries per request unless you cache. With caching, the overhead is minimal. The package itself is free and open-source. The main cost is learning time and the occasional need to debug authorization issues. For large applications, you might need to index the pivot tables and consider using a dedicated cache store like Redis.

Security and Safety Tips

Authorization is a security-critical feature. Follow these guidelines:

Always check permissions on the server side; never rely solely on UI hiding.
Use policies for model-level authorization to avoid duplicating logic.
Be careful with mass assignment; ensure role/permission IDs are not fillable on User model.
Regularly audit your roles and permissions to remove unused ones.
When using multiple guards, ensure that a user from one guard cannot access another guard’s routes.

Frequently Asked Questions

Can I assign permissions directly to a user without a role?

Yes, the Spatie package allows you to do $user->givePermissionTo('edit articles'). This is useful for one-off exceptions, but it’s better to use roles for consistency.

How do I create a super admin who bypasses all checks?

In your AuthServiceProvider’s Gate::before, check if the user has a specific role (e.g., ‘super-admin’) and return true. This will grant them all abilities.

Do I need to cache permissions?

It’s recommended for production to avoid extra queries. Spatie caches permissions by default; just remember to reset the cache when you change permissions.

Can I use roles and permissions with API authentication?

Yes, you can create roles and permissions with the api guard. Use Role::create(['name' => 'editor', 'guard_name' => 'api']). Then assign to users via the API guard.

What if I need hierarchical roles?

You can implement a simple hierarchy by adding a parent_id to roles or by defining role inheritance in your logic. The package doesn’t support this out of the box, but you can extend it.

Conclusion

Building a database-driven roles and permissions system in Laravel is straightforward with the right tools. Start with the Spatie package, follow best practices, and you’ll have a robust authorization layer. Remember to test thoroughly and keep security in mind.

Method: the standard formula for this calculation, rounded as each result states. See how the calculators work or report an error.