AAuth Implementation Guide

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

Installation

composer require aurora-web-software/aauth

php artisan vendor:publish --tag=aauth-config
php artisan vendor:publish --tag=aauth-migrations
php artisan migrate

Step 1: Prepare User Model

Your User model must implement AAuthUserContract:

<?php

namespace App\Models;

use AuroraWebSoftware\AAuth\Contracts\AAuthUserContract;
use AuroraWebSoftware\AAuth\Traits\AAuthUser;
use Illuminate\Foundation\Auth\User as Authenticatable;

class User extends Authenticatable implements AAuthUserContract
{
    use AAuthUser;

    // Your existing code...
}

Step 2: Basic Permission Checks

In Controllers

use AuroraWebSoftware\AAuth\Facades\AAuth;

class PostController extends Controller
{
    public function edit(Post $post)
    {
        // Simple permission check
        if (!AAuth::can('edit-post')) {
            abort(403);
        }

        return view('posts.edit', compact('post'));
    }

    public function approve(Post $post)
    {
        // Parametric permission - check if user can approve this amount
        if (!AAuth::can('approve-budget', [$post->amount])) {
            abort(403, 'Budget limit exceeded');
        }

        $post->approve();
        return redirect()->back();
    }
}

Using passOrAbort (Shortcut)

public function edit(Post $post)
{
    AAuth::passOrAbort('edit-post');

    return view('posts.edit', compact('post'));
}

Step 3: Middleware Usage

Register Middleware (Laravel 11+)

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

Apply to Routes

// Permission middleware
Route::get('/posts/{post}/edit', [PostController::class, 'edit'])
    ->middleware('aauth.permission:edit-post');

// Role middleware
Route::get('/admin/dashboard', [AdminController::class, 'index'])
    ->middleware('aauth.role:admin');

// Multiple permissions
Route::resource('users', UserController::class)
    ->middleware('aauth.permission:manage-users');

Step 4: Blade Directives

{{-- Show only if user has permission --}}
@aauth('edit-post')
    <a href="{{ route('posts.edit', $post) }}">Edit</a>
@endaauth

{{-- With parametric permission --}}
@aauth('approve-budget', [1000])
    <button>Approve</button>
@endaauth

Step 5: Role Management

Create Roles

use AuroraWebSoftware\AAuth\Models\Role;

// System role (global, no organization)
$adminRole = Role::create([
    'name' => 'admin',
    'type' => 'system',
    'status' => 'active',
]);

// Organization role (tied to organization hierarchy)
$managerRole = Role::create([
    'name' => 'manager',
    'type' => 'organization',
    'organization_scope_id' => $scopeId,
    'status' => 'active',
]);

Assign Permissions to Role

use AuroraWebSoftware\AAuth\Services\RolePermissionService;

$service = app(RolePermissionService::class);

// Simple permission
$service->givePermissionToRole($roleId, 'edit-post');

// Parametric permission with max value
$service->givePermissionToRole($roleId, 'approve-budget', [
    'max_amount' => 5000
]);

// Parametric permission with allowed values
$service->givePermissionToRole($roleId, 'manage-department', [
    'departments' => ['HR', 'IT', 'Finance']
]);

Assign Role to User

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

Step 6: Organization Hierarchy (Optional)

Create Organization Scope

use AuroraWebSoftware\AAuth\Models\OrganizationScope;

// Define hierarchy levels
OrganizationScope::create(['name' => 'Company', 'level' => 1]);
OrganizationScope::create(['name' => 'Department', 'level' => 2]);
OrganizationScope::create(['name' => 'Team', 'level' => 3]);

Create Organization Nodes

use AuroraWebSoftware\AAuth\Models\OrganizationNode;

// Root node
$company = OrganizationNode::create([
    'name' => 'Acme Corp',
    'organization_scope_id' => 1,
    'path' => '1',
]);

// Child nodes
$hrDept = OrganizationNode::create([
    'name' => 'HR Department',
    'organization_scope_id' => 2,
    'parent_id' => $company->id,
    'path' => '1/2',
]);

Query User's Accessible Nodes

// Get all accessible organization nodes
$nodes = AAuth::organizationNodes();

// With query builder for custom filters
$nodes = AAuth::organizationNodesQuery()
    ->where('organization_scope_id', 2)
    ->get();

// Check if node is descendant
if (AAuth::descendant($parentNodeId, $childNodeId)) {
    // User can access this node
}

Step 7: Caching Configuration

Edit config/aauth-advanced.php:

'cache' => [
    'enabled' => env('AAUTH_CACHE_ENABLED', true),
    'store' => env('AAUTH_CACHE_STORE', null), // null = default driver
    'ttl' => env('AAUTH_CACHE_TTL', 3600),
    'prefix' => env('AAUTH_CACHE_PREFIX', 'aauth'),
],

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:

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

Add column to users table:

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

Common Scenarios

Scenario 1: Blog with Roles

// Create roles
$adminRole = Role::create(['name' => 'admin', 'type' => 'system', 'status' => 'active']);
$editorRole = Role::create(['name' => 'editor', 'type' => 'system', 'status' => 'active']);
$authorRole = Role::create(['name' => 'author', 'type' => 'system', 'status' => 'active']);

// Assign permissions
$service->givePermissionToRole($adminRole->id, 'manage-users');
$service->givePermissionToRole($adminRole->id, 'manage-posts');
$service->givePermissionToRole($editorRole->id, 'edit-any-post');
$service->givePermissionToRole($authorRole->id, 'create-post');
$service->givePermissionToRole($authorRole->id, 'edit-own-post');

Scenario 2: Multi-Tenant with Budget Limits

// Department manager can approve up to 10,000
$service->givePermissionToRole($deptManagerRole->id, 'approve-budget', [
    'max_amount' => 10000
]);

// Team lead can approve up to 1,000
$service->givePermissionToRole($teamLeadRole->id, 'approve-budget', [
    'max_amount' => 1000
]);

// In controller
public function approvePurchase(Purchase $purchase)
{
    if (!AAuth::can('approve-budget', [$purchase->amount])) {
        abort(403, 'Amount exceeds your approval limit');
    }

    $purchase->approve();
}

Scenario 3: Department-Based Access

// Give access to specific departments
$service->givePermissionToRole($roleId, 'view-reports', [
    'departments' => ['HR', 'Finance']
]);

// Check access
if (AAuth::can('view-reports', ['HR'])) {
    // Can view HR reports
}

Helper Functions

// Global helper function
if (aauth_can('edit-post')) {
    // ...
}

// With parameters
if (aauth_can('approve-budget', [5000])) {
    // ...
}

Troubleshooting

Permission Not Working

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

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

3. Check user has role:

   dd($user->roles);
   

Cache Not Updating

// Clear AAuth context manually
AAuth::clearContext();

// Or clear specific cache keys
Cache::forget('aauth:role:' . $roleId);

Super Admin Not Working

Check your User model has the column:

dd($user->is_super_admin);

Check config is enabled:

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

Quick Reference

Permission Types

Essential Methods

Middleware