Kept decisions
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, not once per row. The Readers 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 andallows()hook answered, what the boundary'sadmits()answered, the level reached in each group, and, for aThroughParent, 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 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
tableof each cache store whose driver isdatabase, and itslock_table(cache_lockswhen unset); session.table, whensession.driverisdatabase;- the
tableof each queue connection whose driver isdatabase; queue.failed.table, when its driver isdatabaseordatabase-uuids;queue.batching.table(job_batcheswhen 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
Jobmodel on thejobstable thatconfig/queue.phpdeclares, 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, orselect ... intoin 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:
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: 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.
Abilities
The Ability value object names what a reader wants to do: how a policy method maps to an ability, how to change the mapping, and how business abilities work.
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().