AAuth Implementation Guide

AAuth is a Laravel RBAC package with organization hierarchy and parametric permissions.

Installation

bash
1composer require aurora-web-software/aauth

bash
1php artisan vendor:publish --tag=aauth-config
2php artisan vendor:publish --tag=aauth-migrations
3php artisan migrate

Step 1: Prepare User Model

Your User model must implement AAuthUserContract:

php
1<?php
2
3namespace App\Models;
4
5use AuroraWebSoftware\AAuth\Contracts\AAuthUserContract;
6use AuroraWebSoftware\AAuth\Traits\AAuthUser;
7use Illuminate\Foundation\Auth\User as Authenticatable;
8
9class User extends Authenticatable implements AAuthUserContract
10{
11    use AAuthUser;
12
13    // Your existing code...
14}

Step 2: Basic Permission Checks

In Controllers

php
1use AuroraWebSoftware\AAuth\Facades\AAuth;
2
3class PostController extends Controller
4{
5    public function edit(Post $post)
6    {
7        // Simple permission check
8        if (!AAuth::can('edit-post')) {
9            abort(403);
10        }
11
12        return view('posts.edit', compact('post'));
13    }
14
15    public function approve(Post $post)
16    {
17        // Parametric permission - check if user can approve this amount
18        if (!AAuth::can('approve-budget', [$post->amount])) {
19            abort(403, 'Budget limit exceeded');
20        }
21
22        $post->approve();
23        return redirect()->back();
24    }
25}

Using passOrAbort (Shortcut)

php
1public function edit(Post $post)
2{
3    AAuth::passOrAbort('edit-post');
4
5    return view('posts.edit', compact('post'));
6}

Step 3: Middleware Usage

Register Middleware (Laravel 11+)

php
1// bootstrap/app.php
2->withMiddleware(function (Middleware $middleware) {
3    $middleware->alias([
4        'aauth.permission' => \AuroraWebSoftware\AAuth\Http\Middleware\AAuthPermission::class,
5        'aauth.role' => \AuroraWebSoftware\AAuth\Http\Middleware\AAuthRole::class,
6    ]);
7})

Apply to Routes

php
1// Permission middleware
2Route::get('/posts/{post}/edit', [PostController::class, 'edit'])
3    ->middleware('aauth.permission:edit-post');
4
5// Role middleware
6Route::get('/admin/dashboard', [AdminController::class, 'index'])
7    ->middleware('aauth.role:admin');
8
9// Multiple permissions
10Route::resource('users', UserController::class)
11    ->middleware('aauth.permission:manage-users');

Step 4: Blade Directives

blade
1{{-- Show only if user has permission --}}
2@aauth('edit-post')
3    <a href="{{ route('posts.edit', $post) }}">Edit</a>
4@endaauth
5
6{{-- With parametric permission --}}
7@aauth('approve-budget', [1000])
8    <button>Approve</button>
9@endaauth

Step 5: Role Management

Create Roles

php
1use AuroraWebSoftware\AAuth\Models\Role;
2
3// System role (global, no organization)
4$adminRole = Role::create([
5    'name' => 'admin',
6    'type' => 'system',
7    'status' => 'active',
8]);
9
10// Organization role (tied to organization hierarchy)
11$managerRole = Role::create([
12    'name' => 'manager',
13    'type' => 'organization',
14    'organization_scope_id' => $scopeId,
15    'status' => 'active',
16]);

Assign Permissions to Role

php
1use AuroraWebSoftware\AAuth\Services\RolePermissionService;
2
3$service = app(RolePermissionService::class);
4
5// Simple permission
6$service->givePermissionToRole($roleId, 'edit-post');
7
8// Parametric permission with max value
9$service->givePermissionToRole($roleId, 'approve-budget', [
10    'max_amount' => 5000
11]);
12
13// Parametric permission with allowed values
14$service->givePermissionToRole($roleId, 'manage-department', [
15    'departments' => ['HR', 'IT', 'Finance']
16]);

Assign Role to User

php
1$service->attachRoleToUser($user, $roleId, $organizationNodeId);

Step 6: Organization Hierarchy (Optional)

Create Organization Scope

php
1use AuroraWebSoftware\AAuth\Models\OrganizationScope;
2
3// Define hierarchy levels
4OrganizationScope::create(['name' => 'Company', 'level' => 1]);
5OrganizationScope::create(['name' => 'Department', 'level' => 2]);
6OrganizationScope::create(['name' => 'Team', 'level' => 3]);

Create Organization Nodes

php
1use AuroraWebSoftware\AAuth\Models\OrganizationNode;
2
3// Root node
4$company = OrganizationNode::create([
5    'name' => 'Acme Corp',
6    'organization_scope_id' => 1,
7    'path' => '1',
8]);
9
10// Child nodes
11$hrDept = OrganizationNode::create([
12    'name' => 'HR Department',
13    'organization_scope_id' => 2,
14    'parent_id' => $company->id,
15    'path' => '1/2',
16]);

Query User's Accessible Nodes

php
1// Get all accessible organization nodes
2$nodes = AAuth::organizationNodes();
3
4// With query builder for custom filters
5$nodes = AAuth::organizationNodesQuery()
6    ->where('organization_scope_id', 2)
7    ->get();
8
9// Check if node is descendant
10if (AAuth::descendant($parentNodeId, $childNodeId)) {
11    // User can access this node
12}

Step 7: Caching Configuration

Edit config/aauth-advanced.php:

php
1'cache' => [
2    'enabled' => env('AAUTH_CACHE_ENABLED', true),
3    'store' => env('AAUTH_CACHE_STORE', null), // null = default driver
4    'ttl' => env('AAUTH_CACHE_TTL', 3600),
5    'prefix' => env('AAUTH_CACHE_PREFIX', 'aauth'),
6],

In .env:

AAUTH_CACHE_ENABLED=true
AAUTH_CACHE_STORE=redis
AAUTH_CACHE_TTL=3600

Step 8: Super Admin (Optional)

Enable users to bypass all permission checks:

php
1// config/aauth-advanced.php
2'super_admin' => [
3    'enabled' => env('AAUTH_SUPER_ADMIN_ENABLED', true),
4    'column' => 'is_super_admin',
5],

Add column to users table:

php
1$table->boolean('is_super_admin')->default(false);

Common Scenarios

Scenario 1: Blog with Roles

php
1// Create roles
2$adminRole = Role::create(['name' => 'admin', 'type' => 'system', 'status' => 'active']);
3$editorRole = Role::create(['name' => 'editor', 'type' => 'system', 'status' => 'active']);
4$authorRole = Role::create(['name' => 'author', 'type' => 'system', 'status' => 'active']);
5
6// Assign permissions
7$service->givePermissionToRole($adminRole->id, 'manage-users');
8$service->givePermissionToRole($adminRole->id, 'manage-posts');
9$service->givePermissionToRole($editorRole->id, 'edit-any-post');
10$service->givePermissionToRole($authorRole->id, 'create-post');
11$service->givePermissionToRole($authorRole->id, 'edit-own-post');

Scenario 2: Multi-Tenant with Budget Limits

php
1// Department manager can approve up to 10,000
2$service->givePermissionToRole($deptManagerRole->id, 'approve-budget', [
3    'max_amount' => 10000
4]);
5
6// Team lead can approve up to 1,000
7$service->givePermissionToRole($teamLeadRole->id, 'approve-budget', [
8    'max_amount' => 1000
9]);
10
11// In controller
12public function approvePurchase(Purchase $purchase)
13{
14    if (!AAuth::can('approve-budget', [$purchase->amount])) {
15        abort(403, 'Amount exceeds your approval limit');
16    }
17
18    $purchase->approve();
19}

Scenario 3: Department-Based Access

php
1// Give access to specific departments
2$service->givePermissionToRole($roleId, 'view-reports', [
3    'departments' => ['HR', 'Finance']
4]);
5
6// Check access
7if (AAuth::can('view-reports', ['HR'])) {
8    // Can view HR reports
9}

Helper Functions

php
1// Global helper function
2if (aauth_can('edit-post')) {
3    // ...
4}
5
6// With parameters
7if (aauth_can('approve-budget', [5000])) {
8    // ...
9}

Troubleshooting

Permission Not Working

1. Clear cache: php artisan cache:clear
2. Check role has permission:

   php
   1$role = Role::find($roleId);
   2dd($role->rolePermissions);

3. Check user has role:

   php
   1dd($user->roles);

Cache Not Updating

php
1// Clear AAuth context manually
2AAuth::clearContext();
3
4// Or clear specific cache keys
5Cache::forget('aauth:role:' . $roleId);

Super Admin Not Working

Check your User model has the column:

php
1dd($user->is_super_admin);

Check config is enabled:

php
1dd(config('aauth-advanced.super_admin.enabled'));

Quick Reference

Permission Types

Essential Methods

Middleware