Skip to main content

​
System Requirements

Before installing Laravel Permission, ensure your system meets the following requirements:

​
PHP Version

Minimum Required: PHP 8.4 or higher
Laravel Permission requires PHP 8.4 or later. You can check your PHP version by running: 
php --version
If you need to upgrade PHP, consult your hosting provider’s documentation or use a version manager like phpenv or Laravel Valet.

​
Laravel Version

Supported Versions: Laravel 12.x and 13.x
This package is designed for Laravel 12.0 or higher. Check your Laravel version: 
php artisan --version
Using an older version of Laravel? Check the compatibility table below for the appropriate package version.

​
Required Dependencies

Laravel Permission depends on several Laravel components that are typically included in a standard Laravel installation:

illuminate/auth

Laravel’s authentication system for managing guards and user authentication

illuminate/database

Laravel’s database layer for Eloquent models and migrations

illuminate/container

Laravel’s service container for dependency injection

illuminate/contracts

Laravel’s contract interfaces
These dependencies are automatically installed when you require the package via Composer.

​
Database Requirements

Laravel Permission supports the following database systems:
  • MySQL 5.7+
  • PostgreSQL 10.0+
  • SQLite 3.8.8+
  • SQL Server 2017+
  • MariaDB 10.2+
The package uses standard Laravel migrations, so it works with any database system supported by Laravel.

​
Database Configuration

Ensure your .env file has the correct database configuration:
.env
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=your_database
DB_USERNAME=your_username
DB_PASSWORD=your_password
Test your database connection: 
php artisan db:show

​
Authentication Setup

Laravel Permission requires an authentication system to be set up in your application.
You need a User model with authentication configured. If you haven’t set this up yet: 
composer require laravel/breeze --dev
php artisan breeze:install
php artisan migrate
npm install && npm run dev

​
Laravel Jetstream

composer require laravel/jetstream
php artisan jetstream:install livewire
php artisan migrate
npm install && npm run dev

​
Manual Setup

If you prefer a manual setup, ensure you have:
  • A users table in your database
  • A User model in app/Models/User.php
  • Authentication guards configured in config/auth.php

​
Version Compatibility

Different versions of Laravel Permission support different versions of Laravel and PHP:
Laravel PermissionLaravelPHP
7.x12.x - 13.x8.4+
6.x11.x8.2+
5.x9.x - 10.x8.0+
4.x8.x7.3+
3.x7.x7.2+
Always use the latest compatible version for the best features and security updates.

​
Installing a Specific Version

To install a specific version for your Laravel installation: 
composer require spatie/laravel-permission

​
Development Environment

For the best development experience, we recommend:

​
Local Development Tools

Laravel Herd

The fastest way to run Laravel on macOS

Laravel Valet

Lightweight development environment for macOS

Laravel Sail

Docker-powered development environment

Homestead

Pre-packaged Vagrant development environment
  • Composer 2.x - PHP dependency manager
  • Git - Version control
  • IDE/Editor - PhpStorm, VS Code, or Sublime Text with PHP extensions

​
Optional Dependencies

​
Laravel Passport (for API Authentication)

If you’re using Laravel Passport for API authentication: 
composer require laravel/passport
Enable Passport client credentials in the config:
config/permission.php
'use_passport_client_credentials' => true,

​
Laravel Octane (for High Performance)

If you’re using Laravel Octane, enable the reset listener:
config/permission.php
'register_octane_reset_listener' => true,

​
Composer Configuration

Ensure your composer.json has the correct minimum stability:
composer.json
{
    "minimum-stability": "dev",
    "prefer-stable": true
}
This ensures you get stable releases while allowing dev dependencies.

​
Checking Your Environment

Here’s a quick checklist to verify your environment is ready:
1

Check PHP Version

php --version
Should show PHP 8.4.0 or higher.
2

Check Laravel Version

php artisan --version
Should show Laravel Framework 12.x.x or 13.x.x.
3

Check Database Connection

php artisan db:show
Should display your database information without errors.
4

Check Composer

composer --version
Should show Composer 2.x.x.
5

Verify Authentication

php artisan route:list --path=login
Should show authentication routes if auth is set up.

​
Common Issues

Error: requires php ^8.4Solution: Upgrade your PHP version to 8.4 or higher. On Ubuntu/Debian:
sudo add-apt-repository ppa:ondrej/php
sudo apt update
sudo apt install php8.4
Error: laravel/framework[v11.x] require spatie/laravel-permission ^6.0Solution: Install the correct package version for your Laravel version:
composer require spatie/laravel-permission:^6.0
Error: User model not found or authentication not configuredSolution: Install Laravel Breeze or set up authentication:
composer require laravel/breeze --dev
php artisan breeze:install
Error: Database connection errors during installationSolution: Verify your .env database credentials and ensure the database exists:
mysql -u root -p
CREATE DATABASE your_database;

​
Next Steps

Once you’ve verified all prerequisites are met:

Installation

Install Laravel Permission in your application

Basic Concepts

Learn about roles and permissions

Build docs developers (and LLMs) love

Get started for freeTalk to us