# Boundaries

> A boundary is a condition that every row must meet, whatever the perimeter that grants it, such as the tenant or the workspace of the user.

## A condition on every row

A tenant, a workspace or a company is not one more perimeter: it is a condition that every row must meet, whatever the perimeter that grants it. Declare it once in the `boundary()` method of the control:

```php [app/Access/Controls/PostControl.php]
use Lomkit\Access\Boundaries\Boundary;

protected function boundary(): Boundary
{
    return Boundary::where('workspace_id', fn (User $user) => $user->current_workspace_id);
}
```

The boundary applies as an **AND** around the perimeters:

- in the controlled queries and in the policy alike, for every ability;
- before the [levels](/essentials/levels): a user reaches the level of their perimeters, inside their workspace;
- even for an [unrestricted](/essentials/perimeters#unrestricted-perimeters) perimeter: an administrator who sees every post sees every post of their workspace.

So the perimeters never repeat the condition, and none of them can forget it. Without `boundary()`, a control has no boundary, as with `Boundary::none()`.

## `Boundary::where()`

`Boundary::where($column, $readerValue)` keeps the rows whose column equals the value that the closure reads from the reader, an int or a string. The same declaration gives the SQL of the controlled queries and the check of the policy, in memory, without a query.

The boundary fails closed:

- A reader value of `null`, such as a user without a current workspace, closes the boundary: the user reads no row, and the policy refuses every ability, `create` included. The SQL never compares with `IS NULL`.
- A reader whose type the closure does not accept, such as an API client for `fn (User $user)`, is refused the same way.
- Any other value than an int, a string or `null` throws `InvalidBoundaryValueException`.

### Read-only rows

`Boundary::where(...)->readOnlyWhenNotNull($column)` keeps a row readable while the column is not null, and refuses it to every other ability. The method exists only on the boundary that `Boundary::where()` returns: for another boundary, write a [boundary class](#boundary-classes) whose `scope()` and `includes()` refuse the abilities other than `view` on such rows.

```php
protected function boundary(): Boundary
{
    return Boundary::where('workspace_id', fn (User $user) => $user->current_workspace_id)
        ->readOnlyWhenNotNull('archived_at');
}
```

An archived post stays in `controlled()` and its `view` is granted, but `update`, `delete` and business abilities such as `approve` are refused, and `controlled('update')` leaves it out.

## Refusals

The policy tells two refusals of the boundary apart:

<table>
<thead>
  <tr>
    <th>
      Code
    </th>
    
    <th>
      When
    </th>
    
    <th>
      Status
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        outside_boundary
      </code>
    </td>
    
    <td>
      The row is outside the boundary for this ability, but the user may still view it, such as an archived post
    </td>
    
    <td>
      403
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        not_found
      </code>
    </td>
    
    <td>
      The boundary also refuses <code>
        view
      </code>
      
      , such as a post of another workspace
    </td>
    
    <td>
      404
    </td>
  </tr>
</tbody>
</table>

A row of another workspace answers like a row that does not exist, so its existence is never revealed. See [Policies](/essentials/policies#refusals).

## Boundary classes

A condition that one column cannot express is a class that extends `Lomkit\Access\Boundaries\Boundary`:

```php [app/Access/Boundaries/TeamBoundary.php]
namespace App\Access\Boundaries;

use App\Models\User;
use Illuminate\Database\Eloquent\Builder;
use Lomkit\Access\AccessContext;
use Lomkit\Access\Boundaries\Boundary;

class TeamBoundary extends Boundary
{
    protected function scope(Builder $query, AccessContext $context): void
    {
        $reader = $context->reader();

        $query->whereIn('team_id', $reader instanceof User ? $reader->teams()->select('teams.id') : []);

        if (! $context->ability()->is('view')) {
            $query->where('locked', false);
        }
    }
}
```

```php
protected function boundary(): Boundary
{
    return new TeamBoundary;
}
```

- `scope()` is required: the condition in SQL, for the controlled queries. It receives the `AccessContext`, with the reader and the ability. A join throws `JoinInPerimeterException`: use `whereHas()` or an `exists` subquery.
- `includes(Model $row, AccessContext $context): bool`, optional, checks a row in memory. Without it, the policy checks the boundary with one `exists` query on the row, even for an unrestricted perimeter, and refuses every [draft](/essentials/policies#drafts), since a row about to be created is not in the database.
- `admits(AccessContext $context): bool`, optional, is the boundary without a row. When it returns `false`, the reader reaches nothing for that ability: `controlled()` lists no row, and the policy refuses with `no_perimeter`, `viewAny` and `create` included.

`boundary()` follows the rule of `perimeters()`: it is built once per process, so it never reads the user, the request or the tenant while it builds the boundary. Read them in `scope()` and `includes()`, from the context. See [Controls](/essentials/controls#pure-perimeter-lists).

## Good to know

- A controlled search applies the boundary too: `Boundary::where()` gives its search keys, and a boundary class declares them in a `searchKeys()` method. See [Search overview](/search/overview#the-boundary).
- A `Gate::before()` callback that returns `true` grants before any policy runs, so it bypasses the boundary too, as it bypasses every policy in Laravel.
- The boundary holds one value per reader. When one list spans several brands or companies, the brand belongs to the perimeters, not to the boundary: see [Several brands](/digging-deeper/several-brands).
