Guide · Open source
How to use laravel-permission: install, roles and permissions
Updated · written with AI from the project's own documentation and checked against our catalogue data
spatie/laravel-permission is a free, MIT-licensed PHP package for Laravel that tracks which users can do what. You can give a user a permission directly, or give them a role such as 'writer' and let the role carry the permissions. This guide explains what the package does, what you need before you start, and how to call its methods in your code.
laravel-permissionspatie/laravel-permission · ★ 13k · MIT Install options & downloads Quick start
- 1Check prerequisites. Confirm you have a Laravel application, PHP and Composer available.
- 2Install the package. Install spatie/laravel-permission using Composer, following the official documentation for your version.
- 3Set up the database tables. Follow the documentation to prepare the database storage for roles and permissions.
- 4Create permissions and roles. Define the permissions your app needs, such as 'edit articles', and roles such as 'writer'.
- 5Assign access to users. Use givePermissionTo or assignRole on a user, or givePermissionTo on a role.
- 6Check access with can(). Call $user->can('edit articles') to test whether the user has the permission.
What you need before you install laravel-permission
The package is built specifically for Laravel, so you need a Laravel application. The prerequisites are PHP and Composer. If your project is not a Laravel app, this package is not the right fit.
- PHP installed
- Composer installed
- A Laravel application
Install laravel-permission with Composer
The README's install instruction is written as a Composer install of the package. Check the official documentation at https://spatie.be/docs/laravel-permission for the exact steps for your Laravel version, including installation and upgrade guidance.
The README also shows a git clone line for the repository. Use the Composer route for a normal project setup, and refer to the documentation for the full installation procedure.
git clone https://github.com/spatie/laravel-permissionGive users permissions and roles
You can attach a permission directly to a user, or attach a permission to a role and then assign that role to a user. Roles are useful when many users need the same set of access.
// Adding permissions to a user
$user->givePermissionTo('edit articles');
// Adding permissions via a role
$user->assignRole('writer');
$role->givePermissionTo('edit articles');Check permissions with can()
Because permissions are registered on Laravel's gate, you check them with Laravel's default can function. You do not need a separate permission-checking API for this basic case.
$user->can('edit articles');Decide whether laravel-permission fits your project
The package stores roles and permissions in your database. It is a good match for admin panels where different users need different access. The README points to other packages for team or multi-tenant roles: laratrust is named for team support, so check it if you need per-team roles.
The README also lists alternatives: Bouncer, laratrust, entrust and roles. It describes Bouncer as an excellent package and notes that laravel-permission is compared to it in a Laravel News article.
- Good fit: Laravel apps needing role-based access control stored in the database
- Good fit: admin panels with different access levels
- Not a fit: non-Laravel PHP projects
- Not a fit: per-team or multi-tenant roles out of the box; the README points to laratrust for team support
- Not a fit: non-developers, since setup and use require writing code
What people use it for
- Letting writers edit articles while other users only read them
- Giving admin panel users different levels of access
- Storing roles and permissions in your application database so they can be managed from the app
Frequently asked questions
Is laravel-permission free to use?
Yes. The package is licensed under the MIT License, as stated in the README. The README also asks users who run it in production to send a postcard, but this is described as a request, not a licence condition.
What do I need to install laravel-permission?
You need PHP, Composer and a Laravel application. The package is built specifically for Laravel, so it does not work as a general PHP library for other frameworks.
How do I install laravel-permission?
The README describes installation via Composer. Follow the official documentation at https://spatie.be/docs/laravel-permission for the full steps and any upgrade guidance.
Can I use laravel-permission for team or multi-tenant roles?
The README does not list team support as a built-in feature. It points to laratrust, which implements team support, so consider that package if you need per-team roles.
How does laravel-permission compare to Bouncer or laratrust?
The README lists Bouncer, laratrust, entrust and roles as alternatives. It describes Bouncer as an excellent package and notes that entrust offers wildcard pattern matching and laratrust implements team support. Compare features against your needs before choosing.
Do I check permissions differently from normal Laravel code?
No. Permissions are registered on Laravel's gate, so you use the standard $user->can('edit articles') check.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
laravel-permission suits Laravel developers who need database-backed roles and permissions, such as admin panels with different access levels. If your project is not Laravel, needs per-team or multi-tenant roles, or you have no developer to write the setup, pick another option such as laratrust or Bouncer.
Install options & downloads