Row checks
How a row is checked
The policy checks a saved row in a fixed order:
- the in-memory form of the boundary:
Boundary::where(), or theincludes()hook of a boundary class; - the perimeters that check in memory: a
should()callback, anincludes()hook, orunrestricted(); - only when none of them grants, one SQL query on the row's key, constrained by the OR of the
query()of every other perimeter the reader reaches, with the boundary inside it when it has no in-memory form.
| The reader reaches | Queries for one row |
|---|---|
| No perimeter | None: no_perimeter |
| An unrestricted perimeter, with no boundary or a boundary with an in-memory form | None |
| A perimeter with an in-memory form that contains the row | None, or one on the boundary when it has no in-memory form |
| Only perimeters without an in-memory form | One, with the boundary in it when it has no in-memory form |
The mode never depends on the state of the moment, such as loaded relations, so a decision costs the same number of queries in tests and in production. The SQL check of each row is kept for the request, and the batched decisions decide many rows in one query.
A draft is not in the database: only the in-memory forms judge it, and a perimeter checked in SQL never grants it. See Drafts.
Which perimeters apply
Inside a control, the protected applicablePerimeters($reader, $ability) lists the perimeters that apply to a reader for an ability: the level reached in each group, then the loose perimeters that allow the reader, or an unrestricted perimeter alone.
use Illuminate\Database\Eloquent\Model;
use Lomkit\Access\Ability;
use Lomkit\Access\Perimeters\Perimeter;
class PostControl extends Control
{
public function grantingPerimeter(Model $reader, Post $post): ?Perimeter
{
foreach ($this->applicablePerimeters($reader, Ability::update()) as $perimeter) {
if ($perimeter->admits($reader, Ability::update(), $post)) {
return $perimeter;
}
}
return null;
}
}
- It reads the kept perimeters of the reader, so it agrees with the policy and the queries.
- It does not check the boundary against a row: the policy does.
applicablePerimeters()is final. Give the methods you add to a control distinctive names, since a minor release may add methods toControl.
Which perimeter grants a row
$perimeter->admits($reader, $ability, $row) tells whether a perimeter applies to the reader for the ability and contains the row:
- in memory, through its
should()callback or itsincludes()hook; - otherwise with one
existsquery on the stored row, through itsquery(); - never for an unsaved row, which only the in-memory checks judge.
$perimeter->checksInMemory() tells which of the two it uses, and checksInMemory() on a boundary tells whether the boundary has an in-memory form.
Never call the hooks of another perimeter, allows(), includes() or scope(), even though PHP lets a perimeter class do it: they skip the admission of the reader by the type of the callbacks and by the reader callback of the search keys. Call admits().
Batched decisions
Decide the rows of a page in one query with withAbilities(), preload decisions with Access::preload(), or get the keys a reader may act on with reachableKeys().
Several brands
List the rows of several brands, tenants or companies in one query with perimeters that read the brand of the row, and know when a parent needs the row's brand.