Quick start
Install the package 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:
php artisan make:perimeter GlobalPerimeter
php artisan make:perimeter ClientPerimeter
php artisan make:perimeter OwnPerimeter
php artisan make:control PostControl
The 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:
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 postsorupdate own postsare permission names of your application, checked here with$user->can(): define them withGate::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 asquery(). 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 and Levels.
The client perimeter refuses a user without a client in allowed(), so a null client never matches the posts without a client.
GlobalPerimeter reaches the posts of every client. When clients are tenants, keep each user inside theirs with a boundary.2. Link the model
Add the HasControl trait to the model:
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.
3. Register the policies
Call Access::registerPolicies() in the boot() method of a service provider:
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.
4. Use it
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.
Next steps
- Search. With Laravel Scout, give each perimeter that restricts rows its search keys and use
ControlledSearchableon the model:Post::search('budget')->controlled()then keeps the posts the user may view. The Search section covers the keys, the engines and the reindexing. - Testing. Run
php artisan access:checkin CI, and prove in your tests that the policy, the queries and the search agree with the assertions ofInteractsWithAccess. The Testing and tooling section covers both. - Essentials. Read Controls and the pages that follow, in order.