Essentials

Levels

Levels::of() declares a hierarchy of perimeters, widest first, where only the highest level a user reaches applies. Perimeters outside a group add up.

A hierarchy of perimeters

Most access models are a hierarchy: administrators see every post, managers the posts of their client, authors their own posts. Declare it in a Levels::of() group, widest level first:

use Lomkit\Access\Perimeters\Levels;

protected function perimeters(): array
{
    return [
        Levels::of(
            GlobalPerimeter::new()
                ->allowed(fn (User $user, Ability $ability) => $user->can("{$ability} all posts"))
                ->unrestricted(),
            ClientPerimeter::new()
                ->allowed(fn (User $user, Ability $ability) => $user->client_id !== null && $user->can("{$ability} client posts"))
                ->query(fn (Builder $query, User $user) => $query->where('client_id', $user->client_id)),
            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)),
        ),
    ];
}

For each ability, only the highest level the user reaches applies: the first level whose allowed() returns true. The levels below it are neither evaluated nor added to the SQL, in the policy and in the controlled queries alike.

The level is chosen for each ability. A user who holds view client posts and update own posts is at the client level for view and at the own level for update: they read the posts of their client and edit only their own.

Levels nest

A level contains the levels below it: a user who reaches the client level must see at least the rows of the own level. Since the lower levels are not evaluated, a row that only a lower level reaches would vanish for the users of a higher level.

A perimeter that does not nest belongs outside the group. assertLevelsNest() checks the nesting on your test data, see Testing.

Loose perimeters add up

Every perimeter outside a group adds up with the others, with an OR, wherever it is written:

protected function perimeters(): array
{
    return [
        Levels::of(
            GlobalPerimeter::new()->allowed(...)->unrestricted(),
            ClientPerimeter::new()->allowed(...)->query(...),
            OwnPerimeter::new()->allowed(...)->query(...),
        ),
        SharedPerimeter::new()->allowed(...)->query(...), // outside the group: adds up
    ];
}

A user reaches the rows of the level they reach in the group, plus the rows of each loose perimeter that allows them: an author also sees the posts shared with them.

  • A control may declare several groups next to loose perimeters. Each group gives its own level, and they all add up.
  • The order of the perimeters and their classes never change how they combine: only the groups do.
  • When an unrestricted perimeter applies, in a group or outside, the user reaches every row of the boundary: no other perimeter narrows it.

Errors

  • Levels::of() without a level throws EmptyLevelsException.
  • A group given as a level of another group throws NestedLevelsException.