Essentials

Readers

The reader is the model a decision is made for. Learn about readers of several types, the decision context, and the decisions kept for a request.

Who is the reader

Every decision is made for a reader: the signed-in user for controlled() and the policy, or the model you name with controlledFor(). A reader is any Eloquent model: a User, an API client, a member of another guard.

WhereReader
controlled(), a Scout search's controlled()Auth::user(), or none for a guest
controlledFor($reader)the model you pass, or none for null
$user->can(), Gate::forUser($user)that user
$this->authorize(), @can, Gate::allows()the signed-in user

Without a reader, the controlled queries read no row. The perimeter callbacks receive the reader as their first parameter (allowed(), should()) or second (query()), and the hooks of a perimeter class read it with $context->reader().

Readers of several types

A control can serve several types of readers. A perimeter whose callbacks type the reader applies only to the readers of that type, and the others skip it:

protected function perimeters(): array
{
    return [
        OwnPerimeter::new()
            ->allowed(fn (User $user, Ability $ability) => $user->can("{$ability} own posts"))
            ->query(fn (Builder $query, User $user) => $query->where('author_id', $user->id)),
        ClientAppPerimeter::new()
            ->allowed(fn (ApiClient $client, Ability $ability) => $client->client_id !== null && $ability->is('view'))
            ->query(fn (Builder $query, ApiClient $client) => $query->where('client_id', $client->client_id)),
    ];
}

A User reaches only OwnPerimeter, an ApiClient only ClientAppPerimeter, and any other reader no perimeter, so no row. The same goes for a boundary declared with Boundary::where(): a reader whose type its closure does not accept is refused everything.

  • A class, a nullable class, an interface, a union or an intersection narrows the readers.
  • An untyped parameter, Model, object or mixed accepts every reader.
  • Type every callback of a perimeter with the same reader type: the perimeter is skipped when any of them refuses the reader.

The decision context

Some decisions depend on more than the reader: the current team of a permission package, the brand or the tenant that the request works in. Declare these values once, in the boot() method of a service provider:

use Lomkit\Access\Access;

public function boot(): void
{
    Access::decisionContextUsing(fn (): array => ['team' => Team::current()?->id]);
}
  • The resolver returns an array of strings, ints, booleans or nulls, keyed by name. Anything else, such as a model, throws InvalidDecisionContextException.
  • The hooks of a perimeter or boundary class read it with $context->decisionContext().
  • Without a resolver, the context is empty.

The package files the decisions it keeps under this context, so a decision made for one team is never reused for another. Everything allowed() reads besides the reader belongs in the decision context, such as the team that setPermissionsTeamId() sets, a tenant or a guard chosen during the request.

Kept decisions

Within a request, a queued job or a console command, the package keeps what it decided:

  • the perimeters a reader reaches: what each allowed() answered, and the level reached in each group, for each reader, ability and decision context;
  • the SQL check of each row, for each reader, decision context and ability.

So an allowed() that queries runs once per reader, ability and context, not once per row, and the policy, the controlled queries and the search filter share its answer: they always agree within a request. The in-memory checks, should() and the boundary, run on every decision.

Everything kept is forgotten at once:

  • after any SQL statement that is not a read, on any connection: Eloquent saves and deletes, mass updates, attach(), DB::table() and DB::statement() writes included, with or without model events. The writes of Laravel's own tables, such as the cache, the sessions and the queues, are the exception, see Laravel's own tables;
  • when a transaction rolls back, once a request is handled, and at the end of each job;
  • when you call Access::forgetDecisions().

A reader that is not saved, or has no key, is never kept: its perimeters are evaluated on every decision.

Call Access::forgetDecisions() yourself when a decision changes without a write through Laravel:

  • in a long console command, at the start of each unit of work, such as each tenant, since it never sees a permission revoked by another process;
  • in a test, after Gate::define() changes a permission between two checks.

The tests need no reset: each test starts with no kept decision.

What Digging deeper covers

These pages keep to what most applications need. The Digging deeper section covers the rest: