# Readers

> The reader is the model a decision is made for. Learn about readers of several types, the decision context, and the decisions kept for a request.

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

<table>
<thead>
  <tr>
    <th>
      Where
    </th>
    
    <th>
      Reader
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        controlled()
      </code>
      
      , a Scout search's <code>
        controlled()
      </code>
    </td>
    
    <td>
      <code>
        Auth::user()
      </code>
      
      , or none for a guest
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        controlledFor($reader)
      </code>
    </td>
    
    <td>
      the model you pass, or none for <code>
        null
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        $user->can()
      </code>
      
      , <code>
        Gate::forUser($user)
      </code>
    </td>
    
    <td>
      that user
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        $this->authorize()
      </code>
      
      , <code>
        @can
      </code>
      
      , <code>
        Gate::allows()
      </code>
    </td>
    
    <td>
      the signed-in user
    </td>
  </tr>
</tbody>
</table>

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:

```php
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](/essentials/boundaries) 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`, `object` or `mixed` accepts 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:

```php
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()` and `DB::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](/digging-deeper/decisions#laravels-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](/digging-deeper/batched-decisions), `Access::preload()` and `reachableKeys()`, next to [`withAbilities()`](/essentials/queries#deciding-the-rows-of-a-page);
- [the writes of Laravel's own tables](/digging-deeper/decisions#laravels-own-tables), such as the cache, the sessions and the queues, which do not forget the kept decisions;
- [lists that span several brands](/digging-deeper/several-brands), and [a parent decided in the context of the child row](/digging-deeper/row-context).
