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

```bash
php artisan make:perimeter ClientPerimeter
```

The class lands in `app/Access/Perimeters`, empty:

```php [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](/essentials/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:

```bash
php artisan make:perimeter EditorialPerimeter --hooks
```

```php [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);
    }
}
```

<table>
<thead>
  <tr>
    <th>
      Hook
    </th>
    
    <th>
      Callback it replaces
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        allows(AccessContext $context): bool
      </code>
    </td>
    
    <td>
      <code>
        allowed()
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        includes(Model $row, AccessContext $context): bool
      </code>
    </td>
    
    <td>
      <code>
        should()
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        scope(Builder $query, AccessContext $context): void
      </code>
    </td>
    
    <td>
      <code>
        query()
      </code>
    </td>
  </tr>
</tbody>
</table>

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

```php [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());
    }
}
```

```php
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](/essentials/controls#pure-perimeter-lists).
- 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.
