# 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**:

```php
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](/testing-and-tooling/testing#the-levels).

## Loose perimeters add up

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

```php
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](/essentials/perimeters#unrestricted-perimeters) perimeter applies, in a group or outside, the user reaches every row of the [boundary](/essentials/boundaries): no other perimeter narrows it.

## Errors

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