Row context
A ThroughParent decides its parent under the decision context of the request. When the control of the parent reads several brands from that context, a child row can be opened by a parent readable only in another brand than its own: Several brands shows the case. decidedInRowContext() decides the parent, for each child row, within the value that the row holds. Replace "brand" with the dimension of your application.
Declaring the switch
Declare once, in the boot() method of a service provider and next to Access::decisionContextUsing(), the values that the request covers and how the application acts in one of them. Brands stands for the state of your application:
use Closure;
use Lomkit\Access\Access;
public function boot(): void
{
Access::decisionContextUsing(fn (): array => ['brands' => Brands::requested()->sort()->implode(',')]);
Access::rowContextUsing(
values: fn (): array => Brands::requested()->all(),
within: fn (int|string $brand, Closure $decide): mixed => Brands::actingIn([$brand], $decide),
);
}
public static function actingIn(array $brands, Closure $callback): mixed
{
$previous = self::$requested;
self::$requested = $brands;
try {
return $callback();
} finally {
self::$requested = $previous;
}
}
valuesreturns the values that the request covers, ints or non-empty strings, exactly as stored in the column of the child rows; an empty list reaches nothing. It must read the same state as the decision context.withinswitches the application to the single value it receives, every state that the parent reads included (the brands, the team of a permission package, a tenant), calls$decideexactly once, and restores the previous state in afinallyblock.- Keep both cheap: they run once per value for each list, and for the first row check of a reader, ability and context in a request.
- Only the PHP state is switched:
withinruns while the package builds the SQL, and the query runs after it returns. Keep out of the rules of the parent a state that the database reads, such as a session variable or a row-level security policy.
Then name, on the ThroughParent, the column of the child row that holds the value:
ThroughParent::belongsTo('post', inverse: 'comments')
->decidedInRowContext('brand_id'),
What it changes
The SQL gets one branch per value of the request, each built while within() runs for its value:
where (
(comments.brand_id = 'A' and exists (select * from posts where posts.id = comments.post_id and (<PostControl within A>)))
or (comments.brand_id = 'B' and exists (select * from posts where posts.id = comments.post_id and (<PostControl within B>)))
)
- A child row whose value is
null, or not one ofvalues, has no branch: theThroughParentrefuses it. Reach such rows through another perimeter. - The policy, the row checks,
withAbilities(),Access::preload()andreachableKeys()use the same branches. - A decision without a row is granted when there is a value of the request in which the
allowed()of theThroughParentaccepts and the parent reaches a perimeter. - A draft reads the column from its attributes, like the foreign key.
- The decisions on the parent are kept under the context of each value, the same key as a request of that value alone.
access:checkprintsrow context brand_idon the line of theThroughParent, and--jsongivesparent.row_context.
Each row gets the answer of its own value alone. That narrows the wide answer only when the rules of the parent grow with the brands: each rule that reads the brands filters the rows by them, and each allowed() that reads them accepts as soon as the reader holds the right in one of them. A rule that grants more for fewer brands would open, within one value, a parent that the whole request does not open. No assertion checks it.
Searching through the parent
A searchable child whose ThroughParent is decidedInRowContext('brand_id') writes the value of the child row after the relation: through.post.in.1.2.workspace_id.1.author.7 for a comment of brand 1. A child without a value carries no key through that parent. The reader gets, for each value of the request where the allowed() of the ThroughParent accepts, the keys of the parent computed within that value. See Searching through a parent.
Errors
| Mistake | Exception |
|---|---|
decidedInRowContext() without Access::rowContextUsing() | MissingRowContextException, when the control is built |
values returns something else than a list of ints and non-empty strings | InvalidRowContextValuesException |
within does not call $decide exactly once, leaves the decision context changed, decides under the context of the whole request or of another value, or switches two values to the same context | RowContextSwitchException |
| The column is not a plain column name | InvalidRowContextColumnException |
decidedInRowContext() twice on one ThroughParent | DuplicatePerimeterCallbackException |
The ThroughParent is a level of Levels::of() | RowContextInLevelsException: declare it next to the group |
Testing the switch
assertRowContextAgrees() compares each row with a request of its value alone, which the test sets up itself through alone, without the within closure under test:
public function test_the_brand_switch_is_complete(): void
{
foreach ([$this->headquarters, $this->brandManager] as $reader) {
$this->assertRowContextAgrees(
CommentControl::class,
$reader,
Comment::uncontrolled()->get(),
alone: fn (int|string $brand, Closure $check): mixed => $this->asBrandRequest($brand, $check),
);
}
}
alonereceives a value and a callback, sets up every state of a real request of that value alone, calls the callback and restores the state.asBrandRequest()stands for that helper of your tests.- For each row whose value is one of the request, the assertion compares the answer under the request with the answer inside
alone, through the Gate and throughcontrolledFor(), forview,updateanddeleteby default (pass others asabilities). - It catches a
withinthat forgets a state the parent reads, and a perimeter or boundary of the child that reads the brands of the request instead of the brand of the row. It does not check that the rules of the parent grow with the brands. - The control declares exactly one column with
decidedInRowContext(), and at least one row holds a value of the request.
Several brands
List the rows of several brands, tenants or companies in one query with perimeters that read the brand of the row, and know when a parent needs the row's brand.
What is public in 1.x
The releases of 1.x follow semantic versioning for what this documentation describes. Learn what that covers, and what may change in any release.