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

Within a request, a queued job or a console command, the package keeps what it decided, so that an `allowed()` that queries runs once per reader, ability and [decision context](/essentials/readers#the-decision-context), not once per row. The [Readers](/essentials/readers#kept-decisions) page gives the essentials; this page gives the details.

## What is kept

Two kinds of answers, each capped at 10,000 entries, the oldest dropped first:

- **The perimeters a reader reaches**, under the reader (its morph class, connection and key), the decision context, the control and the ability: what every `allowed()` callback and `allows()` hook answered, what the boundary's `admits()` answered, the level reached in each group, and, for a `ThroughParent`, the perimeters the reader reaches on the parent, kept the same way under the parent's control.
- **The SQL check of each row**, under the reader, the decision context, the model, the key of the row and the ability. The [batched decisions](/digging-deeper/batched-decisions) fill it too.

The policy, `controlled()`, `controlledFor()`, the batches, the search filter and `applicablePerimeters()` read the same kept perimeters, so they always agree within a request. The in-memory checks, `should()`, `includes()` and the in-memory form of the boundary, run on every decision, on the row as stored.

A reader without a key, or not saved, is never kept: its perimeters are evaluated again on every decision.

## What forgets them

Everything kept is forgotten at once:

- after any SQL statement that is not a read, on any connection;
- when a transaction rolls back;
- once Laravel has handled a request, so two requests of one test share nothing;
- at the end of each queued job;
- when the application calls `Access::forgetDecisions()`.

A **read** is a single statement that starts with `select` or `show`, after spaces and opening parentheses. Every other statement forgets: Eloquent saves and deletes, with or without events (`saveQuietly()`, `withoutEvents()`, and `Event::fake()` on a connection opened before it), mass updates and deletes, `attach()`, `detach()` and `sync()`, `DB::table()`, `DB::statement()` and `DB::unprepared()`. So do the statements that might write without starting with a write: `with`, `explain`, `pragma`, `call`, `set`, a statement that starts with a comment, the schema statements, and a `select` followed by `;` and another statement.

## Laravel's own tables

The writes that Laravel makes to its own tables do not forget, so a cache entry, a lock, the rate limiter, a session or a queued job costs no query in production, where these drivers write to the database:

- the `table` of each cache store whose driver is `database`, and its `lock_table` (`cache_locks` when unset);
- `session.table`, when `session.driver` is `database`;
- the `table` of each queue connection whose driver is `database`;
- `queue.failed.table`, when its driver is `database` or `database-uuids`;
- `queue.batching.table` (`job_batches` when unset), unless batching uses DynamoDB.

The package reads them from the configuration, each on the connection it names, the default one when it is `null`. A write is one of them only when it is a single `insert`, upsert, `update` that reads no other table, `delete` or SQL Server `merge` on one of these tables, quoted the way the query builder quotes it.

- An application table with the name and the connection of one of them, such as a `Job` model on the `jobs` table that `config/queue.php` declares, never forgets: give it another name or connection.
- The list cannot be extended. Write a log of each row after the response (`defer()`, `dispatch()->afterResponse()`), not while the page renders: each write would forget the batched decisions of the page.

## Calling `forgetDecisions()`

Call `Access::forgetDecisions()` when a decision changes without a write through a Laravel connection:

- a write through another PDO handle, or a database client outside Laravel;
- a write by another process, such as a queue worker, a scheduled command or another application, that the current request or job must see;
- a write hidden in a statement read as a `select`, such as a function that writes, or `select ... into` in PostgreSQL and SQL Server;
- a permission changed without any write, such as a `Gate::define()` in a test.

A statement that fails after writing part of its rows does not forget. An attribute of the reader changed in memory, without saving it, does not change what was kept either.

### Long console commands

A console command keeps its decisions for its whole run, and never sees a permission revoked by another process. Call `Access::forgetDecisions()` at the start of each unit of work:

```php
foreach (Tenant::all() as $tenant) {
    Access::forgetDecisions();

    // ...
}
```

The same goes for a right on a period: an `allowed()` that compares with `now()`, and the SQL check of a row through a `query()` that does, keep the answer of the instant they ran. The lists still run `query()` at each call, and the searches compute the reader keys at each call.

### Jobs

A queue worker starts each job with no kept decision. A job run with the `sync` connection or `dispatchSync()` shares the kept decisions of the request that runs it.

## The decision context

Everything that `allowed()` reads besides the reader belongs in the [decision context](/essentials/readers#the-decision-context): the current team of a permission package, a tenant or a guard set during the request. A value that changes without being in it reuses the answer given for the previous value until the next flush.

laravel-rest-api files the decisions that `authorizationCache()` keeps under the same context: see [laravel-rest-api](/integrations/laravel-rest-api#kept-decisions).
