Bouncer Role and Ability Management

Bouncer supports multi-tenant applications by scoping roles and abilities to a specific tenant.

1. Publish the scope middleware:

php artisan vendor:publish --tag="bouncer.middleware"

2. Configure the middleware: Edit the published middleware (typically app/Http/Middleware/ScopeBouncer.php) to define how the tenant ID is retrieved from the request:

public function handle($request, Closure $next)
{
    $tenantId = $request->user()->account_id;

    Bouncer::scope()->to($tenantId);

    return $next($request);
}

3. Register the middleware in your app/Http/Kernel.php within the web middleware group:

protected $middlewareGroups = [
    'web' => [
        // ...
        \App\Http\Middleware\ScopeBouncer::class,
    ]
];

Bouncer allows you to create roles and abilities on the fly. Simply pass the name of the role or ability to Bouncer::allow(), and Bouncer will create the underlying models if they do not exist.

To add extra attributes (like a title), use the role() and ability() methods to manually create the models first.

Note: These examples use the Bouncer facade. If you do not use facades, inject an instance of Silber\Bouncer\Bouncer into your class.

// Simple creation
Bouncer::allow('admin')->to('ban-users');

// Creation with additional attributes
$admin = Bouncer::role()->firstOrCreate([
    'name' => 'admin',
    'title' => 'Administrator',
]);

$ban = Bouncer::ability()->firstOrCreate([
    'name' => 'ban-users',
    'title' => 'Ban users',
]);

Bouncer::allow($admin)->to($ban);

Bouncer caches queries for the current request. If cross-request caching is enabled, you can refresh the cache manually.

• Bouncer::refresh();: Fully refreshes the entire cache. Uses cache tags if available.
• Bouncer::refreshFor($user);: Refreshes the cache only for a specific user.

Note on Multi-tenancy: When using multi-tenancy, refreshFor($user) only refreshes the cache within the current scope's context.

You can assign roles to a user using the Bouncer facade or directly on the user model. To remove a role, use the retract method.

Via Facade:

• Bouncer::assign('role-name')->to($user);
• Bouncer::retract('role-name')->from($user);

Via User Model:

• $user->assign('role-name');
• $user->retract('role-name');

// Assigning
Bouncer::assign('admin')->to($user);
$user->assign('admin');

// Retracting
Bouncer::retract('admin')->from($user);
$user->retract('admin');

Bouncer integrates directly with Laravel's Gate. You can use the Bouncer facade for convenience or use the standard $user->can() method on the user model.

Via Bouncer Facade:

• Bouncer::can($ability, $model = null);
• Bouncer::canAny($abilities, $model = null);
• Bouncer::cannot($ability, $model = null);
• Bouncer::authorize($ability, $model = null);

Via User Model:

• $user->can($ability, $model = null);

In Blade Templates: Use the standard Laravel @can directive:

@can('update', $post)
    <!-- Content -->
@endcan

// Facade passthroughs
Bouncer::can($ability);
Bouncer::can($ability, $model);
Bouncer::canAny($abilities);
Bouncer::canAny($abilities, $model);
Bouncer::cannot($ability);
Bouncer::cannot($ability, $model);
Bouncer::authorize($ability);
Bouncer::authorize($ability, $model);

// User model
$user->can($ability, $model);

Abilities can be granted directly to a user without a role. You can also remove specific abilities using disallow.

Granting:

• Bouncer::allow($user)->to('ability-name');
• $user->allow('ability-name');

Removing:

• Bouncer::disallow($user)->to('ability-name');
• $user->disallow('ability-name');

Important Notes:

• If a user has a role that grants an ability, disallow on the user will not stop them from having that ability. You must instead disallow the ability from the role: Bouncer::disallow('role-name')->to('ability-name');.
• To remove an ability for a specific model type, pass the class name: Bouncer::disallow($user)->to('delete', Post::class);.
• To remove an ability for a specific model instance, pass the instance: Bouncer::disallow($user)->to('delete', $post); (Note: this will not remove a model-type level disallow).

You can use Eloquent-style queries to find users based on their assigned roles.

• User::whereIs('role-name')->get(); (Find users with a specific role)
• User::whereIs('role1', 'role2')->get(); (Find users with ANY of the given roles)
• User::whereIsAll('role1', 'role2')->get(); (Find users with ALL of the given roles)

You can retrieve a user's roles or abilities directly from the user model.

• $user->getRoles();: Returns a collection of the user's roles.
• $user->getAbilities();: Returns a collection of all allowed abilities (including those from roles).
• $user->getForbiddenAbilities();: Returns a collection of abilities explicitly forbidden for the user.

$roles = $user->getRoles();
$abilities = $user->getAbilities();
$forbiddenAbilities = $user->getForbiddenAbilities();

To integrate Bouncer into a Laravel application, follow these steps:

1. Install the package via Composer:

   composer require silber/bouncer

2. Add the HasRolesAndAbilities trait to your User model:

   use Silber\Bouncer\Database\HasRolesAndAbilities;
   
   class User extends Model
   {
       use HasRolesAndAbilities;
   }

3. Publish the Bouncer migrations:

   php artisan vendor:publish --tag="bouncer.migrations"

4. Run the migrations:

   php artisan migrate

When using the Bouncer facade, ensure you import it at the top of your file:

use Bouncer;