Digging Deeper

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.

How a row is checked

The policy checks a saved row in a fixed order:

  1. the in-memory form of the boundary: Boundary::where(), or the includes() hook of a boundary class;
  2. the perimeters that check in memory: a should() callback, an includes() hook, or unrestricted();
  3. 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 reachesQueries for one row
No perimeterNone: no_perimeter
An unrestricted perimeter, with no boundary or a boundary with an in-memory formNone
A perimeter with an in-memory form that contains the rowNone, or one on the boundary when it has no in-memory form
Only perimeters without an in-memory formOne, 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 to Control.

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 its includes() hook;
  • otherwise with one exists query on the stored row, through its query();
  • 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().