Readers
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.
| Where | Reader |
|---|---|
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,objectormixedaccepts 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()andDB::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:
- the batched decisions,
Access::preload()andreachableKeys(), next towithAbilities(); - the writes of Laravel's own tables, such as the cache, the sessions and the queues, which do not forget the kept decisions;
- lists that span several brands, and a parent decided in the context of the child row.
Queries
controlled(), controlledFor() and uncontrolled() filter your Eloquent queries in SQL with the control of the model. A query is controlled only when it says so.
Search overview
A controlled Laravel Scout search keeps, in one engine query, the documents the reader may view: each document carries the keys that open it.