Batched decisions
A page that checks @can('update', $post) on each row runs one query per row and ability for the perimeters checked in SQL. Three tools decide many rows at once, and keep the answers for the request, so that can(), @can, authorize() and Gate::inspect() then answer without SQL.
| You have | Use |
|---|---|
| A query that loads the page | withAbilities() |
| Rows already loaded | Access::preload() |
| Rows already loaded, and you need the keys | reachableKeys() |
withAbilities()
$posts = Post::controlled()
->withAbilities(['view', 'update', 'delete'])
->paginate();
For each ability, the query selects one CASE that returns the verdict of the row: the boundary when it has no in-memory form, then the perimeters checked in SQL. The answers are kept under the reader chosen by controlledFor(), or the signed-in user for controlled(), and under the current decision context.
- It works with
get(),first(),paginate(),simplePaginate(),cursorPaginate(),chunk(),lazy(),cursor()and the eager loads of a controlled relation:
User::with(['posts' => fn ($posts) => $posts->controlled()->withAbilities(['update'])])->get();
- It comes after
controlled()orcontrolledFor(), or throwsMissingControlledReaderException. - The abilities are names or
Abilityobjects. A name goes throughabilityFor(), and one the control cannot map throwsInvalidAbilityException. controlled()does not decideviewby itself: Laravel only groups the conditions of the scope, so anorWhere()added after it could bring rows from outside the perimeters. Listviewwhen the page checks it.- Select the columns with
select(): the columns passed toget()are ignored oncewithAbilities()adds its own. - The extra columns use reserved aliases and are removed from every model right after the query: they never show in
getAttributes(),toArray()or the JSON.
To page through the rows a reader may act on, list them with controlledFor($user, 'update'), then decide the other abilities on the same rows:
$editable = Post::controlledFor($user, 'update')
->withAbilities(['view', 'delete'])
->paginate();
Preloading loaded rows
use Lomkit\Access\Ability;
use Lomkit\Access\Access;
Access::preload($user, 'update', $posts);
Access::preload($user, Ability::delete(), $posts);
Access::preload($reader, $ability, $rows) runs one query per ability and per model, in chunks of 1,000 keys, and keeps the answers the same way.
- The rows can belong to several controlled models.
- Unsaved rows are skipped, since they are refused as
unsavedwithout SQL. - A reader without a key, or not saved, is never kept, so preloading for it runs no query.
The laravel-rest-api extension preloads the row checks of each page this way.
reachableKeys()
use Lomkit\Access\Ability;
use Lomkit\Access\Access;
$editable = Access::controlFor(Post::class)->reachableKeys($user, Ability::update(), $posts);
reachableKeys() returns, in one query, the keys of the rows the reader may act on, in the order of $rows. Use it to filter rows that are already loaded, such as the results of a search, which always finds the rows the reader may view.
What a batch holds
A batch holds only what the SQL decides, under the perimeters kept for the reader. The in-memory checks still run on every decision, on the row as stored: the in-memory form of the boundary, and the perimeters with a should() callback or an includes() hook. A perimeter checked in memory can grant a row that the batch answered outside_rows, so a batched answer is always the answer of the row-by-row decision. assertControlAgrees() checks it on your test data.
With a boundary that has no in-memory form, withAbilities(['view', ...]) or a preload of view also gives the not_found answers of the other abilities without a query.
A batch is worth its query only while nothing forgets the kept decisions: a write for each row while the page renders, such as an access log, forgets them, and the next checks query again.
Kept decisions
What the package keeps within a request or a job, what forgets it, the writes of Laravel's own tables that do not, and when to call Access::forgetDecisions().
Row checks
How the policy checks one row, in memory or in one SQL query, and how a control or a perimeter tells which perimeters apply and which one grants a row.