Spatie Laravel Permission

The spatie/laravel-permission package allows you to manage user permissions and roles within a database. It integrates directly with Laravel's built-in authorization system (Gates), meaning once permissions are assigned, you can use Laravel's standard can method to check for authorization.

// Adding permissions to a user
$user->givePermissionTo('edit articles');

// Adding permissions via a role
$user->assignRole('writer');

// Adding permissions to a role
$role->givePermissionTo('edit articles');

// Checking permissions using Laravel's default gate
$user->can('edit articles');

To allow a specific role (e.g., Super-Admin) to bypass all permission checks, use a Gate::before check in your AuthServiceProvider (or AppServiceProvider in Laravel 11). This ensures that any call to can() or @can returns true for users with this role.

use Illuminate\Support\Facades\Gate;

public function boot()
{
    // Implicitly grant "Super-Admin" role all permission checks using can()
    Gate::before(function ($user, $ability) {
        if ($user->hasRole('Super-Admin')) {
            return true;
        }
    });
}

The package follows a specific authorization hierarchy:

• Hierarchy: Users have Roles, Roles have Permissions, and Applications check Permissions (not Roles).
• Best Practice: Avoid assigning permissions directly to users; instead, assign permissions to roles and assign those roles to users.
• Authorization: Use $user->can('permission-name') for all authorization checks. This method is preferred because it integrates with Laravel's Gate and supports 'Super Admin' logic.
• Trait: The HasRoles trait is the primary entry point for user-based authorization.

The package uses two primary abstractions to manage authorization:

• Permission: A specific ability or capability within your application (e.g., edit articles).
• Role: A named group of permissions that can be assigned to users or other models (e.g., writer).

Permissions can be assigned directly to users, or users can be assigned roles which in turn contain permissions.

Because of Eloquent's polymorphic mapping, child models that inherit from a parent User model may struggle to share the same roles/permissions.

If you want a child model to share the exact same roles and permissions as the parent (effectively treating the child as the parent in the database), you can override the getMorphClass method to return the parent's morph class name (e.g., 'users').

Warning: This makes the child model lose its independence regarding roles and permissions; it will always use the parent's identity for authorization checks.

public function getMorphClass()
{
    return 'users';
}

Teams permissions allow you to scope roles and permissions to specific organizational units (teams).

Core Mechanics

• Global Scope: A role with team_id = null is a global role. It is unique and can be assigned to users across any team.
• Team Scope: A role with a specific team_id is only valid within that team. Multiple teams can have a role named 'editor' as long as their team_ids differ.
• The Active Team ID: The package relies on a global team_id (set via setPermissionsTeamId()) to determine which scope to use for assignments (assignRole(), givePermissionTo()) and checks (hasRole(), can()).
• Relation Management: Because Eloquent caches relations, switching the active team requires manually unsetting the roles and permissions relations on your models to ensure the next access fetches the data for the newly active team.

The package uses foreign-key relationships with cascading deletes to ensure data integrity.

• If your engine supports foreign keys: The database will automatically handle cascading deletes.
• If your engine does NOT support foreign keys: You must manually alter the migration files. However, as long as you manage related records exclusively through the methods provided by this package, the package's internal detaching logic will prevent data integrity issues.

Wildcard permission strings consist of one or more parts separated by dots (.).

Key Rules:

• The meaning of each part is determined by your application (e.g., {resource}.{action}.{target}).
• You can use as many parts as needed; there is no limit to the depth of the hierarchy.
• Crucial: You must explicitly create the permission (e.g., posts.create.*) in the database before you can assign it to a user or check for it.

$permission = 'posts.create.1';

By default, the package integrates with Laravel's authorization system by registering a Gate::before() method call. This allows the package to intercept calls to can() helpers and model policies to determine if a user has the required permission by checking the permissions stored in your database.

This default behavior is controlled by the register_permission_check_method configuration key. If this key is set to true (the default), the package handles permission checks automatically via the database.