Checking API

Reference for Warrant\HasWarrantSchema. Conceptual coverage is in Checking access.

Setup

use Warrant\HasWarrantSchema;

class Document extends Model
{
    use HasWarrantSchema;

    abstract public function warrantSchema(): string; // return the schema class-string
}

The returned schema’s const model must equal this model’s class, or Warrant throws LogicException (Schema [...] must manage model [...]).

Static helpers

public static function userHasAbilities(
    string|array $abilities,
    Model|string|null $target = null,
    ?Authenticatable $user = null,
    AbilityMatchMode $matchMode = AbilityMatchMode::ALL,
    array $context = [],
): bool;

public static function getUserAbilities(
    Model|string|null $target = null,
    ?Authenticatable $user = null,
    array $context = [],
): array;

public static function authorize(
    string|array $abilities,
    Model|string|null $target = null,
    ?Authenticatable $user = null,
    AbilityMatchMode $matchMode = AbilityMatchMode::ALL,
    array $context = [],
): void;

authorize() is the throwing sibling of userHasAbilities() — same signature, but returns void and throws WarrantAuthorizationException (rendered as HTTP 403 by Laravel) on denial. The exception carries a diagnosed denial context so you can attach a custom explanation — see Denial messages.

Instance methods

public function hasAbility(
    string|array $abilities,
    ?Authenticatable $user = null,
    AbilityMatchMode $matchMode = AbilityMatchMode::ALL,
    array $context = [],
): bool; // one targeted EXISTS query on $this

public function loadAbilities(
    ?Authenticatable $user = null,
    string $selectedAbilitiesKey = 'abilities',
    array $context = [],
): array; // computes, then setAttribute() on the instance

Query scopes

// ->hasAbility(...)
public function scopeHasAbility(
    EloquentBuilder $query,
    string|array $abilities,
    ?Authenticatable $user = null,
    AbilityMatchMode $matchMode = AbilityMatchMode::ALL,
    array $context = [],
): EloquentBuilder;

// ->selectAbilities(...)
public function scopeSelectAbilities(
    EloquentBuilder $query,
    ?Authenticatable $user = null,
    string $selectedAbilitiesKey = 'abilities',
    ?array $onlyAbilities = null,
    array $context = [],
): EloquentBuilder;

• $user defaults to auth()->user(); scopes throw LogicException if no user is available.
• hasAbility([]) (empty ability list) leaves the query unchanged.
• selectAbilities targets rows via getQualifiedKeyName(). Its JSON column is in ability declaration order and requires a supported DB driver.

The global scope

Warrant\SelectAbilitiesScope implements Illuminate\Database\Eloquent\Scope. Its apply() no-ops when there’s no authenticated user or the model lacks a warrantSchema() method; otherwise it calls selectAbilities($currentUser).

Note

The trait does not register this scope automatically. Attach it yourself (e.g. in the model’s booted()) if you want the abilities column on every query.

Match modes

Warrant\AbilityMatchMode::ALL; // default on trait helpers/scopes
Warrant\AbilityMatchMode::ANY;

The lower-level getAbilitiesWithoutTarget() (on the schema) defaults to ANY — the one exception to the ALL default.

Reachability

Reachability answers “could this user ever have this ability, given the shape of the rules?” — a purely structural analysis of the resolved rule set. It evaluates no conditions and runs no SQL. Conceptual coverage is in Reachability.

public static function abilityReachability(
    string $ability,
    ?Authenticatable $user = null,
): Reachability;

public static function userCouldEverHave(
    string|array $abilities,
    ?Authenticatable $user = null,
    AbilityMatchMode $matchMode = AbilityMatchMode::ALL,
): bool; // reachability !== NEVER

public static function userAlwaysHas(
    string|array $abilities,
    ?Authenticatable $user = null,
    AbilityMatchMode $matchMode = AbilityMatchMode::ALL,
): bool; // reachability === ALWAYS

public static function userNeverHas(
    string|array $abilities,
    ?Authenticatable $user = null,
    AbilityMatchMode $matchMode = AbilityMatchMode::ALL,
): bool; // reachability === NEVER

public static function getUserPossibleAbilities(?Authenticatable $user = null): array;   // reachability !== NEVER
public static function getUserGuaranteedAbilities(?Authenticatable $user = null): array; // === ALWAYS
public static function getUserImpossibleAbilities(?Authenticatable $user = null): array;  // === NEVER

Warrant\Reachability is a pure enum with cases NEVER, MAYBE, ALWAYS. See Schema API for the enum and the per-ability decision table.

No context: argument — but a user is still required

No reachability API takes a context: array; conditions are never evaluated, so context is irrelevant. A $user is still required (defaulting to auth()->user()) because the resolver may return a different rule set per user.

Lower-level instance methods

Defined on the schema instance; the static helpers above are thin wrappers over these.

public function reachabilityOf(Authenticatable $user, string $ability): Reachability;
public function reachabilityMap(Authenticatable $user, ?array $abilities = null): array;
public function reachabilitySatisfies(
    Authenticatable $user,
    string|array $abilities,
    callable $passes,
    AbilityMatchMode $matchMode,
): bool;
public function abilitiesWhereReachability(Authenticatable $user, callable $predicate): array;