# Quick start

> Control your first model in four steps, from the perimeter classes to the policy and the controlled queries.

[Install the package](/getting-started/installation) first.

Take a `Post` model with a `client_id` and an `author_id`, and a `User` model with a `client_id`. Three kinds of users read posts: administrators read every post, managers read the posts of their client, authors read their own posts.

## 1. Declare who reaches which posts

Create one perimeter class per kind of access, and the control of the model:

```bash
php artisan make:perimeter GlobalPerimeter
php artisan make:perimeter ClientPerimeter
php artisan make:perimeter OwnPerimeter
php artisan make:control PostControl
```

The [perimeter classes](/essentials/perimeter-classes) land in `app/Access/Perimeters` and the control in `app/Access/Controls`. `make:control` names the model after the control, `App\Models\Post` here. Declare the rules of each perimeter in the control:

```php [app/Access/Controls/PostControl.php]
namespace App\Access\Controls;

use App\Access\Perimeters\ClientPerimeter;
use App\Access\Perimeters\GlobalPerimeter;
use App\Access\Perimeters\OwnPerimeter;
use App\Models\Post;
use App\Models\User;
use Illuminate\Database\Eloquent\Builder;
use Lomkit\Access\Ability;
use Lomkit\Access\Controls\Control;
use Lomkit\Access\Perimeters\Levels;

class PostControl extends Control
{
    protected string $model = Post::class;

    protected function perimeters(): array
    {
        return [
            Levels::of(
                GlobalPerimeter::new()
                    ->allowed(fn (User $user, Ability $ability) => $user->can("{$ability} all posts"))
                    ->unrestricted(),
                ClientPerimeter::new()
                    ->allowed(fn (User $user, Ability $ability) => $user->client_id !== null && $user->can("{$ability} client posts"))
                    ->should(fn (User $user, Post $post) => $post->client_id === $user->client_id)
                    ->query(function (Builder $query, User $user): void {
                        $query->where('client_id', $user->client_id);
                    }),
                OwnPerimeter::new()
                    ->allowed(fn (User $user, Ability $ability) => $user->can("{$ability} own posts"))
                    ->should(fn (User $user, Post $post) => $post->author_id === $user->id)
                    ->query(function (Builder $query, User $user): void {
                        $query->where('author_id', $user->id);
                    }),
            ),
        ];
    }
}
```

- `allowed()` is the permission: whether the perimeter applies to the user for an ability. `view client posts` or `update own posts` are permission names of your application, checked here with `$user->can()`: define them with `Gate::define()` or a permission package. Any boolean check works.
- `query()` gives the rows of the perimeter in SQL, for the lists.
- `should()` checks one row in memory, for the policy. It must describe the same rows as `query()`. It is kept here because users create posts through these perimeters, and a post about to be created can only be judged in memory. It also saves one query per check.
- `unrestricted()` reaches every post, for the administrators.

The three perimeters form a `Levels::of()` group, widest first: for each ability, only the highest level that the user reaches applies. A manager who also holds `view own posts` reaches the client level for `view`, and the own level is not evaluated. See [Perimeters](/essentials/perimeters) and [Levels](/essentials/levels).

The client perimeter refuses a user without a client in `allowed()`, so a `null` client never matches the posts without a client.

<note>

`GlobalPerimeter` reaches the posts of every client. When clients are tenants, keep each user inside theirs with a [boundary](/essentials/boundaries).

</note>

## 2. Link the model

Add the `HasControl` trait to the model:

```php [app/Models/Post.php]
namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Lomkit\Access\Controls\HasControl;

class Post extends Model
{
    use HasControl;
}
```

The package finds `PostControl` in `app/Access/Controls` through its `$model` property. A control kept in another directory is named on the model with `#[ControlledBy(PostControl::class)]`. See [Controls](/essentials/controls).

## 3. Register the policies

Call `Access::registerPolicies()` in the `boot()` method of a service provider:

```php [app/Providers/AppServiceProvider.php]
use Lomkit\Access\Access;

public function boot(): void
{
    Access::registerPolicies();
}
```

Every controlled model that has no policy of its own now gets one, built on its control. See [Policies](/essentials/policies).

## 4. Use it

```php
Post::query()->controlled()->paginate();         // the posts the signed-in user may view
Post::query()->controlled('update')->paginate(); // the posts the signed-in user may update
Post::controlledFor($user)->get();               // for a named user, in jobs and commands

$user->can('update', $post);                     // the policy, from the same perimeters
```

A query is controlled only when it says so: `Post::query()->get()` still reads every row. A controlled query without a signed-in user returns no row. See [Queries](/essentials/queries).

## Next steps

- **Search.** With Laravel Scout, give each perimeter that restricts rows its search keys and use `ControlledSearchable` on the model: `Post::search('budget')->controlled()` then keeps the posts the user may view. The [Search](/search/overview) section covers the keys, the engines and the reindexing.
- **Testing.** Run `php artisan access:check` in CI, and prove in your tests that the policy, the queries and the search agree with the assertions of `InteractsWithAccess`. The [Testing and tooling](/testing-and-tooling/testing) section covers both.
- **Essentials.** Read [Controls](/essentials/controls) and the pages that follow, in order.
