Checking access

Once schema, resolver, and rules are in place, you never touch the compiler directly. You ask questions through the model, query scopes, static helpers, or middleware.

Set up the model

Add the HasWarrantSchema trait and point it at the schema:

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

class Document extends Model
{
    use HasWarrantSchema;

    public function warrantSchema(): string
    {
        return \App\Warrant\DocumentSchema::class;
    }
}

Caution

The schema’s const model must match the model that returns it. If Document::warrantSchema() returns a schema whose model is Invoice::class, Warrant throws Schema [...] must manage model [...].

Boolean checks

Run as a scoped EXISTS query — no records are loaded:

Document::userHasAbilities('update', $document);           // a model instance
Document::userHasAbilities('update', $documentId);         // a key
Document::userHasAbilities(['view', 'update'], $document); // several at once
Document::userHasAbilities('create');                       // no-target / capability

// Instance form (checks $this):
$document->hasAbility('update');

Each accepts an optional $user (defaults to auth()->user()) and, for userHasAbilities, an AbilityMatchMode.

Note

If no user is authenticated and none is passed, these throw “requires an authenticated user or an explicit user instance.” — a loud failure rather than a silent deny.

Filtering queries

The hasAbility scope restricts a query to the rows the user may act on — the “which records?” question, answered in SQL:

// Documents the current user can update:
Document::query()->hasAbility('update')->paginate();

// Rows they can BOTH view and approve:
Document::query()->hasAbility(['view', 'approve'], matchMode: AbilityMatchMode::ALL)->get();

// For a specific user:
Document::query()->hasAbility('delete', $user)->get();

Empty ability list is a no-op

hasAbility([]) leaves the query’s SQL unchanged rather than filtering everything out — handy when the ability list is computed and might be empty.

Per-row abilities

The selectAbilities scope attaches a computed abilities column — a JSON array of what the user can do to that row — so your UI renders controls without N extra checks:

$rows = Document::query()->selectAbilities()->get();

$rows->first()->abilities; // ['view', 'update']

The list is ordered by ability declaration order in the schema.

On a list endpoint you often only care about a subset (say, just update for an Edit button). Narrowing it is a real saving — the attached subquery grows one UNION ALL branch per ability:

Document::query()->selectAbilities(onlyAbilities: ['update'])->get();

You can also change the column name and attach abilities to an already-loaded model:

Document::query()->selectAbilities(selectedAbilitiesKey: 'perms')->get();

$document->loadAbilities();      // sets $document->abilities
$document->getUserAbilities($document); // ['view', 'update'] — static form

Driver support

The per-row column uses a database-native JSON aggregate, implemented for PostgreSQL, MySQL/MariaDB, and SQLite. Any other driver throws “Warrant ability selection does not support the […] database driver.”

The SelectAbilitiesScope is not auto-registered

Warrant provides Warrant\SelectAbilitiesScope as a global scope, but the trait does not attach it for you — add it yourself if you want the column applied globally. It safely no-ops when there’s no authenticated user (unauthenticated requests simply get no abilities column).

Match modes

When you check several abilities at once, AbilityMatchMode decides how they combine:

• AbilityMatchMode::ALL — the row/user must satisfy every listed ability.
• AbilityMatchMode::ANY — any one is enough.

use Warrant\AbilityMatchMode;

Document::query()->hasAbility(['view', 'approve'], matchMode: AbilityMatchMode::ANY)->get();

Default differs on getAbilitiesWithoutTarget

Most entry points default to ALL. The lower-level getAbilitiesWithoutTarget() defaults to ANY. If you call it directly, pass the match mode explicitly to avoid surprises.

Capability (no-target) checks

Not every check is about a row. “Can this user create documents?” or “can they access settings?” have no target. Pass null as the target (or omit it):

Document::userHasAbilities('create');   // target defaults to null
DocumentSchema::getUserAbilities();     // all no-target abilities

For section-level capabilities with no model at all, define a capability schema with const model = '' and only #[GlobalCondition] conditions. In a no-target check, targeted conditions are treated as false, so only global logic contributes.

Passing context

Every check API takes an optional context: array — values for any @context keys the rules reference. See Check-time context.

API summary

Call	Question
Model::userHasAbilities($abilities, $target, $user, $matchMode, $context)	Can they? (bool)
$model->hasAbility($abilities, $user, $matchMode, $context)	Can they, for this instance?
Model::getUserAbilities($target, $user, $context)	What can they do to this? (array)
->hasAbility(...) scope	Which rows?
->selectAbilities(...) scope	What per row?
$model->loadAbilities(...)	Attach abilities to an instance
Model::authorize($abilities, $target, $user, $matchMode, $context)	Can they? — throws a 403 with a message
Model::userCouldEverHave($abilities, $user, $matchMode)	Could they ever? (bool)

Full signatures are in the Checking API reference.

Two questions this guide doesn’t cover live on their own pages: when a denial should explain itself, authorize throws a 403 carrying the responsible rule’s message; and when you only need to know whether an ability is conceivable — to render a nav or gate a section without a query — reachability answers structurally, no SQL.