Essentials

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:

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: a user reaches the level of their perimeters, inside their workspace;
  • even for an unrestricted 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 whose scope() and includes() refuse the abilities other than view on such rows.

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:

CodeWhenStatus
outside_boundaryThe row is outside the boundary for this ability, but the user may still view it, such as an archived post403
not_foundThe boundary also refuses view, such as a post of another workspace404

A row of another workspace answers like a row that does not exist, so its existence is never revealed. See Policies.

Boundary classes

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

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);
        }
    }
}
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, 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.

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.
  • 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.