Perimeter classes
Generating a perimeter class
A perimeter is an instance of a class that extends Lomkit\Access\Perimeters\Perimeter:
php artisan make:perimeter ClientPerimeter
The class lands in app/Access/Perimeters, empty:
namespace App\Access\Perimeters;
use Lomkit\Access\Perimeters\Perimeter;
class ClientPerimeter extends Perimeter {}
Its rules are the callbacks that the control declares, allowed(), should() and query(), as Perimeters shows. The class names the rule, in access:check and in the errors.
Rules in the class
A rule shared by several controls can live in the class instead, in three protected hooks:
php artisan make:perimeter EditorialPerimeter --hooks
namespace App\Access\Perimeters;
use App\Models\User;
use Illuminate\Database\Eloquent\Builder;
use Illuminate\Database\Eloquent\Model;
use Lomkit\Access\AccessContext;
use Lomkit\Access\Perimeters\Perimeter;
class EditorialPerimeter extends Perimeter
{
protected function allows(AccessContext $context): bool
{
$reader = $context->reader();
return $reader instanceof User
&& $reader->client_id !== null
&& $reader->can("{$context->ability()} editorial posts");
}
protected function includes(Model $row, AccessContext $context): bool
{
$reader = $context->reader();
return $reader instanceof User && $row->client_id === $reader->client_id;
}
protected function scope(Builder $query, AccessContext $context): void
{
$reader = $context->reader();
$query->where('client_id', $reader instanceof User ? $reader->client_id : 0);
}
}
| Hook | Callback it replaces |
|---|---|
allows(AccessContext $context): bool | allowed() |
includes(Model $row, AccessContext $context): bool | should() |
scope(Builder $query, AccessContext $context): void | query() |
- Each hook receives an
AccessContext:reader()gives the reader, typedModel, so check its class withinstanceof;ability()gives the ability. allows()refuses a reader without a client, so thatincludes()andscope()never compare with anullclient.--hooksgenerates the three hooks, which refuse everything until you write them. Removeincludes()to check the rows in SQL.- A rule is written once: declaring in the control the callback of a hook that the class overrides throws
OverriddenPerimeterHookException. - The control lists the class with
EditorialPerimeter::new(), and may still addallowed()when the class does not overrideallows().
Variants of a class
A class that needs a value for each use, such as the kind of document, keeps it as private state that every hook reads. A required value goes in a constructor with readonly promoted properties, behind a named static constructor:
namespace App\Access\Perimeters;
use Illuminate\Database\Eloquent\Builder;
use Illuminate\Database\Eloquent\Model;
use Lomkit\Access\AccessContext;
use Lomkit\Access\Perimeters\Perimeter;
final class OwnedDocuments extends Perimeter
{
private function __construct(private readonly string $kind) {}
public static function ofKind(string $kind): self
{
return new self($kind);
}
protected function includes(Model $row, AccessContext $context): bool
{
return $row->kind === $this->kind && $row->owner_id === $context->reader()->getKey();
}
protected function scope(Builder $query, AccessContext $context): void
{
$query->where('kind', $this->kind)->where('owner_id', $context->reader()->getKey());
}
}
OwnedDocuments::ofKind('invoice')
->allowed(fn (User $user, Ability $ability) => $user->can("{$ability} own invoices"));
- Call the named constructor first: the fluent methods clone the perimeter and keep its state.
X::new()on a class whose constructor requires arguments, or is not public, throwsUnbuildablePerimeterException.- Build the state from constants, never from the request or the user: the control keeps its perimeters for the whole process. See Controls.
- Never narrow a class with a second
query(), or by wrapping it in another perimeter: the package reads only what each perimeter of the list declares.
Perimeters
A perimeter is one access rule of a control. allowed() is the permission, query() gives the rows for the lists, should() checks one row.
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.