feat: Enhance role and permission management

- Added `revokeAllPermissions()` to HasPermissions trait
- Added `hasPermissionTo()` to HasPermissions trait
- Added `syncRolesWithoutDetaching()` to HasRoles trait
- Added `revokeRoles()` and `getRoleNames()` to HasRoles trait
- Improved type handling in `hasRole()` and related methods
- Updated model configurations and cache settings
- Refactored permission and role creation commands

Author: amdad121

CHANGELOG.md

@@ -2,6 +2,52 @@
 
 All notable changes to `guard-laravel` will be documented in this file.
 
+## v1.1.0 - 2026-01-30
+
+### 🔨 Breaking Changes
+
+- Removed deprecated `detach()` usage in `syncRoles()` method
+- Changed return type of `assignRole()` from `Model` to `self`
+- Changed `revokeRole()` return type from `int` to `int` (number of roles remaining)
+
+### ✨ New Features
+
+- **HasPermissions Trait**:
+  - Added `revokeAllPermissions()` method to revoke all permissions
+  - Added `hasPermissionTo()` method to check if role has a permission
+
+- **HasRoles Trait**:
+  - Added `syncRolesWithoutDetaching()` method to sync roles without detaching
+  - Added `revokeRole()` method to revoke a single role
+  - Added `revokeRoles()` method to revoke all roles
+  - Added `getRoleNames()` method to get all role names
+  - Improved `hasRole()` to handle Collection types
+  - Improved `hasAllRoles()` and `hasAnyRole()` to handle Collection types
+  - Simplified wildcard matching using `contains()` with closure
+
+- **Models**:
+  - Removed outdated `static $table` pattern from `Permission` and `Role` models
+  - Now uses Laravel's built-in `getTable()` with config fallback
+
+- **Service Provider**:
+  - Fixed `permissionsTableExists()` to use config table name
+  - Improved `registerModelObservers()` readability using `->each()`
+  - Improved `defineGatePermissions()` and `defineGateRoles()` readability
+
+### 📚 Documentation
+
+- Added comprehensive Laravel-style documentation comments to config file
+- Added docblocks to all methods in Service Provider
+- Updated configuration documentation with type casting examples
+- Updated Contributing guide with correct script names
+- Updated code examples for new methods
+
+### 🛠️ Code Quality
+
+- Improved type hints throughout codebase
+- Added proper exception handling documentation
+- Refactored code for better readability and maintainability
+
 ## v1.0.0 - 2025-01-01
 
 ### 🎉 Initial Stable Release

CLAUDE.md

@@ -0,0 +1,179 @@
+# Guard Laravel - Claude Code Guidelines
+
+## Development Commands
+
+```bash
+# Format code with Laravel Pint
+composer lint
+
+# Check code style without modifying files
+composer lint:check
+
+# Run static analysis with Larastan
+composer analyse
+
+# Run code refactoring with Rector
+composer refactor
+
+# Check Rector dry-run
+composer refactor:check
+
+# Run Pest tests
+composer test
+
+# Run tests with coverage
+composer test-coverage
+```
+
+## Architecture Overview
+
+### Package Purpose
+
+Guard is a modern Role and Permission management system for Laravel 10, 11, and 12 with PHP 8.2-8.5 support. It provides comprehensive ACL functionality with wildcard permissions, caching, and middleware protection.
+
+### Key Components
+
+#### Contracts (`src/Contracts/`)
+
+Define the interface that models must implement:
+
+- **User**: Interface for models using roles/permissions (methods: `hasRole()`, `hasPermission()`, `assignRole()`, `syncRoles()`, etc.)
+- **Role**: Interface for role models (methods: `getName()`, `permissions()`, `givePermissionTo()`, `syncPermissions()`, etc.)
+- **Permission**: Interface for permission models (methods: `getName()`, `roles()`, `isWildcard()`, `getGroup()`, `getType()`, etc.)
+
+#### Models (`src/Models/`)
+
+- **Role**: Eloquent model with `is_guarded` boolean for protecting system-critical roles
+- **Permission**: Eloquent model with wildcard detection and grouping support
+
+#### Traits (`src/`)
+
+- **HasRoles**: Primary trait for user models, implements all role management methods
+- **HasPermissions**: Trait for role models, implements all permission management methods
+
+#### Service Provider (`src/GuardServiceProvider.php`)
+
+- Registers models, commands, middleware
+- Defines Gates for authorization (`Gate::define()`)
+- Handles automatic cache invalidation via model observers
+- Validates configured models exist (skips user model during tests)
+
+#### Middleware
+
+- **RoleMiddleware**: Checks user has specific role
+- **PermissionMiddleware**: Checks user has specific permission
+- **RoleOrPermissionMiddleware**: Checks user has role OR permission
+
+#### Commands
+
+- `guard:create-role`: Create new roles with optional label and user assignment
+- `guard:create-permission`: Create new permissions with optional label and role assignment
+
+### Laravel Integration
+
+#### Service Provider Registration
+
+Automatically registered via `extra.laravel.providers` in composer.json
+
+#### Facade
+
+```php
+use AmdadulHaq\Guard\Facades\Guard;
+```
+
+#### Configuration
+
+Published to `config/guard.php` with:
+
+- `models`: User, Role, Permission model mappings
+- `tables`: Custom table names
+- `cache`: Cache duration settings
+- `middleware`: Middleware aliases
+- `wildcard`: Enable wildcard permissions
+
+### Role-Permission Relationship
+
+#### Database Structure
+
+- **roles**: `id`, `name`, `label`, `description`, `is_guarded`, timestamps
+- **permissions**: `id`, `name`, `label`, `description`, `group`, `is_wildcard`, timestamps
+- **permission_role**: Pivot table for role-permission relationships
+- **role_user**: Pivot table for user-role relationships
+
+#### Key Features
+
+- Many-to-many relationships between roles and permissions
+- Many-to-many between users and roles
+- Wildcard permissions (`posts.*` matches `posts.create`, `posts.edit`, etc.)
+- Permission groups for organization
+- Guarded roles that can't be deleted
+
+### Caching Mechanism
+
+#### Automatic Cache Invalidation
+
+- Cache keys defined in `CacheKey` enum (`guard_roles`, `guard_permissions`)
+- Cache cleared automatically on model save/deleted via observers
+
+#### Manual Cache Clear
+
+```php
+Guard::clearCache();
+```
+
+### Wildcard Permissions System
+
+#### Implementation
+
+- Permissions ending with `*` are automatically marked as wildcards in the `booted()` static method
+- Wildcard matching uses pattern prefix comparison (e.g., `posts.*` matches `posts.create`)
+- Pattern format: `resource.action` where `action` can be `*`
+
+#### Usage
+
+```php
+// Create wildcard permission
+$permission = Permission::create(['name' => 'posts.*']);
+
+// User with wildcard permission can access all matching permissions
+$user->hasPermission('posts.create'); // returns true
+```
+
+### Contract Implementation Requirements
+
+All contract interfaces must be implemented by their respective models. When implementing `UserContract`:
+
+```php
+use AmdadulHaq\Guard\Contracts\User as UserContract;
+use AmdadulHaq\Guard\HasPermissions;
+use AmdadulHaq\Guard\HasRoles;
+
+class User extends Authenticatable implements UserContract
+{
+    use HasPermissions, HasRoles;
+}
+```
+
+### Important Implementation Notes
+
+#### Type Safety
+
+- Uses PHP 8.2+ strict types on all files
+- Enums for `CacheKey` and `PermissionType`
+- Return types on all public methods
+- Collection type is `Illuminate\Support\Collection` for methods returning permission/role names
+
+#### Exception Handling
+
+- Custom exceptions in `src/Exceptions/`
+- `PermissionDeniedException` for failed middleware checks
+- `RoleDoesNotExistException` for missing roles
+- `PermissionDoesNotExistException` for missing permissions
+
+#### Test Models
+
+Test models in `tests/Models/User.php` must implement the same methods as the actual User model, including `getRoleNames()` and `getPermissionNames()`.
+
+#### Guarded Roles
+
+Protected roles (with `is_guarded = true`) cannot be deleted through standard operations. Use `isProtectedRole()` to check protection status.

CONTRIBUTING.md

@@ -30,10 +30,10 @@ Ensure your code follows Laravel Pint standards:
 
 ```bash
 # Check code style
-composer format:check
+composer lint:check
 
 # Fix code style
-composer format
+composer lint
 ```
 
 ## Static Analysis
@@ -49,7 +49,7 @@ composer analyse
 1. Create a new branch from `main`
 2. Write tests for your changes
 3. Ensure all tests pass (`composer test`)
-4. Ensure code style passes (`composer format:check`)
+4. Ensure code style passes (`composer lint:check`)
 5. Ensure static analysis passes (`composer analyse`)
 6. Submit a pull request with a clear description of changes
 

README.md

@@ -127,9 +127,9 @@ return [
         'permissions' => 'permissions',
     ],
     'cache' => [
-        'permissions_duration' => env('GUARD_PERMISSIONS_CACHE_DURATION', 3600),
-        'roles_duration' => env('GUARD_ROLES_CACHE_DURATION', 3600),
         'enabled' => env('GUARD_CACHE_ENABLED', true),
+        'roles_duration' => (int) env('GUARD_ROLES_CACHE_DURATION', 3600),
+        'permissions_duration' => (int) env('GUARD_PERMISSIONS_CACHE_DURATION', 3600),
     ],
     'middleware' => [
         'role' => 'role',
@@ -189,17 +189,30 @@ $user->hasPermission('posts.delete'); // true
 ### Assigning Permissions to Roles
 
 ```php
-// Assign a single permission
+use AmdadulHaq\Guard\Models\Permission;
+
+// Assign a single permission by model
 $role->givePermissionTo($permission);
+
+// Assign a single permission by name
 $role->givePermissionTo('users.create');
 
 // Sync multiple permissions (supports both IDs and names)
 $role->syncPermissions([$permission1->id, $permission2->id]);
 $role->syncPermissions(['users.create', 'users.edit', 'users.delete']);
 
-// Revoke a permission
+// Sync without detaching existing permissions
+$role->syncRolesWithoutDetaching(['editor', 'moderator']);
+
+// Revoke a specific permission
 $role->revokePermissionTo($permission);
 $role->revokePermissionTo('users.delete');
+
+// Revoke all permissions
+$role->revokeAllPermissions();
+
+// Check if role has a permission
+$role->hasPermissionTo('users.edit'); // true or false
 ```
 
 ### Assigning Roles to Users
@@ -218,8 +231,24 @@ $user->assignRole('administrator');
 // Sync multiple roles
 $user->syncRoles([$role1->id, $role2->id]);
 
-// Revoke a role
+// Sync without detaching existing roles
+$user->syncRolesWithoutDetaching(['editor', 'moderator']);
+
+// Revoke a specific role
 $user->revokeRole($role);
+$user->revokeRole('editor');
+
+// Revoke all roles
+$user->revokeRoles();
+
+// Get all role names
+$user->getRoleNames(); // ['administrator', 'editor']
+
+// Check if model has all specified roles
+$user->hasAllRoles(['admin', 'editor']); // true if user has both
+
+// Check if model has any of the specified roles
+$user->hasAnyRole(['admin', 'editor']); // true if user has at least one
 ```
 
 ### Direct User Permissions
@@ -243,6 +272,9 @@ $user->syncPermissions(['posts.create', 'posts.update', 'posts.delete']);
 // Revoke specific permission
 $user->revokePermissionTo('posts.delete');
 
+// Revoke all permissions
+$user->revokeAllPermissions();
+
 // Check if user has direct permission
 $user->hasDirectPermission('posts.create'); // true
 
@@ -422,9 +454,9 @@ Role::unguarded()->get(); // Get all unguarded roles
 The package automatically caches permissions and roles. Clear cache manually:
 
 ```php
-use AmdadulHaq\Guard\GuardServiceProvider;
+use AmdadulHaq\Guard\Facades\Guard;
 
-GuardServiceProvider::staticClearCache();
+Guard::clearCache();
 ```
 
 Cache is automatically invalidated when roles or permissions are created, updated, or deleted.