Several brands
A decision runs under one decision context: the one the resolver returns when the decision is made. This page covers the lists that span several brands, companies or tenants in one query. Replace "brand" with the dimension of your application.
The brand is a value of the row
Do not build such a list by switching the decision context between controlledFor() calls joined with orWhere(). Only the list would follow each branch: withAbilities(), the policy, the kept decisions, Access::preload() and the row checks of laravel-rest-api run under the context in force, not under the brand of each row. A post of brand B listed through the rights of brand B would be decided for update with the rights of brand A, and kept so.
When one list spans several brands, the brand is a value of the row, not of the request. Write perimeters that read the brand of the row and filter by the brands where the reader holds the right:
protected function perimeters(): array
{
return [
BrandPerimeter::new()
->allowed(fn (User $user, Ability $ability): bool => $user->brandsWhere("{$ability} brand posts") !== [])
->should(fn (User $user, Post $post, Ability $ability): bool => in_array($post->brand_id, $user->brandsWhere("{$ability} brand posts"), true))
->query(function (Builder $query, User $user, Ability $ability): void {
$query->whereIn('brand_id', $user->brandsWhere("{$ability} brand posts"));
}),
OwnPerimeter::new()
->allowed(fn (User $user, Ability $ability): bool => $user->brandsWhere("{$ability} own posts") !== [])
->should(fn (User $user, Post $post, Ability $ability): bool => $post->author_id === $user->id && in_array($post->brand_id, $user->brandsWhere("{$ability} own posts"), true))
->query(function (Builder $query, User $user, Ability $ability): void {
$query->whereBelongsTo($user, 'author')->whereIn('brand_id', $user->brandsWhere("{$ability} own posts"));
}),
];
}
brandsWhere() stands for a method of your application that returns the brands where the user holds a permission. Post::controlled() then lists the posts of every brand of the reader in one query, and the policy, withAbilities() and Access::preload() decide each row from its own brand, whatever the current one.
- Keep these perimeters out of
Levels::of(). A group applies only the highest level the reader reaches, in any brand: a reader who sees every post of brand A and only their own posts of brand B would lose their posts of brand B. Loose perimeters add up, each filtered by its own brands. - Keep the brand out of the boundary.
Boundary::where()holds one value per reader, so a boundary that reads the current brand cuts the list to that brand. Keep in the boundary what is the same for every row the reader may reach, such as the tenant. - Check the result with
assertControlAgrees()on posts of several brands.
One level per brand
The loose perimeters already give each brand its own level: in each brand, their union is the highest level the reader reaches there. Never wrap a group, or its levels, in a perimeter that picks the level brand by brand: the package reads only what each perimeter of the list declares.
To keep what a group saves, the lower levels left out of the SQL, filter each lower level by the brands where no higher level applies:
OwnPerimeter::new()
->allowed(fn (User $user, Ability $ability): bool => $user->brandsOnlyWhere("{$ability} own posts", above: ["{$ability} brand posts"]) !== [])
->should(fn (User $user, Post $post, Ability $ability): bool => $post->author_id === $user->id && in_array($post->brand_id, $user->brandsOnlyWhere("{$ability} own posts", above: ["{$ability} brand posts"]), true))
->query(function (Builder $query, User $user, Ability $ability): void {
$query->whereBelongsTo($user, 'author')->whereIn('brand_id', $user->brandsOnlyWhere("{$ability} own posts", above: ["{$ability} brand posts"]));
}),
brandsOnlyWhere() stands for brandsWhere() of the first permission minus the brands of every higher level, whose permissions above lists, so each brand is read by one level only.
Search keys
On a searchable model, key these perimeters by the brand of the row and the brands where the reader holds the view right:
BrandPerimeter::new()
// allowed(), should() and query() as above
->searchKeys(
name: 'brand',
row: fn (Post $post) => $post->brand_id,
reader: fn (User $user) => $user->brandsWhere('view brand posts'),
),
OwnPerimeter::new()
// allowed(), should() and query() as above
->searchKeys(
name: 'own',
row: fn (Post $post) => [[$post->brand_id, $post->author_id]],
reader: fn (User $user) => array_map(fn (int $brand): array => [$brand, $user->id], $user->brandsWhere('view own posts')),
),
The key of an own post holds its brand with its author: an author key alone would find the reader's posts in every brand, even one where they hold no right. Post::search()->controlled() finds the posts of every brand of the reader, and laravel-rest-api serves the lists and the searches of several brands under one decision context, with its extension as it is. Check with assertSearchAgrees() on posts of several brands.
A child read through its parent
A ThroughParent decides its parent under the decision context of the request, and never reads the brand of the child row. With the perimeters above, which read the brand of the row and never the current brand, that changes nothing: a comment is readable wherever its post is. A condition on the comment's own brand and the reader's rights goes in the comment's boundary.
It is different when the control of the parent reads the brands from the decision context, such as ['brands' => '1,2'] for a headquarters that reads two brands. The parent is then decided under the whole context, and being readable in any one of its brands is enough. Take a post P readable only in brand B, and a comment of brand A on P under a comment boundary that keeps the brands of the request: under A and B, the comment is listed and granted, since P is readable in B, though neither brand alone grants it. Every path agrees on this wide answer, so the assertions cannot catch it.
decidedInRowContext() decides the parent, for each child row, within the brand that the row holds: see Row context.
Without the row context
Without decidedInRowContext(), serve the children of such a parent one brand at a time, with a boundary on the child that keeps its rows to the brand of the request. To show several brands on one page, run one query per brand, switch the decision context between them, and decide everything the page needs on those rows, withAbilities(), every can() and the API resources that check them, while the context of their brand is in force. Never join those queries with orWhere(). laravel-rest-api decides under the context of the request, so there one brand at a time means one brand per request.
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.
Row context
Decide the parent of a ThroughParent in the brand or tenant of each child row with decidedInRowContext() and Access::rowContextUsing(), and test the switch.