Essentials

Perimeter classes

Every perimeter is a class of your application. Keep its rules as callbacks in the control, or write them once in the class, with protected hooks and variants.

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:

app/Access/Perimeters/ClientPerimeter.php
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
app/Access/Perimeters/EditorialPerimeter.php
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);
    }
}
HookCallback it replaces
allows(AccessContext $context): boolallowed()
includes(Model $row, AccessContext $context): boolshould()
scope(Builder $query, AccessContext $context): voidquery()
  • Each hook receives an AccessContext: reader() gives the reader, typed Model, so check its class with instanceof; ability() gives the ability.
  • allows() refuses a reader without a client, so that includes() and scope() never compare with a null client.
  • --hooks generates the three hooks, which refuse everything until you write them. Remove includes() 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 add allowed() when the class does not override allows().

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:

app/Access/Perimeters/OwnedDocuments.php
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, throws UnbuildablePerimeterException.
  • 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.