Getting Started

This package is an authorization layer, not an authentication one. The fastest path to value is to wire it into Laravel's existing Gate/Policy system and then stop calling permission tables directly from controllers.

Install and let Laravel discover the provider:

composer require patrickhanna/laravel-warden

Publish and run the package assets:
```
php artisan vendor:publish --provider="PatrickHanna\\Warden\\WardenServiceProvider"
php artisan migrate
```
Verify the provider class name in vendor/patrickhanna/laravel-warden/composer.json before running this; the repository name (laravel-warrant) and package name (laravel-warden) differ, so the namespace may not match the package slug.

Add the package trait to your User model (check the README or src/ for the exact trait name):

use PatrickHanna\Warden\Traits\HasWarrant;

class User extends Authenticatable
{
    use HasWarrant;
}

Seed a role and a permission, attach them, and verify with Tinker:

$role = WarrantRole::create(['name' => 'editor']);
$role->givePermission('posts.update');

$user->assignRole('editor');

$user->can('posts.update'); // should be true

First real use case: protect a resource route with a policy or a can: middleware:

Route::put('/posts/{post}', [PostController::class, 'update'])
    ->middleware('can:update,post');

Where to look first:

The service provider: it shows how the package hooks into Gate, whether it registers a Gate::before, and what facade/trait names are real.
The published config: it usually defines model class overrides, cache settings, and table names.
The migrations: they reveal the schema (roles, permissions, pivot tables, and any tenant/scope columns) and therefore what "database-scoped" actually means in this package.
The trait: it shows the public API (assignRole, givePermission, hasPermission, etc.) that you will use daily.

If the package does not register itself with Laravel's Gate, use its facade directly in policies rather than scattering calls through controllers. Integrating once at the policy layer keeps the rest of the app framework-idiomatic.

Implementation Patterns

Policy-first, permission-second

Keep business rules in policies and use the package only to answer "does this user hold this ability for this scope?" This preserves Laravel's authorize(), can(), Blade @can, and form-request conventions while letting permissions be data-driven.

class PostPolicy
{
    public function update(User $user, Post $post): bool
    {
        if ($user->id === $post->user_id) {
            return true;
        }

        return $user->hasPermission('posts.update', $post);
    }
}

Passing the model instance is the important part. String-only checks ($user->can('posts.update')) test global permission; model-aware checks test the database-scoped ability the package advertises.

Route and controller integration

Prefer middleware and form requests over inline checks:

Route::middleware('can:update,post')->put('/posts/{post}', ...);

public function authorize(): bool
{
    return $this->user()->can('update', $this->route('post'));
}

This keeps authorization consistent across HTTP, API, and console entry points.

Role vs direct permission assignment

Use roles for job functions (editor, moderator, billing) and direct permissions only for one-off exceptions. Seeding is the main place this matters:

$role = Role::firstOrCreate(['name' => 'editor']);
$role->syncPermissions(['posts.create', 'posts.update']);

$user->assignRole('editor');

Make seeders idempotent with firstOrCreate/syncPermissions; otherwise repeated deploys create duplicate pivots or fail on unique constraints.

Database-scoped checks

The key workflow is "can this user do X to this specific record?" Keep a consistent call shape across the codebase:

$user->can('update', $post);
$user->can('delete', $comment);

If the package exposes a scope/tenant concept, resolve the tenant before the check and cache the resolved permission set per request. Avoid resolving scopes inside loops.

Blade and API responses

Use the framework directives so the package's Gate integration does the work:

@can('update', $post)
    <a href="{{ route('posts.edit', $post) }}">Edit</a>
@endcan

For APIs, expose abilities explicitly rather than leaking the permission schema:

'can' => [
    'update' => $request->user()->can('update', $post),
    'delete' => $request->user()->can('delete', $post),
],

Testing

Because the package integrates with Gate, tests stay familiar:

$this->actingAs($editor)
    ->put("/posts/{$post->id}")
    ->assertOk();

Test the negative path too: a user with posts.update globally but not for another tenant's post should receive 403. That is the check most likely to regress.

Gotchas and Tips

Maturity risk. With 14 stars and zero dependents, treat this as a small, low-traffic package. Pin the exact version in composer.json, read src/ before adopting, and keep an exit path. If the package is abandoned, your policies should still be the place where authorization logic lives so you can swap the permission backend.
Naming drift. The package is laravel-warden but the repository is laravel-warrant. Provider namespaces, facade names, config keys, and trait names may not match the README. Confirm them in composer.json and src/ before copying examples.
Global bypasses. If the package registers a Gate::before for super-admins, it can silently bypass database-scoped checks. Search the service provider for Gate::before and Gate::after; if present, make the bypass explicit and test it.
Stale permission cache. Permission packages commonly cache role/permission lookups. After changing roles in a seeder, admin panel, or queue job, clear the package cache or call its documented refresh method. Otherwise tests pass locally and production behaves inconsistently.
N+1 queries. Loading permissions per model inside a collection can explode query count. Eager-load roles/permissions where the package supports it, and memoize the permission set on the user instance for the request.
Policy discovery. Model-aware checks rely on Laravel finding PostPolicy for Post. If you use non-standard namespaces, register policies explicitly in AuthServiceProvider; otherwise can('update', $post) may fall through to a global ability check and return the wrong result.
Middleware order. auth must run before can: middleware. A can: route on a guest produces a confusing 403 rather than a redirect to login.
String vs model checks. $user->can('posts.update') and $user->can('posts.update', $post) are not interchangeable. Standardize on the model-aware form anywhere a record is involved.
Schema portability. If the migrations use JSON columns for scoped permissions, verify behavior on your target database (MySQL 5.7+, PostgreSQL, SQLite). JSON query differences are a common source of "works locally, fails in CI" bugs.
Extension points. The published config usually allows swapping the role/permission models and table names. Prefer config overrides and custom policies over forking the package; a fork of a 14-star package is hard to maintain.
Debugging. When a check unexpectedly fails, log Gate::forUser($user)->inspect('update', $post) to see which policy or ability resolved the result, then compare against the package's stored permissions for that user and scope.

Laravel Warden Laravel Package