# spatie/laravel-permission architecture

> Architecture diagram of the GitHub repository spatie/laravel-permission, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-01-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/spatie/laravel-permission
- Repository: https://github.com/spatie/laravel-permission

## Overview

##### Main Components

a. Core Components:
- Permission Manager (PermissionRegistrar)
- Models Layer (Role and Permission models)
- Cache Layer
- Database Layer
- Middleware Layer
- Service Provider

b. Integration Points:
- Laravel Gate Integration
- Laravel Auth System
- Cache Driver
- Database Connection

**┌─ Application Layer ─────────────────────────────┐**

- ┌─ Auth Layer ──┐    ┌─ Gate/Policy Layer ─┐  │
- User Model    │←───│ Permission Checks    │  │
- ┘    └───────────────────────┘ │
- ↑                      ↑              │

- ┌─ Permission Package Core ──────────────────┐ │

- ┌─ Service Provider ─┐                   │ │
- PermissionProvider │                   │ │
- ┘                    │ │
- ↓                              │ │
- ┌─ Permission Registrar ─┐              │ │
- Cache Management     │              │ │
- Permission Registry  │              │ │
- ┘              │ │
- ↓                              │ │
- ┌─ Models ─────┐    ┌─ Middleware ───┐  │ │
- Role         │    │ Permission     │  │ │
- Permission   │    │ Role          │  │ │
- ┘    └──────────────┘  │ │
- ↓                              │ │
- ┌─ Traits ──────┐                      │ │
- HasRoles      │                      │ │
- HasPermissions│                      │ │
- ┘                      │ │
- ┘ │
- ↓                      │
- ┌─ Storage Layer ────────────────────────┐ │
- Database Tables   Cache Storage        │ │
- ┘ │
- ┘

##### Important Relationships to Highlight

- Bidirectional relationship between User model and Role/Permission models
- Cache interaction flow
- Middleware integration points
- Database table relationships

##### Key Technical Details

- Cache implementation for permission checks
- Database tables (roles, permissions, role_has_permissions, model_has_roles, model_has_permissions)
- Middleware registration flow
- Service provider bootstrap process

##### Implementation Notes

- Use clear, consistent symbols for different types of components
- Notes for important configuration options
- Version compatibility information

- The package's integration with Laravel's core systems
- The caching mechanism for performance optimization
- The flexibility of the permission/role assignment system
- The various ways to check permissions (Gate, middleware, direct methods)

Remember to maintain a balance between detail and clarity, focusing on the architectural decisions that make this package efficient and flexible.

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph Application
        subgraph AuthLayer
            User[User Model]
        end

        subgraph GateLayer
            Gate[Gate/Policy Checks]
        end

        subgraph PackageCore[Permission Package Core]
            Provider[Permission Service Provider]:::core
            click Provider "https://github.com/spatie/laravel-permission/blob/main/src/PermissionServiceProvider.php"
            
            PermissionMgr[Permission Registrar]:::core
            click PermissionMgr "https://github.com/spatie/laravel-permission/blob/main/src/PermissionRegistrar.php"
            
            subgraph Models
                RoleModel[Role Model]:::model
                click RoleModel "https://github.com/spatie/laravel-permission/blob/main/src/Models/Role.php"
                PermModel[Permission Model]:::model
                click PermModel "https://github.com/spatie/laravel-permission/blob/main/src/Models/Permission.php"
            end
            
            subgraph Middleware
                PermMiddleware[Permission Middleware]:::middleware
                click PermMiddleware "https://github.com/spatie/laravel-permission/blob/main/src/Middleware/PermissionMiddleware.php"
                RoleMiddleware[Role Middleware]:::middleware
                click RoleMiddleware "https://github.com/spatie/laravel-permission/blob/main/src/Middleware/RoleMiddleware.php"
                RolePermMiddleware[Role or Permission Middleware]:::middleware
                click RolePermMiddleware "https://github.com/spatie/laravel-permission/blob/main/src/Middleware/RoleOrPermissionMiddleware.php"
            end
            
            subgraph Traits
                HasRoles[HasRoles Trait]:::trait
                click HasRoles "https://github.com/spatie/laravel-permission/blob/main/src/Traits/HasRoles.php"
                HasPerms[HasPermissions Trait]:::trait
                click HasPerms "https://github.com/spatie/laravel-permission/blob/main/src/Traits/HasPermissions.php"
                RefreshCache[Refreshes Permission Cache]:::trait
                click RefreshCache "https://github.com/spatie/laravel-permission/blob/main/src/Traits/RefreshesPermissionCache.php"
            end
            
            subgraph Commands
                CreatePerm[Create Permission]:::command
                click CreatePerm "https://github.com/spatie/laravel-permission/blob/main/src/Commands/CreatePermission.php"
                CreateRole[Create Role]:::command
                click CreateRole "https://github.com/spatie/laravel-permission/blob/main/src/Commands/CreateRole.php"
                ShowCmd[Show Command]:::command
                click ShowCmd "https://github.com/spatie/laravel-permission/blob/main/src/Commands/Show.php"
                CacheReset[Cache Reset]:::command
                click CacheReset "https://github.com/spatie/laravel-permission/blob/main/src/Commands/CacheReset.php"
            end
            
            WildcardPerms[Wildcard Permissions]:::core
            click WildcardPerms "https://github.com/spatie/laravel-permission/blob/main/src/WildcardPermission.php"
            
            subgraph Contracts
                PermContract[Permission Contract]:::contract
                click PermContract "https://github.com/spatie/laravel-permission/blob/main/src/Contracts/Permission.php"
                RoleContract[Role Contract]:::contract
                click RoleContract "https://github.com/spatie/laravel-permission/blob/main/src/Contracts/Role.php"
                WildContract[Wildcard Contract]:::contract
                click WildContract "https://github.com/spatie/laravel-permission/blob/main/src/Contracts/Wildcard.php"
            end
        end

        subgraph Storage
            DB[(Database)]:::storage
            click DB "https://github.com/spatie/laravel-permission/blob/main/database/migrations/create_permission_tables.php.stub"
            Cache[(Cache Storage)]:::storage
            Teams[(Teams Support)]:::storage
            click Teams "https://github.com/spatie/laravel-permission/blob/main/database/migrations/add_teams_fields.php.stub"
        end

        Config[Configuration]:::config
        click Config "https://github.com/spatie/laravel-permission/blob/main/config/permission.php"
    end

    %% Relationships
    User --> Gate
    Gate --> PermissionMgr
    Provider --> PermissionMgr
    PermissionMgr --> Models
    PermissionMgr --> Cache
    Models --> DB
    Models --> Teams
    Middleware --> PermissionMgr
    Traits --> Models
    Commands --> PermissionMgr
    WildcardPerms --> PermissionMgr
    Contracts --> Models

    %% Styling
    classDef core fill:#2196F3,stroke:#1565C0,color:white
    classDef model fill:#4CAF50,stroke:#388E3C,color:white
    classDef middleware fill:#FF9800,stroke:#F57C00,color:white
    classDef trait fill:#9C27B0,stroke:#7B1FA2,color:white
    classDef command fill:#795548,stroke:#5D4037,color:white
    classDef contract fill:#607D8B,stroke:#455A64,color:white
    classDef storage fill:#FFC107,stroke:#FFA000,color:black
    classDef config fill:#9E9E9E,stroke:#616161,color:white
```
