PHP code example of amdadulhaq / guard-laravel

    
        
<?php
require_once('vendor/autoload.php');

/* Start to develop here. Best regards https://php-download.com/ */

    

amdadulhaq / guard-laravel example snippets

namespace App\Models;

use AmdadulHaq\Guard\Contracts\Roleable as RoleableContract;
use AmdadulHaq\Guard\Concerns\Roleable;
use Illuminate\Foundation\Auth\User as Authenticatable;

class User extends Authenticatable implements RoleableContract
{
    use Roleable;
}

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

namespace App\Models;

use AmdadulHaq\Guard\Contracts\Roleable as RoleableContract;
use AmdadulHaq\Guard\Concerns\Roleable;
use Illuminate\Foundation\Auth\User as Authenticatable;

class User extends Authenticatable implements RoleableContract
{
    use Roleable;
}

return [
    'models' => [
        'user' => \App\Models\User::class,
        'role' => \AmdadulHaq\Guard\Models\Role::class,
        'permission' => \AmdadulHaq\Guard\Models\Permission::class,
    ],
    'tables' => [
        'roles' => 'roles',
        'permissions' => 'permissions',
    ],
    'middleware' => [
        'role' => 'role',
        'permission' => 'permission',
        'role_or_permission' => 'role_or_permission',
    ],
    'wildcard' => [
        'enabled' => env('GUARD_WILDCARD_ENABLED', true),
    ],
];

// config/guard.php
'models' => [
    'user' => \App\Models\User::class,
    'role' => \App\Models\Role::class,        // extends AmdadulHaq\Guard\Models\Role
    'permission' => \App\Models\Permission::class, // extends AmdadulHaq\Guard\Models\Permission
],

use AmdadulHaq\Guard\Contracts\Roleable as RoleableContract;
use AmdadulHaq\Guard\Concerns\Roleable;

class User extends Authenticatable implements RoleableContract
{
    use Roleable;
}

use AmdadulHaq\Guard\Models\Role;

// Set fields on create (or later via update())
$role = Role::create([
    'name' => 'administrator',        //  protect from deletion
]);

$role->update(['label' => 'Admin']);

// Get fields
$role->getName();              // 'administrator'
$role->getLabel();             // 'Administrator'
$role->getDescription();       // 'Full system access'
$role->isProtectedRole();      // true — deleting now throws GuardedRoleException

// Other role methods
$role->getPermissionNames();   // All permission names assigned to the role
$role->users;                  // Users with this role

// Query scopes
Role::guarded()->get();        // Only guarded roles
Role::unguarded()->get();      // Only unguarded roles

use AmdadulHaq\Guard\Models\Permission;

// Set fields on create — only 'name' is d, unique — used by all checks
    'label' => 'Delete Users',        // optional display name
    'description' => 'Permanently remove user accounts',
    'group' => 'users',               // optional stored grouping
]);

// Wildcard permission — is_wildcard is set automatically when name ends with '*'
Permission::create([
    'name' => 'posts.*',
    'label' => 'Manage All Posts',
    'group' => 'posts',
]);

// Get fields
$permission->getName();         // 'users.delete'
$permission->getLabel();        // 'Delete Users'
$permission->getDescription();  // 'Permanently remove user accounts'
$permission->getGroup();        // 'users' (derived from the name prefix)
$permission->isWildcard();      // false
$permission->getType();         // PermissionType::DELETE (from the last name segment)
$permission->roles;             // Roles with this permission

// Query scopes — group permissions for an admin UI
Permission::wildcard()->get();           // Only wildcard permissions
Permission::byGroup('users')->get();     // All users.* permissions
Permission::all()->groupBy->getGroup();  // ['users' => [...], 'posts' => [...]]

// Create wildcard permission
Permission::create(['name' => 'posts.*']);

// Assign to role
$role->givePermissionTo('posts.*');

// Now user can do all of these:
$user->hasPermission('posts.create');  // true
$user->hasPermission('posts.update');  // true
$user->hasPermission('posts.delete');  // true
$user->hasPermission('posts.publish'); // true

// Single role
$user->assignRole('administrator'); // by role name
$user->assignRole($roleModel); // by role model

// Multiple roles in one call
$user->assignRole('administrator', 'editor');
$user->assignRole([$roleModel, $roleId, 'moderator']);

// Sync (replaces all)
$user->syncRoles(['administrator', 'editor']);
$user->syncRoles([$role1->id, $role2->id]);

// Sync without detaching existing
$user->syncRolesWithoutDetaching(['moderator']);

// Revoke
$user->revokeRole('editor');
$user->revokeRole($roleModel);
$user->revokeRoles(); // Revoke all

// Single role
$user->hasRole('administrator');              // true/false

// Multiple roles
$user->hasAllRoles(['admin', 'editor']);     // Must have ALL
$user->hasAnyRole(['admin', 'moderator']);   // Must have ANY

// Get role names
$user->getRoleNames(); // ['administrator', 'editor']

// Get role labels keyed by name (falls back to name when no label)
$user->getRoleLabels(); // ['administrator' => 'Administrator', 'editor' => 'editor']

// Single permission
$role->givePermissionTo('users.create'); // by permission name
$role->givePermissionTo($permissionModel); // by permission model

// Multiple permissions in one call
$role->givePermissionTo('users.create', 'users.edit');
$role->givePermissionTo([$permissionModel, $permissionId, 'users.delete']);

// Sync (replaces all)
$role->syncPermissions(['users.create', 'users.edit']);
$role->syncPermissions([$perm1->id, $perm2->id]);

// Revoke
$role->revokePermissionTo('users.delete');
$role->revokePermissionTo($permissionModel);
$role->revokeAllPermissions();

$role->hasPermission('users.edit');    // Check if role has permission
$role->getPermissionNames();             // Get all permission names

// Check by name
$user->hasPermission('users.create');

// Check by model
$user->hasPermission($permissionModel);

// Wildcard matching
$user->hasPermission('posts.*');

// Get all permissions inherited from roles
$user->getPermissions();

// Get permission names array
$user->getPermissionNames(); // ['users.create', 'users.edit']

if ($user->hasRole('administrator')) {
    // User has administrator role
}

if ($user->hasAllRoles(['admin', 'editor'])) {
    // User has both roles
}

if ($user->hasAnyRole(['admin', 'moderator'])) {
    // User has at least one role
}

// Get all role names
$user->getRoleNames(); // ['administrator', 'editor']

if ($user->hasPermission('users.create')) {
    // User can create users
}

if ($user->hasPermission('posts.*')) {
    // User has wildcard permission for posts
}

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

// Multiple roles (});

// Permission middleware
Route::middleware('permission:users.create')->post('/users', [UserController::class, 'store']);

// Multiple permissions (ssion
Route::middleware('role_or_permission:admin,editor,posts.manage')->group(function () {
    Route::post('/manage', [Controller::class, 'handle']);
});

// In controllers
public function store(Request $request)
{
    $this->authorize('users.create');
    // User can create users
}

// Using Gate facade
use Illuminate\Support\Facades\Gate;

if (Gate::allows('users.create')) {
    // Allowed
}

if (Gate::denies('users.delete')) {
    abort(403, 'Permission denied');
}

// Check for specific user
if (Gate::forUser($otherUser)->allows('posts.edit')) {
    // That user can edit posts
}

// Authorize roles
$this->authorize('administrator');

// Users with a specific role
User::query()->withRoles('administrator')->get();

// Users with a specific permission inherited through roles
User::query()->withPermissions('users.create')->get();

// Role scopes
Role::query()->guarded()->get();
Role::query()->unguarded()->get();

// Permission scopes
Permission::query()->wildcard()->get();
Permission::query()->byGroup('users')->get();

use AmdadulHaq\Guard\Facades\Guard;

Guard::getSingularName('roles');          // 'role'
Guard::getTableName(Role::class);         // 'roles' (resolves the model's table)
Guard::getPivotTableName([Role::class, User::class]); // 'role_user' (alphabetical)

use AmdadulHaq\Guard\Exceptions\PermissionDeniedException;
use AmdadulHaq\Guard\Exceptions\GuardedRoleException;

// Thrown by the middleware when a user lacks the ::roleNotAssigned('administrator');
throw PermissionDeniedException::roleOrPermissionNotAssigned('admin, users.delete');

// Thrown when deleting a role with is_guarded = true
throw GuardedRoleException::cannotDelete('super-admin');

Schema::create('roles', function (Blueprint $table) {
    $table->id();
    $table->string('name')->unique();
    $table->string('label')->nullable();
    $table->text('description')->nullable();
    $table->boolean('is_guarded')->default(false);
    $table->timestamps();
});

Schema::create('permissions', function (Blueprint $table) {
    $table->id();
    $table->string('name')->unique();
    $table->string('label')->nullable();
    $table->text('description')->nullable();
    $table->string('group')->nullable()->index();
    $table->boolean('is_wildcard')->default(false);
    $table->timestamps();
});

Schema::create('permission_role', function (Blueprint $table) {
    $table->foreignId('permission_id')->constrained()->cascadeOnDelete();
    $table->foreignId('role_id')->constrained()->cascadeOnDelete();
    $table->primary(['permission_id', 'role_id']);
});

Schema::create('role_user', function (Blueprint $table) {
    $table->foreignId('role_id')->constrained()->cascadeOnDelete();
    $table->foreignId('user_id')->constrained()->cascadeOnDelete();
    $table->primary(['role_id', 'user_id']);
});

use AmdadulHaq\Guard\Enums\PermissionType;

PermissionType::CREATE->label();       // "Create"
PermissionType::READ->label();         // "Read"
PermissionType::WRITE->label();        // "Write"
PermissionType::UPDATE->label();       // "Update"
PermissionType::DELETE->label();       // "Delete"
PermissionType::VIEW_ANY->label();     // "View any"
PermissionType::VIEW->label();         // "View"
PermissionType::RESTORE->label();      // "Restore"
PermissionType::FORCE_DELETE->label(); // "Force delete"
PermissionType::MANAGE->label();       // "Manage"

    //  Good
    User::whereHas('roles', fn ($q) => $q->where('name', 'admin'))->get();

    //  Less efficient
    User::all()->filter(fn ($u) => $u->hasRole('admin'));
    

    User::with(['roles', 'roles.permissions'])->get();
    

bash
php artisan vendor:publish --tag="guard-migrations"
php artisan migrate

bash
php artisan guard:create-role admin Administrator
php artisan guard:create-permission users.create "Create Users"

bash
php artisan vendor:publish --tag="guard-migrations"
php artisan migrate

bash
php artisan vendor:publish --tag="guard-config"

bash
php artisan guard:create-role admin Administrator

# Optionally assign it to a user by ID, email, or name
php artisan guard:create-role moderator "Moderator" 1
php artisan guard:create-role moderator "Moderator" [email protected]
php artisan guard:create-role moderator "Moderator" "Jane Doe"

bash
php artisan guard:upgrade

bash
composer dump-autoload

bash
php artisan config:clear