{"id":19052419,"url":"https://github.com/amdad121/guard-laravel","last_synced_at":"2026-04-01T23:25:11.807Z","repository":{"id":216545665,"uuid":"741170174","full_name":"amdad121/guard-laravel","owner":"amdad121","description":"A powerful, flexible, and developer-friendly role and permission management system for Laravel applications.","archived":false,"fork":false,"pushed_at":"2026-03-20T05:23:49.000Z","size":113,"stargazers_count":13,"open_issues_count":0,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-03-20T08:42:43.103Z","etag":null,"topics":["acl","authorization","laravel","package","permission","permissions","role","role-based-access-control","roles"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/amdad121.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":"amdad121"}},"created_at":"2024-01-09T20:57:49.000Z","updated_at":"2026-03-20T05:23:53.000Z","dependencies_parsed_at":"2026-02-07T11:04:25.344Z","dependency_job_id":null,"html_url":"https://github.com/amdad121/guard-laravel","commit_stats":null,"previous_names":["amdad121/guard-laravel"],"tags_count":30,"template":false,"template_full_name":null,"purl":"pkg:github/amdad121/guard-laravel","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amdad121%2Fguard-laravel","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amdad121%2Fguard-laravel/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amdad121%2Fguard-laravel/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amdad121%2Fguard-laravel/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/amdad121","download_url":"https://codeload.github.com/amdad121/guard-laravel/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amdad121%2Fguard-laravel/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31292894,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-01T21:15:39.731Z","status":"ssl_error","status_checked_at":"2026-04-01T21:15:34.046Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["acl","authorization","laravel","package","permission","permissions","role","role-based-access-control","roles"],"created_at":"2024-11-08T23:26:22.076Z","updated_at":"2026-04-01T23:25:11.801Z","avatar_url":"https://github.com/amdad121.png","language":"PHP","funding_links":["https://github.com/sponsors/amdad121"],"categories":[],"sub_categories":[],"readme":"# 🛡️ Guard - Modern Role \u0026 Permission Management for Laravel\n\n[![Latest Version on Packagist](https://img.shields.io/packagist/v/amdadulhaq/guard-laravel.svg?style=flat-square)](https://packagist.org/packages/amdadulhaq/guard-laravel)\n[![GitHub Tests Action Status](https://img.shields.io/github/actions/workflow/status/amdad121/guard-laravel/run-tests.yml?branch=main\u0026label=tests\u0026style=flat-square)](https://github.com/amdad121/guard-laravel/actions?query=workflow%3Arun-tests+branch%3Amain)\n[![GitHub Code Style Action Status](https://img.shields.io/github/actions/workflow/status/amdad121/guard-laravel/fix-php-code-style-issues.yml?branch=main\u0026label=code%20style\u0026style=flat-square)](https://github.com/amdad121/guard-laravel/actions?query=workflow%3A\"Fix+PHP+code+style+issues\"+branch%3Amain)\n[![Total Downloads](https://img.shields.io/packagist/dt/amdadulhaq/guard-laravel.svg?style=flat-square)](https://packagist.org/packages/amdadulhaq/guard-laravel)\n[![PHP Version](https://img.shields.io/badge/PHP-8.2%2B-777BB4?style=flat-square\u0026logo=php)](https://php.net)\n[![Laravel Version](https://img.shields.io/badge/Laravel-10%2F11%2F12%2F13-FF2D20?style=flat-square\u0026logo=laravel)](https://laravel.com)\n\n\u003e A powerful, flexible, and developer-friendly role and permission management system for Laravel applications.\n\n## 🚀 Quick Start\n\nGet up and running in 5 minutes:\n\n\u003e **Upgrading from an older version?** Check the [Upgrade Guide](UPGRADE.md) for detailed migration instructions.\n\n### 1. Install via Composer\n\n```bash\ncomposer require amdadulhaq/guard-laravel\n```\n\n### 2. Publish and run migrations\n\n```bash\nphp artisan vendor:publish --tag=\"guard-migrations\"\nphp artisan migrate\n```\n\n### 3. Setup your User model\n\nChoose one setup:\n\n**Roles only**\n\n```php\n\u003c?php\n\nnamespace App\\Models;\n\nuse AmdadulHaq\\Guard\\Contracts\\Roles as RolesContract;\nuse AmdadulHaq\\Guard\\Concerns\\HasRoles;\nuse Illuminate\\Foundation\\Auth\\User as Authenticatable;\n\nclass User extends Authenticatable implements RolesContract\n{\n    use HasRoles;\n}\n```\n\n**Roles + Permissions**\n\n```php\n\u003c?php\n\nnamespace App\\Models;\n\nuse AmdadulHaq\\Guard\\Contracts\\User as UserContract;\nuse AmdadulHaq\\Guard\\Concerns\\HasRoles;\nuse AmdadulHaq\\Guard\\Concerns\\HasPermissions;\nuse Illuminate\\Foundation\\Auth\\User as Authenticatable;\n\nclass User extends Authenticatable implements UserContract\n{\n    use HasRoles;\n    use HasPermissions;\n}\n```\n\n### 4. Create your first role and permission\n\n```bash\nphp artisan guard:create-role admin Administrator\nphp artisan guard:create-permission users.create \"Create Users\"\n```\n\n### 5. Protect your routes\n\n```php\nRoute::middleware('role:admin')-\u003eget('/admin', [AdminController::class, 'index']);\n```\n\n## ✨ Features\n\n- 🎯 **Modern PHP \u0026 Laravel** - Built for PHP 8.2+ and Laravel 10/11/12/13\n- 🔐 **Flexible Permission System** - Users can have permissions via roles\n- 🎭 **Wildcard Permissions** - Use `posts.*` to match all post-related permissions\n- ⚡ **Smart Caching** - Automatic cache invalidation for optimal performance\n- 🔑 **Laravel Gate Integration** - Native `@can`, `@canany`, `@cannot` support\n- 🛡️ **Middleware Protection** - `role`, `permission`, and `role_or_permission` middleware\n- 🎨 **Blade Directives** - `@role`, `@hasrole`, `@hasanyrole`, `@hasallroles`\n- 📦 **Type-Safe Enums** - IDE-friendly `PermissionType` and `CacheKey` enums\n- 🏰 **Guarded Roles** - Protect critical roles from accidental deletion\n- 📁 **Permission Groups** - Organize permissions by resource\n- 🎨 **Interactive Commands** - Laravel Prompts for creating roles/permissions\n- 🧹 **Clean Architecture** - Separated concerns with traits and contracts\n- 🧪 **Developer Tools** - Pint, Pest, Rector, and Larastan included\n\n## 📑 Table of Contents\n\n- [Installation](#installation)\n- [Upgrade Guide](UPGRADE.md)\n- [Configuration](#configuration)\n- [Usage](#usage)\n    - [User Setup](#user-setup)\n    - [Creating Roles](#creating-roles)\n    - [Creating Permissions](#creating-permissions)\n    - [Wildcard Permissions](#wildcard-permissions)\n    - [Role Management](#role-management)\n    - [Permission Management](#permission-management)\n    - [Checking Access](#checking-access)\n    - [Middleware](#middleware)\n    - [Gate Integration](#gate-integration)\n    - [Blade Directives](#blade-directives)\n    - [Artisan Commands](#artisan-commands)\n    - [Query Scopes](#query-scopes)\n- [Models Reference](#models-reference)\n- [Exceptions](#exceptions)\n- [Caching](#caching)\n- [Database Structure](#database-structure)\n- [Enums](#enums)\n- [Development](#development)\n- [Troubleshooting](#troubleshooting)\n- [FAQ](#faq)\n\n## 📦 Installation\n\n### Requirements\n\n- **PHP**: 8.2, 8.3, 8.4, or 8.5\n- **Laravel**: 10.x, 11.x, 12.x, or 13.x\n- **Database**: MySQL 5.7+, PostgreSQL 9.6+, SQLite 3.8+, or SQL Server 2017+\n\n### Step 1: Install via Composer\n\n```bash\ncomposer require amdadulhaq/guard-laravel\n```\n\n### Step 2: Publish Migrations\n\n```bash\nphp artisan vendor:publish --tag=\"guard-migrations\"\nphp artisan migrate\n```\n\nThis creates 4 tables:\n\n- `roles` - Role definitions\n- `permissions` - Permission definitions\n- `permission_role` - Role-permission relationships\n- `role_user` - User-role relationships\nPivot table names are derived from model table names; the defaults shown above are used unless you customize model tables.\n\n### Step 3: Configure User Model\n\nYou can use the package in two ways.\n\n**Roles only**\n\n```php\n\u003c?php\n\nnamespace App\\Models;\n\nuse AmdadulHaq\\Guard\\Contracts\\Roles as RolesContract;\nuse AmdadulHaq\\Guard\\Concerns\\HasRoles;\nuse Illuminate\\Foundation\\Auth\\User as Authenticatable;\n\nclass User extends Authenticatable implements RolesContract\n{\n    use HasRoles;\n}\n```\n\n**Roles + Permissions**\n\n```php\n\u003c?php\n\nnamespace App\\Models;\n\nuse AmdadulHaq\\Guard\\Contracts\\User as UserContract;\nuse AmdadulHaq\\Guard\\Concerns\\HasRoles;\nuse AmdadulHaq\\Guard\\Concerns\\HasPermissions;\nuse Illuminate\\Foundation\\Auth\\User as Authenticatable;\n\nclass User extends Authenticatable implements UserContract\n{\n    use HasRoles;\n    use HasPermissions;\n}\n```\n\n### Step 4: (Optional) Publish Config\n\n```bash\nphp artisan vendor:publish --tag=\"guard-config\"\n```\n\n## ⚙️ Configuration\n\nThe `config/guard.php` file:\n\n```php\nreturn [\n    'models' =\u003e [\n        'user' =\u003e \\App\\Models\\User::class,\n        'role' =\u003e \\AmdadulHaq\\Guard\\Models\\Role::class,\n        'permission' =\u003e \\AmdadulHaq\\Guard\\Models\\Permission::class,\n    ],\n    'tables' =\u003e [\n        'roles' =\u003e 'roles',\n        'permissions' =\u003e 'permissions',\n    ],\n    'cache' =\u003e [\n        'enabled' =\u003e env('GUARD_CACHE_ENABLED', true),\n        'roles_duration' =\u003e (int) env('GUARD_ROLES_CACHE_DURATION', 3600),\n        'permissions_duration' =\u003e (int) env('GUARD_PERMISSIONS_CACHE_DURATION', 3600),\n    ],\n    'middleware' =\u003e [\n        'role' =\u003e 'role',\n        'permission' =\u003e 'permission',\n        'role_or_permission' =\u003e 'role_or_permission',\n    ],\n    'wildcard' =\u003e [\n        'enabled' =\u003e env('GUARD_WILDCARD_ENABLED', true),\n    ],\n];\n```\n\n## 🎯 Usage\n\n### User Setup\n\nUse one of these setups depending on what your app needs.\n\n**Roles only**\n\n```php\nuse AmdadulHaq\\Guard\\Contracts\\Roles as RolesContract;\nuse AmdadulHaq\\Guard\\Concerns\\HasRoles;\n\nclass User extends Authenticatable implements RolesContract\n{\n    use HasRoles;\n}\n```\n\n**Roles + Permissions**\n\n```php\nuse AmdadulHaq\\Guard\\Contracts\\User as UserContract;\nuse AmdadulHaq\\Guard\\Concerns\\HasRoles;\nuse AmdadulHaq\\Guard\\Concerns\\HasPermissions;\n\nclass User extends Authenticatable implements UserContract\n{\n    use HasRoles;\n    use HasPermissions;\n}\n```\n\nNotes:\n\n- `HasPermissions` on the user model is for permission checks.\n- Users do not receive permissions directly.\n- Assign permissions to roles, then users inherit them from those roles.\n\n### Creating Roles\n\n```php\nuse AmdadulHaq\\Guard\\Models\\Role;\n\n// Create a role\n$adminRole = Role::create([\n    'name' =\u003e 'administrator',\n    'label' =\u003e 'Administrator',\n    'description' =\u003e 'Full system access',\n    'is_guarded' =\u003e true, // Protected from deletion\n]);\n\n// Create via command\n// php artisan guard:create-role moderator \"Moderator\"\n// php artisan guard:create-role moderator \"Moderator\" 1\n// php artisan guard:create-role moderator \"Moderator\" user@example.com\n// php artisan guard:create-role moderator \"Moderator\" \"Jane Doe\"\n```\n\n**Role Model Methods:**\n\n```php\n$role-\u003egetName();              // Get role name\n$role-\u003eisProtectedRole();      // Check if guarded\n$role-\u003egetPermissionNames();   // Get all permission names\n$role-\u003eusers;                  // Get users with this role\n\n// Query scopes\nRole::guarded()-\u003eget();        // Only guarded roles\nRole::unguarded()-\u003eget();      // Only unguarded roles\n```\n\n### Creating Permissions\n\n```php\nuse AmdadulHaq\\Guard\\Models\\Permission;\n\n// Simple permission\nPermission::create([\n    'name' =\u003e 'users.create',\n    'label' =\u003e 'Create Users',\n    'description' =\u003e 'Can create new users',\n    'group' =\u003e 'users', // For organization\n]);\n\n// Wildcard permission (auto-sets is_wildcard = true)\nPermission::create([\n    'name' =\u003e 'posts.*',\n    'label' =\u003e 'Manage All Posts',\n    'group' =\u003e 'posts',\n]);\n\n// Create via command\n// php artisan guard:create-permission users.delete \"Delete Users\"\n// php artisan guard:create-permission users.delete \"Delete Users\" 1\n// php artisan guard:create-permission users.delete \"Delete Users\" admin\n```\n\n**Permission Model Methods:**\n\n```php\n$permission-\u003egetName();          // Get permission name\n$permission-\u003egetLabel();         // Get human-readable label\n$permission-\u003egetDescription();   // Get description\n$permission-\u003eisWildcard();       // Check if wildcard (e.g., posts.*)\n$permission-\u003egetGroup();         // Get group (e.g., 'users' from 'users.create')\n$permission-\u003egetType();          // Get PermissionType enum (e.g., PermissionType::CREATE)\n$permission-\u003eroles;              // Get roles with this permission\n\n// Query scopes\nPermission::wildcard()-\u003eget();           // Only wildcard permissions\nPermission::byGroup('users')-\u003eget();     // Permissions in users group\n```\n\n### Wildcard Permissions\n\nWildcard permissions automatically match all sub-permissions:\n\n```php\n// Create wildcard permission\nPermission::create(['name' =\u003e 'posts.*']);\n\n// Assign to role\n$role-\u003egivePermissionTo('posts.*');\n\n// Now user can do all of these:\n$user-\u003ehasPermission('posts.create');  // true\n$user-\u003ehasPermission('posts.update');  // true\n$user-\u003ehasPermission('posts.delete');  // true\n$user-\u003ehasPermission('posts.publish'); // true\n```\n\nThe `is_wildcard` boolean is automatically set when the name ends with `*`.\n\n### Role Management\n\n**Assigning Roles:**\n\n```php\n// Single role\n$user-\u003eassignRole('administrator'); // by role name\n$user-\u003eassignRole($roleModel); // by role model\n\n// Multiple roles in one call\n$user-\u003eassignRole('administrator', 'editor');\n$user-\u003eassignRole([$roleModel, $roleId, 'moderator']);\n\n// Sync (replaces all)\n$user-\u003esyncRoles(['administrator', 'editor']);\n$user-\u003esyncRoles([$role1-\u003eid, $role2-\u003eid]);\n\n// Sync without detaching existing\n$user-\u003esyncRolesWithoutDetaching(['moderator']);\n\n// Revoke\n$user-\u003erevokeRole('editor');\n$user-\u003erevokeRole($roleModel);\n$user-\u003erevokeRoles(); // Revoke all\n```\n\n**Checking Roles:**\n\n```php\n// Single role\n$user-\u003ehasRole('administrator');              // true/false\n\n// Multiple roles\n$user-\u003ehasAllRoles(['admin', 'editor']);     // Must have ALL\n$user-\u003ehasAnyRole(['admin', 'moderator']);   // Must have ANY\n\n// Get role names\n$user-\u003egetRoleNames(); // ['administrator', 'editor']\n```\n\n### Permission Management\n\n**Assigning to Roles:**\n\n```php\n// Single permission\n$role-\u003egivePermissionTo('users.create'); // by permission name\n$role-\u003egivePermissionTo($permissionModel); // by permission model\n\n// Multiple permissions in one call\n$role-\u003egivePermissionTo('users.create', 'users.edit');\n$role-\u003egivePermissionTo([$permissionModel, $permissionId, 'users.delete']);\n\n// Sync (replaces all)\n$role-\u003esyncPermissions(['users.create', 'users.edit']);\n$role-\u003esyncPermissions([$perm1-\u003eid, $perm2-\u003eid]);\n\n// Revoke\n$role-\u003erevokePermissionTo('users.delete');\n$role-\u003erevokePermissionTo($permissionModel);\n$role-\u003erevokeAllPermissions();\n```\n\n**Checking Role Permissions:**\n\n```php\n$role-\u003ehasPermissionTo('users.edit');    // Check if role has permission\n$role-\u003egetPermissionNames();             // Get all permission names\n```\n\n**Checking User Permissions:**\n\n```php\n// Check by name\n$user-\u003ehasPermission('users.create');\n\n// Check by model\n$user-\u003ehasPermission($permissionModel);\n\n// Wildcard matching\n$user-\u003ehasPermission('posts.*');\n\n// Get all permissions inherited from roles\n$user-\u003egetPermissions();\n\n// Get permission names array\n$user-\u003egetPermissionNames(); // ['users.create', 'users.edit']\n```\n\n### Checking Access\n\n**Role Checking:**\n\n```php\nif ($user-\u003ehasRole('administrator')) {\n    // User has administrator role\n}\n\nif ($user-\u003ehasAllRoles(['admin', 'editor'])) {\n    // User has both roles\n}\n\nif ($user-\u003ehasAnyRole(['admin', 'moderator'])) {\n    // User has at least one role\n}\n\n// Get all role names\n$user-\u003egetRoleNames(); // ['administrator', 'editor']\n```\n\n**Permission Checking:**\n\n```php\nif ($user-\u003ehasPermission('users.create')) {\n    // User can create users\n}\n\nif ($user-\u003ehasPermission('posts.*')) {\n    // User has wildcard permission for posts\n}\n```\n\n### Middleware\n\nAll middleware supports multiple values (requires ANY):\n\n```php\n// Role middleware\nRoute::middleware('role:administrator')-\u003eget('/admin', [AdminController::class, 'index']);\n\n// Multiple roles (requires ANY)\nRoute::middleware('role:admin,editor')-\u003egroup(function () {\n    Route::get('/dashboard', [DashboardController::class, 'index']);\n});\n\n// Permission middleware\nRoute::middleware('permission:users.create')-\u003epost('/users', [UserController::class, 'store']);\n\n// Multiple permissions (requires ANY)\nRoute::middleware('permission:users.create,users.edit')-\u003eput('/users/{id}', [UserController::class, 'update']);\n\n// Role OR permission middleware\nRoute::middleware('role_or_permission:admin,users.create')-\u003eget('/users', [UserController::class, 'index']);\n\n// Multiple role_or_permission\nRoute::middleware('role_or_permission:admin,editor,posts.manage')-\u003egroup(function () {\n    Route::post('/manage', [Controller::class, 'handle']);\n});\n```\n\n### Gate Integration\n\nThe package automatically registers Gates for all permissions and roles:\n\n```php\n// In controllers\npublic function store(Request $request)\n{\n    $this-\u003eauthorize('users.create');\n    // User can create users\n}\n\n// Using Gate facade\nuse Illuminate\\Support\\Facades\\Gate;\n\nif (Gate::allows('users.create')) {\n    // Allowed\n}\n\nif (Gate::denies('users.delete')) {\n    abort(403, 'Permission denied');\n}\n\n// Check for specific user\nif (Gate::forUser($otherUser)-\u003eallows('posts.edit')) {\n    // That user can edit posts\n}\n\n// Authorize roles\n$this-\u003eauthorize('administrator');\n```\n\n### Blade Directives\n\nGuard provides custom Blade directives for role checking, in addition to Laravel's built-in `@can` directives:\n\n**Custom Role Directives:**\n\n```blade\n@role('administrator')\n    \u003cdiv class=\"admin-panel\"\u003e\n        \u003ch1\u003eAdmin Dashboard\u003c/h1\u003e\n    \u003c/div\u003e\n@endrole\n\n@hasrole('editor')\n    \u003cp\u003eEditor content here\u003c/p\u003e\n@endhasrole\n\n@hasanyrole(['administrator', 'moderator'])\n    \u003cp\u003eContent for admins or moderators\u003c/p\u003e\n@endhasanyrole\n\n@hasallroles(['administrator', 'editor'])\n    \u003cp\u003eOnly for users with BOTH admin AND editor roles\u003c/p\u003e\n@endhasallroles\n```\n\n**Built-in Laravel Directives (via Gate integration):**\n\n```blade\n@can('users.create')\n    \u003ca href=\"/users/create\"\u003eCreate User\u003c/a\u003e\n@endcan\n\n@canany(['users.create', 'users.edit'])\n    \u003cp\u003eYou can manage users\u003c/p\u003e\n@endcanany\n\n@cannot('users.delete')\n    \u003cp\u003eYou cannot delete users\u003c/p\u003e\n@endcannot\n```\n\n### Artisan Commands\n\n**Create a Role:**\n\n```bash\nphp artisan guard:create-role admin Administrator\n\n# With optional user assignment as the third positional argument\nphp artisan guard:create-role moderator Moderator 1\n```\n\n**Create a Permission:**\n\n```bash\nphp artisan guard:create-permission users.create \"Create Users\"\n\n# With optional role assignment as the third positional argument\nphp artisan guard:create-permission posts.delete \"Delete Posts\" 1\n```\n\nBoth commands support Laravel Prompts when optional assignment arguments are omitted.\n\n- `guard:create-role` prompts for an optional user identifier and accepts a user ID, email, or name.\n- `guard:create-permission` prompts for an optional role identifier and accepts a role ID or role name.\n\n### Query Scopes\n\n```php\n// Users with a specific role\nUser::query()-\u003ewithRoles('administrator')-\u003eget();\n\n// Users with a specific permission inherited through roles\nUser::query()-\u003ewithPermissions('users.create')-\u003eget();\n\n// Role scopes\nRole::query()-\u003eguarded()-\u003eget();\nRole::query()-\u003eunguarded()-\u003eget();\n\n// Permission scopes\nPermission::query()-\u003ewildcard()-\u003eget();\nPermission::query()-\u003ebyGroup('users')-\u003eget();\n```\n\n## 📚 Models Reference\n\n### User Model (via Traits)\n\n**HasRoles trait provides:**\n\n- `roles()` - BelongsToMany relationship\n- `assignRole(...$roles)` - Assign one or more roles\n- `syncRoles(array $roles, bool $detach = true)` - Sync roles\n- `syncRolesWithoutDetaching(array $roles)` - Sync without detaching\n- `revokeRole($role)` - Revoke specific role\n- `revokeRoles()` - Revoke all roles\n- `getRoleNames()` - Get all role names\n- `hasRole($role)` - Check single role\n- `hasAllRoles(...$roles)` - Check all roles\n- `hasAnyRole(...$roles)` - Check any role\n\n**HasPermissions trait provides:**\n\n- `getPermissionNames()` - Get permission names inherited from roles\n- `hasPermission($permission)` - Check permission (by name or model)\n- `getPermissions()` - Get all permissions inherited from roles\n\n### Role Model\n\n**Properties:**\n\n- `name` (string, unique)\n- `label` (string, nullable)\n- `description` (text, nullable)\n- `is_guarded` (boolean)\n\n**Methods:**\n\n- `getName()` - Get role name\n- `isProtectedRole()` - Check if guarded\n- `getPermissionNames()` - Get assigned permission names\n- `permissions()` - BelongsToMany to permissions\n- `users()` - BelongsToMany to users\n\n**Scopes:**\n\n- `guarded()` - Only guarded roles\n- `unguarded()` - Only unguarded roles\n\n### Permission Model\n\n**Properties:**\n\n- `name` (string, unique)\n- `label` (string, nullable)\n- `description` (text, nullable)\n- `group` (string, nullable, indexed)\n- `is_wildcard` (boolean, auto-set)\n\n**Methods:**\n\n- `getName()` - Get permission name\n- `getLabel()` - Get human-readable label\n- `getDescription()` - Get description\n- `isWildcard()` - Check if wildcard pattern\n- `getGroup()` - Get resource group (e.g., 'users')\n- `getType()` - Get PermissionType enum\n- `roles()` - BelongsToMany to roles\n- `giveRoleTo(...$roles)` - Give one or more roles to permission\n- `syncRoles(array $roles)` - Sync roles\n- `revokeRole($role)` - Revoke role\n- `assignRole(...$roles)` - Alias for giveRoleTo\n\n**Scopes:**\n\n- `wildcard()` - Only wildcard permissions\n- `byGroup($group)` - Filter by group\n\n## 🚨 Exceptions\n\n```php\nuse AmdadulHaq\\Guard\\Exceptions\\PermissionDeniedException;\nuse AmdadulHaq\\Guard\\Exceptions\\RoleDoesNotExistException;\nuse AmdadulHaq\\Guard\\Exceptions\\PermissionDoesNotExistException;\n\n// Permission denied\nthrow PermissionDeniedException::create('users.delete');\nthrow PermissionDeniedException::roleNotAssigned('administrator');\n\n// Role not found\nthrow RoleDoesNotExistException::named('admin');\nthrow RoleDoesNotExistException::withId(123);\n\n// Permission not found\nthrow PermissionDoesNotExistException::named('users.delete');\nthrow PermissionDoesNotExistException::withId(456);\n```\n\n## 💾 Caching\n\nThe package uses intelligent caching:\n\n```php\nuse AmdadulHaq\\Guard\\Facades\\Guard;\n\n// Clear cache manually\nGuard::clearCache();\n```\n\n**Cache is automatically cleared when:**\n\n- Roles or permissions are created/updated/deleted\n- Role-permission relationships change\n\n**Configuration:**\n\n```php\n'cache' =\u003e [\n    'enabled' =\u003e true,\n    'roles_duration' =\u003e 3600,        // 1 hour\n    'permissions_duration' =\u003e 3600,  // 1 hour\n],\n```\n\n## 🗄️ Database Structure\n\n### Roles Table\n\n```php\nSchema::create('roles', function (Blueprint $table) {\n    $table-\u003eid();\n    $table-\u003estring('name')-\u003eunique();\n    $table-\u003estring('label')-\u003enullable();\n    $table-\u003etext('description')-\u003enullable();\n    $table-\u003eboolean('is_guarded')-\u003edefault(false);\n    $table-\u003etimestamps();\n});\n```\n\n### Permissions Table\n\n```php\nSchema::create('permissions', function (Blueprint $table) {\n    $table-\u003eid();\n    $table-\u003estring('name')-\u003eunique();\n    $table-\u003estring('label')-\u003enullable();\n    $table-\u003etext('description')-\u003enullable();\n    $table-\u003estring('group')-\u003enullable()-\u003eindex();\n    $table-\u003eboolean('is_wildcard')-\u003edefault(false);\n    $table-\u003etimestamps();\n});\n```\n\n### Permission-Role Pivot\n\n```php\nSchema::create('permission_role', function (Blueprint $table) {\n    $table-\u003eforeignId('permission_id')-\u003econstrained()-\u003ecascadeOnDelete();\n    $table-\u003eforeignId('role_id')-\u003econstrained()-\u003ecascadeOnDelete();\n    $table-\u003eprimary(['permission_id', 'role_id']);\n});\n```\n\n### Role-User Pivot\n\n```php\nSchema::create('role_user', function (Blueprint $table) {\n    $table-\u003eforeignId('role_id')-\u003econstrained()-\u003ecascadeOnDelete();\n    $table-\u003eforeignId('user_id')-\u003econstrained()-\u003ecascadeOnDelete();\n    $table-\u003eprimary(['role_id', 'user_id']);\n});\n```\n\n## 🔢 Enums\n\n### PermissionType\n\n```php\nuse AmdadulHaq\\Guard\\Enums\\PermissionType;\n\nPermissionType::CREATE-\u003elabel();       // \"Create\"\nPermissionType::READ-\u003elabel();         // \"Read\"\nPermissionType::WRITE-\u003elabel();        // \"Write\"\nPermissionType::UPDATE-\u003elabel();       // \"Update\"\nPermissionType::DELETE-\u003elabel();       // \"Delete\"\nPermissionType::VIEW_ANY-\u003elabel();     // \"View any\"\nPermissionType::VIEW-\u003elabel();         // \"View\"\nPermissionType::RESTORE-\u003elabel();      // \"Restore\"\nPermissionType::FORCE_DELETE-\u003elabel(); // \"Force delete\"\nPermissionType::MANAGE-\u003elabel();       // \"Manage\"\n```\n\n### CacheKey\n\n```php\nuse AmdadulHaq\\Guard\\Enums\\CacheKey;\n\nCacheKey::PERMISSIONS-\u003evalue; // 'guard_permissions'\nCacheKey::ROLES-\u003evalue;       // 'guard_roles'\n```\n\n## 🛠️ Development\n\n### Code Quality Tools\n\n```bash\n# Rector (code refactoring)\ncomposer refactor\ncomposer refactor:check\n\n# Laravel Pint (code style)\ncomposer lint\ncomposer lint:check\n\n# Pest (testing)\ncomposer test\ncomposer test-coverage\n\n# Larastan (static analysis)\ncomposer analyse\n```\n\n### Running Tests\n\n```bash\n# Run all tests\ncomposer test\n\n# With coverage\ncomposer test-coverage\n```\n\n## 🔧 Troubleshooting\n\n### Common Issues\n\n**Issue: `Class 'AmdadulHaq\\Guard\\Concerns\\HasRoles' not found`**\n\nSolution:\n\n```bash\ncomposer dump-autoload\n```\n\n**Issue: `Target class [role] does not exist.`**\n\nSolution:\n\n```bash\nphp artisan config:clear\n```\n\n**Issue: Permissions not being recognized**\n\nSolution:\n\n```bash\nphp artisan cache:clear\n# Or\nphp artisan tinker --execute=\"\\AmdadulHaq\\Guard\\Facades\\Guard::clearCache()\"\n```\n\n### Performance Tips\n\n1. **Keep caching enabled** in production\n2. **Use wildcard permissions** to reduce permission count\n3. **Filter at database level** instead of loading all users:\n\n    ```php\n    // ✅ Good\n    User::whereHas('roles', fn ($q) =\u003e $q-\u003ewhere('name', 'admin'))-\u003eget();\n\n    // ❌ Less efficient\n    User::all()-\u003efilter(fn ($u) =\u003e $u-\u003ehasRole('admin'));\n    ```\n\n4. **Eager load** when needed:\n    ```php\n    User::with(['roles', 'roles.permissions'])-\u003eget();\n    ```\n\n## ❓ FAQ\n\n**Q: Can I use this with Laravel Sanctum?**\n\nA: Yes! Guard works seamlessly with Sanctum and any auth system.\n\n**Q: Can users have permissions without roles?**\n\nA: No, users receive permissions via roles.\n\n**Q: How do wildcard permissions work?**\n\nA: Create a permission like `posts.*` and it automatically matches `posts.create`, `posts.edit`, etc.\n\n**Q: Can I customize table names?**\n\nA: Yes, publish the config and modify the `tables` section.\n\n**Q: Does it work with multiple guards?**\n\nA: Yes, it integrates with Laravel's authorization system.\n\n**Q: Is there a UI for managing roles?**\n\nA: Guard is backend-only. For a UI, consider Filament Shield or build your own.\n\n**Q: What Blade directives does Guard provide?**\n\nA: Guard ships with `@role`, `@hasrole`, `@hasanyrole`, and `@hasallroles`. Laravel's built-in `@can`, `@canany`, and `@cannot` also work through Gate integration.\n\n**Q: Can permissions be assigned to permissions?**\n\nA: No, permissions are assigned to roles.\n\n## 🤝 Contributing\n\nWe welcome contributions! Please see [CONTRIBUTING](CONTRIBUTING.md) for details.\n\n## 📝 Changelog\n\nSee [CHANGELOG](CHANGELOG.md) for recent changes.\n\n## 🔒 Security\n\nPlease review [our security policy](../../security/policy) for reporting vulnerabilities.\n\n## 👏 Credits\n\n![Contributors](https://contrib.rocks/image?repo=amdad121/guard-laravel)\n\n## 📄 License\n\nThe MIT License (MIT). See [License File](LICENSE.md) for details.\n\n---\n\n\u003cp align=\"center\"\u003eMade with ❤️ for the Laravel community\u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Famdad121%2Fguard-laravel","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Famdad121%2Fguard-laravel","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Famdad121%2Fguard-laravel/lists"}