# 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.

<table>
<thead>
  <tr>
    <th>
      The reader reaches
    </th>
    
    <th>
      Queries for one row
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      No perimeter
    </td>
    
    <td>
      None: <code>
        no_perimeter
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      An unrestricted perimeter, with no boundary or a boundary with an in-memory form
    </td>
    
    <td>
      None
    </td>
  </tr>
  
  <tr>
    <td>
      A perimeter with an in-memory form that contains the row
    </td>
    
    <td>
      None, or one on the boundary when it has no in-memory form
    </td>
  </tr>
  
  <tr>
    <td>
      Only perimeters without an in-memory form
    </td>
    
    <td>
      One, with the boundary in it when it has no in-memory form
    </td>
  </tr>
</tbody>
</table>

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](/digging-deeper/decisions) for the request, and the [batched decisions](/digging-deeper/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](/essentials/policies#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.

```php
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](/digging-deeper/decisions#what-is-kept) 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()`.
