Most Laravel apps check permissions in two places. A policy decides whether a user can update a record, and a separate query scope decides which records appear on the list page. When someone changes one and forgets the other, users see rows they cannot open, or can’t see rows they are allowed to edit.

Laravel Warrant, a package by Patrick Hanna featured on Laravel News on 19 November 2026, tackles this by compiling authorization rules into SQL conditions. You write a rule once and use it to filter Eloquent queries, check a single model, and even return each row’s allowed abilities. This tutorial walks through a practical example: a timesheet screen where employees can view their own entries and edit them until they are locked.

Before you start: it’s a beta

Warrant is in beta and its API may change between releases. The maintainer recommends pinning an exact version and reading the changelog before upgrading. The package supports Laravel 11, 12 and 13 with PHP 8.2 or later (Laravel 13 itself needs PHP 8.3+).

composer require patrickhanna/laravel-warrant:4.12.3
php artisan vendor:publish --tag=warrant-config

For the example you need a timesheets table with a user_id column and a non-nullable boolean locked column.

How Warrant compares to what you already use

Option Best for
Native policies Rules written in plain PHP; list queries maintained separately
Spatie Laravel Permission Assigning permissions to users and roles
Bouncer Roles and abilities, including per-model grants
Laravel Warrant Record-level rules that must also filter queries and produce per-row abilities

You don’t have to throw away your role system. Laravel News points out that you could keep Spatie’s role assignments and write a Warrant rule provider that returns rules for those roles.

Step 1: Define a schema with conditions and rules

A Warrant schema declares the abilities for a model, the row conditions (as query constraints), and the rules that combine them. Create app/Warrant/TimesheetSchema.php:

<?php

namespace App\Warrant;

use App\Models\Timesheet;
use Illuminate\Contracts\Database\Query\Builder;
use Warrant\Rules\RuleProviderContext;
use Warrant\Schema\Abilities\Ability;
use Warrant\Schema\Conditions\Row\RowCondition;
use Warrant\Schema\Conditions\Row\RowConditionContext;
use Warrant\Schema\Types\Classes\ModelSchema;

class TimesheetSchema extends ModelSchema
{
    public const model = Timesheet::class;

    #[Ability] public const VIEW = 'view';
    #[Ability] public const UPDATE = 'update';

    #[RowCondition]
    public function isOwner(RowConditionContext $c): Builder
    {
        return $c->query->where(
            $c->column('user_id'),
            $c->user->getAuthIdentifier(),
        );
    }

    #[RowCondition]
    public function isLocked(RowConditionContext $c): Builder
    {
        return $c->query->where($c->column('locked'), true);
    }

    public function rules(RuleProviderContext $context): string
    {
        return <<<'WARRANT'
            if is_owner they can view, update
            if is_locked they cannot update
        WARRANT;
    }
}

A few things to notice:

  • The method names isOwner and isLocked become is_owner and is_locked in Warrant’s rule language.
  • $c->column() qualifies the column for the row being checked, which keeps things correct even when the query uses a table alias.
  • Denials override grants. An employee can view a locked timesheet they own, but cannot update it. Any declared ability without a matching grant is denied.

The rules here live in the schema, but an optional IRuleProvider can load them from the database or .warrant files instead. Warrant leaves storage and your role model up to you.

Step 2: Connect the model

Add the trait and point the model at its schema. The abilities cast will be used later when we select per-row abilities.

<?php

namespace App\Models;

use App\Warrant\TimesheetSchema;
use Illuminate\Database\Eloquent\Model;
use Warrant\HasWarrantSchema;

class Timesheet extends Model
{
    use HasWarrantSchema;

    protected $casts = ['abilities' => 'array'];

    public static function warrantSchema(): string
    {
        return TimesheetSchema::class;
    }
}

Then register the schema under a stable key in config/warrant.php:

'schemas' => [
    'timesheets' => App\Warrant\TimesheetSchema::class,
],

Step 3: Filter records in the database, before pagination

Now the payoff. To list only the timesheets the current user may update:

use App\Models\Timesheet;

$timesheets = Timesheet::query()
    ->userHasAbility('update')
    ->orderByDesc('id')
    ->paginate(20);

Because the rule is turned into SQL, the database removes rows the user can’t update before Laravel paginates. Compare that with filtering a collection after fetching a page: you could end up with 7 rows instead of 20, and a total count that includes records the user can’t access.

To run the same query on someone else’s behalf (say, a manager previewing an employee’s view), pass that user as the scope’s second argument.

Step 4: Show an edit button per row

List pages often need to know, row by row, whether to show an “Edit” button. Warrant can select the allowed abilities alongside each record:

$timesheets = Timesheet::query()
    ->userHasAbility('view')
    ->selectUserAbilities(onlyAbilities: ['update'])
    ->paginate(20);

foreach ($timesheets as $timesheet) {
    $canEdit = in_array('update', $timesheet->abilities, true);
}

Thanks to the array cast, abilities decodes to ['update'] or []. Ability selection works on PostgreSQL, MySQL/MariaDB and SQLite.

In Blade, that becomes:

@foreach ($timesheets as $timesheet)
    <tr>
        <td>{{ $timesheet->date }}</td>
        <td>{{ $timesheet->hours }}</td>
        <td>
            @if (in_array('update', $timesheet->abilities, true))
                <a href="{{ route('timesheets.edit', $timesheet) }}">Edit</a>
            @endif
        </td>
    </tr>
@endforeach

Step 5: Still authorize the action itself

Hiding a button never protects an endpoint. Always authorize the update before saving. Warrant’s Gate integration is enabled by default, so normal Laravel calls work:

use Illuminate\Http\Request;
use Illuminate\Support\Facades\Gate;
use App\Models\Timesheet;

public function update(Request $request, Timesheet $timesheet)
{
    Gate::authorize('update', $timesheet);

    $timesheet->update($request->validate([
        'hours' => ['required', 'numeric', 'min:0', 'max:24'],
    ]));

    return back();
}

You can also use $request->user()->can('update', $timesheet), Blade’s @can directives and the can: route middleware.

How it interacts with your policies

Warrant registers a Gate::before hook. When the model’s schema declares the ability being checked, Warrant answers and Laravel skips the matching policy method. Abilities the schema does not declare still go through normal policy handling. If you move an existing ability into Warrant, read the old policy method carefully and carry over any rule you still need, otherwise it will silently stop applying.

Performance and testing tips

  • Inspect the generated SQL against real data, especially when conditions query related tables.
  • Request only the abilities you need. Each selected ability adds a predicate per row, so ask for update alone if that’s all the screen uses.
  • Test both sides: which records each user can see, which they can change, and cases where a grant and a denial both match.

A simple feature test might look like this:

it('hides locked timesheets from the editable list', function () {
    $user = User::factory()->create();
    Timesheet::factory()->for($user)->create(['locked' => false]);
    Timesheet::factory()->for($user)->create(['locked' => true]);

    $this->actingAs($user);

    expect(Timesheet::query()->userHasAbility('update')->count())->toBe(1);
});

When to use it (and when not to)

Warrant shines when the same access rules must drive both list queries and single-record checks, like our timesheet screen. If a handful of PHP policy methods already cover your needs, adding another rule language may not be worth it.

Key takeaways

  • Laravel Warrant compiles authorization rules into SQL so policies and list queries stay in sync.
  • Filtering happens in the database before pagination, and you can return per-row abilities for UI buttons.
  • Gate integration means can(), @can and Gate::authorize() keep working.
  • It’s beta: pin an exact version and test carefully.

Read the full write-up on Laravel News and check the package documentation before adopting it.