PHPackages                             hasanhawary/permission-manager - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Authentication & Authorization](/categories/authentication)
4. /
5. hasanhawary/permission-manager

ActiveLibrary[Authentication & Authorization](/categories/authentication)

hasanhawary/permission-manager
==============================

A simple permission and role management service extracted from the app for reuse.

1.4.4(1w ago)1394MITPHPPHP >=8.1 <8.6CI passing

Since Sep 21Pushed 3w agoCompare

[ Source](https://github.com/hasanhawary/permission-manager)[ Packagist](https://packagist.org/packages/hasanhawary/permission-manager)[ Docs](https://github.com/hasanhawary/permission-manager)[ RSS](/packages/hasanhawary-permission-manager/feed)WikiDiscussions main Synced 2d ago

READMEChangelogDependencies (10)Versions (12)Used By (0)

Permission Manager
==================

[](#permission-manager)

[![Latest Stable Version](https://camo.githubusercontent.com/7e01ae019a966cf1da2159ad5a0b455b906bd91cad57957dabba6d1df8c9416f/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f686173616e6861776172792f7065726d697373696f6e2d6d616e616765722e737667)](https://packagist.org/packages/hasanhawary/permission-manager)[![Total Downloads](https://camo.githubusercontent.com/ba046d6cbca7534788e3f93b29d37abc8157e72d02a42d562ffc3b43df5849fa/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f646d2f686173616e6861776172792f7065726d697373696f6e2d6d616e616765722e737667)](https://packagist.org/packages/hasanhawary/permission-manager)[![PHP Version](https://camo.githubusercontent.com/baf8d2aae03c05b30efa66d6d9d5d0e6ea16c53bd03e2fb8a25c3b446d97a72d/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f686173616e6861776172792f7065726d697373696f6e2d6d616e616765722e737667)](https://packagist.org/packages/hasanhawary/permission-manager)[![License](https://camo.githubusercontent.com/7013272bd27ece47364536a221edb554cd69683b68a46fc0ee96881174c4214c/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d626c75652e737667)](LICENSE)

A simple but powerful **role and permission manager** for Laravel, built on top of [spatie/laravel-permission](https://github.com/spatie/laravel-permission).

The package is self-contained: it ships its own Role and Permission models, migrations, config, command, facade, helpers, and service bindings. Host projects may override the models/config, but no `App\...` classes are required by default.

---

✨ Features
----------

[](#-features)

- **One-line setup:** `Access::handle()` builds roles & permissions automatically.
- Ships with **default roles** (`root`, `admin`).
- Auto-discovers your **models** from `app/Models` and **nested directories** automatically.
- **Config-driven roles**: inheritance (`like`), add/remove (`added`, `exception`), and custom permission sets.
- **Additional operations** for global actions not tied to models.
- **Translation-ready**: multilingual `display_name` for roles & permissions (e.g., English & Arabic).
- **Multiple guard support**: configure default guard and per-model guard overrides.
- **Package-owned models** for roles and permissions, with optional custom model overrides.
- **Package-owned migrations** for Spatie tables plus `display_name`, `group`, and `is_active` metadata.
- Works with **Laravel Modules** as well as `app/Models`.

---

📦 Installation
--------------

[](#-installation)

```
composer require hasanhawary/permission-manager
```

The service provider is auto-discovered.

Run migrations after installing. The package loads idempotent migrations for the Spatie permission tables plus package metadata columns:

```
php artisan migrate
```

Optionally publish the config:

```
php artisan vendor:publish --tag=permission-manager-config
```

Optionally publish migrations if you want to edit them before running:

```
php artisan vendor:publish --tag=permission-manager-migrations
```

If your app already owns equivalent Spatie/permission-manager migrations, disable automatic package migration loading:

```
'migrations' => [
    'load' => false,
],
```

---

⚡ Quick Start: Build Everything
-------------------------------

[](#-quick-start-build-everything)

Use the **facade** for the simplest bootstrap:

```
use HasanHawary\PermissionManager\Facades\Access;

// Full rebuild: reset tables, then regenerate roles and permissions
Access::handle();

// Regenerate without truncating existing tables
Access::handle(skipReset: true);
```

Or run the artisan command:

```
php artisan permissions:reset
php artisan permissions:reset --skip
```

The command delegates to `Access::handle()`.

---

🗂 Model-level Permissions
-------------------------

[](#-model-level-permissions)

Define permissions **directly in your models**:

```
class Report
{
    public bool $inPermission = true;

    // Override CRUD (defaults: create/read/update/delete)
    public array $basicOperations = ['read', 'update'];

    // Add custom operations
    public array $specialOperations = ['export'];

    // Optional: Set specific guard for this model's permissions
    // This overrides the default_guard from config
    protected string $guard_name = 'api';
}
```

Generated permissions:

```
read-report
update-report
export-report

```

The package automatically discovers models in `app/Models` and all **nested subdirectories**. Laravel Modules are also supported by default.

---

⚙️ Config Example (`config/roles.php`)
--------------------------------------

[](#️-config-example-configrolesphp)

```
// Package-owned model paths. Override only if your app has custom Spatie models.
'class_paths' => [
    'role' => \HasanHawary\PermissionManager\Models\Role::class,
    'permission' => \HasanHawary\PermissionManager\Models\Permission::class,
],

// Default guard for permissions (default: 'sanctum')
'default_guard' => 'sanctum',

'roles' => [
    'manager' => [
        'like' => 'admin',      // inherit from admin
        'type' => 'exception',  // remove selected permissions
        'permissions' => [
            'Project' => ['delete'], // manager cannot delete projects
        ],
    ],
    'auditor' => [
        'permissions' => [
            'Report' => ['read', 'export'],
        ],
    ],
],

'additional_operations' => [
    [
        'name' => 'ReportBuilder',
        'operations' => ['main'], // generates "main-report-builder"
        'basic' => true           // also add CRUD ops
    ]
],

'default' => [
    'permissions' => ['dashboard-access'],
],
```

### Configuration Options

[](#configuration-options)

#### `class_paths`

[](#class_paths)

Override the default Role and Permission model classes. This is useful if you have custom implementations or use different namespaces:

```
'class_paths' => [
    'role' => \HasanHawary\PermissionManager\Models\Role::class,
    'permission' => \HasanHawary\PermissionManager\Models\Permission::class,
],
```

The service provider also aligns Spatie's `permission.models.role` and `permission.models.permission` with these package defaults unless the host project already customized Spatie's model config.

#### `default_guard`

[](#default_guard)

Set the default authentication guard for permissions. This guard will be used when checking user permissions and roles:

```
'default_guard' => 'sanctum', // or 'web', 'api', etc.
```

#### Per-Model Guard Override

[](#per-model-guard-override)

You can override the default guard for specific models using the `$guard_name` property in your model:

```
class ApiResource
{
    public bool $inPermission = true;
    protected string $guard_name = 'api'; // Use 'api' guard instead of default
}
```

#### Discovery Paths

[](#discovery-paths)

Model discovery defaults to Laravel apps and Laravel Modules, but paths and namespaces are configurable:

```
'discovery' => [
    'models_path' => 'app/Models',
    'models_namespace' => 'App\\Models',
    'modules_path' => 'Modules',
    'modules_models_path' => 'App/Models',
    'modules_namespace' => 'Modules',
],
```

Set these to empty values to disable filesystem discovery and rely only on configured `additional_operations` / explicit role permissions.

#### Role Permission Rules

[](#role-permission-rules)

Role entries support direct permissions, inherited permissions, model-generated permissions, and merge modes:

```
'roles' => [
    'auditor' => [
        'permissions' => [
            'Report' => ['read', 'export'],
        ],
    ],

    'manager' => [
        'like' => 'admin',
        'type' => 'exception',
        'permissions' => [
            'Project' => ['delete'],
        ],
    ],

    'operator' => [
        'models' => ['Report'],
        'type' => 'added',
        'permissions' => [
            'Dashboard' => ['read'],
        ],
    ],
],
```

Supported operation shortcuts:

```
'permissions' => [
    'Report' => ['basic'], // create/read/update/delete
    'User' => ['*'],       // all operations resolved for User
],
```

---

🌍 Translations
--------------

[](#-translations)

This makes it easy to show localized names in dashboards, logs, or admin panels.

Example language file `lang/ar/roles.php`:

```