feat(refactor): restructure roles and permissions

- Contracts renamed: HasRoles -> Roles, HasPermissions -> Permissions
- Traits moved to Concerns directory
- Middleware updated for multiple roles/permissions
- Model assignment methods accept Model|string
- Added shared Concerns: ChecksRoles, ResolvesModels

Author: amdad121

CHANGELOG.md

@@ -2,6 +2,93 @@
 
 All notable changes to `guard-laravel` will be documented in this file.
 
+## v1.3.0 - 2026-02-02
+
+### 🔨 Breaking Changes
+
+- **Contracts renamed**: `HasRoles` → `Roles`, `HasPermissions` → `Permissions`
+- **Traits moved to Concerns directory**: All traits now in `src/Concerns/`
+- **Middleware updates**: All middlewares now support multiple roles/permissions via variadic parameters
+- **Method signatures updated**: All model assignment methods now accept `Model|string` parameters
+- **Shared concerns added**: `ChecksRoles` and `ResolvesModels` traits for DRY principle
+
+### ✨ New Features
+
+- **Improved Architecture**:
+  - Contracts and traits properly separated with no naming conflicts
+  - New `ChecksRoles` trait with shared role checking logic
+  - New `ResolvesModels` trait with shared model resolution logic
+  - Better type hints throughout codebase
+  - Improved code organization and maintainability
+
+- **Middleware Enhancements**:
+  - `RoleMiddleware`: Now supports multiple roles (comma-separated or variadic)
+  - `PermissionMiddleware`: Now supports multiple permissions
+  - `RoleOrPermissionMiddleware`: Now supports multiple roles or permissions
+  - All middlewares handle both formats: `role:admin,editor` or `role:admin`, `role:editor`
+
+- **Code Quality**:
+  - 0 static analysis errors (Larastan)
+  - All files pass Laravel Pint linting
+  - Follows SOLID principles
+  - Proper separation of concerns
+
+- **Testing**:
+  - Added comprehensive middleware tests (10 new tests)
+  - Test User model now extends Authenticatable (proper Laravel usage)
+  - All 42 tests passing (77 assertions)
+  - 35 source files
+
+- **Documentation**:
+  - Updated README with new architecture
+  - Complete UPGRADE.md guide
+  - Clarified middleware usage with examples
+
+### 📚 Documentation
+
+- Updated README.md with new contract and trait structure
+- Comprehensive UPGRADE.md with migration guide
+- Added examples for middleware multiple parameters
+- Clarified import statements for new structure
+
+### 🛠️ Code Quality
+
+- Refactored code to follow DRY principle
+- Improved type hints for better IDE support
+- Better documentation comments
+- Enhanced error messages
+
+### 🔄 Migration Requirements
+
+Users upgrading to v1.3.0 need to:
+
+1. Update imports from `Guard\HasRoles` to `Guard\Concerns\HasRoles`
+2. Update imports from `Guard\HasPermissions` to `Guard\Concerns\HasPermissions`
+3. Update middleware usage to support multiple roles/permissions (if needed)
+4. Test application thoroughly after upgrade
+
+### 📊 Statistics
+
+- **Source files**: 35 (increased from 26)
+- **Tests passing**: 42 (increased from 36)
+- **Assertions**: 77 (increased from 69)
+- **Static analysis**: 0 errors
+- **Code quality**: All files pass Laravel Pint
+
+### 🐛 Bug Fixes
+
+- Fixed middleware exception handling in test environment
+- Improved type resolution in model assignment methods
+- Fixed import paths in test files
+
+### 🎯 Improvements
+
+- **SOLID Principles**: Better separation of concerns
+- **DRY Principle**: Shared traits reduce code duplication
+- **Naming Conventions**: Traits in Concerns, contracts as interfaces
+- **Flexibility**: Middleware now supports multiple parameters
+- **Maintainability**: Better code organization
+
 ## v1.1.0 - 2026-01-30
 
 ### 🔨 Breaking Changes

CLAUDE.md

@@ -54,10 +54,11 @@ If you find Guard Laravel helpful, please consider **sponsoring** the project. Y
 
 - **PHP 8.2, 8.3, 8.4, & 8.5 & Laravel 10, 11, & 12** - Modern PHP and Laravel features
 - **Role & Permission Management** - Create and manage roles with permissions
+- **Separate Concerns** - Traits and contracts are properly separated for better maintainability
 - **Wildcard Permissions** - Use wildcard patterns like `posts.*` for flexible permission checking
 - **Permission Groups** - Organize permissions into groups
 - **Guarded Roles** - Protect certain roles from deletion/modification
-- **Custom Middleware** - Built-in middleware for route protection
+- **Multiple Roles/Permissions** - Middleware now supports multiple roles/permissions at once
 - **Cache Support** - Intelligent caching with automatic invalidation
 - **Query Scopes** - Filter users by roles and permissions
 - **Custom Exceptions** - Better error messages
@@ -85,17 +86,19 @@ php artisan vendor:publish --tag="guard-migrations"
 php artisan migrate
 ```
 
-Add the `HasRoles` trait and `UserContract` interface to your User model:
+Add the `HasRoles` trait and `User` interface to your User model:
 
 ```php
 namespace App\Models;
 
 use AmdadulHaq\Guard\Contracts\User as UserContract;
-use AmdadulHaq\Guard\HasRoles;
+use AmdadulHaq\Guard\Concerns\HasRoles;
+use AmdadulHaq\Guard\Concerns\HasPermissions;
 
 class User extends Authenticatable implements UserContract
 {
     use HasRoles;
+    use HasPermissions;
 }
 ```
 
@@ -276,13 +279,10 @@ $user->revokePermissionTo('posts.delete');
 $user->revokeAllPermissions();
 
 // Check if user has direct permission
-$user->hasDirectPermission('posts.create'); // true
-
-// Get all direct permissions for user
-$user->getDirectPermissions(); // Collection of permissions
+$user->hasPermission('posts.create'); // true
 
 // Get all permissions (roles + direct)
-$user->getAllPermissions(); // Collection of all permissions
+$user->getPermissions(); // Collection of all permissions
 ```
 
 ### Checking Roles
@@ -347,20 +347,38 @@ User::withPermissions('users.create')->get();
 
 ### Middleware
 
-Protect routes using built-in middleware:
+Protect routes using built-in middleware. All middlewares support multiple roles/permissions:
 
 ```php
+// Single permission
 Route::middleware('permission:users.create')->group(function () {
     Route::post('/users', [UserController::class, 'store']);
 });
 
+// Multiple permissions (requires any of them)
+Route::middleware('permission:users.create,users.edit')->group(function () {
+    Route::put('/users/{id}', [UserController::class, 'update']);
+});
+
+// Single role
 Route::middleware('role:administrator')->group(function () {
     Route::delete('/users/{id}', [UserController::class, 'destroy']);
 });
 
-Route::middleware('role_or_permission:users.create')->group(function () {
+// Multiple roles (requires any of them)
+Route::middleware('role:admin,editor')->group(function () {
+    Route::get('/admin', [AdminController::class, 'dashboard']);
+});
+
+// Role OR permission
+Route::middleware('role_or_permission:admin,users.create')->group(function () {
     Route::get('/users', [UserController::class, 'index']);
 });
+
+// Multiple role_or_permission
+Route::middleware('role_or_permission:admin,editor,users.manage')->group(function () {
+    Route::post('/manage', [Controller::class, 'handle']);
+});
 ```
 
 ### Gate Integration