Introduction
What it is
Laravel Access Control decides who can see and change which rows of your Eloquent models. For each model, you write one control. Its perimeters say which users reach which rows, for each ability: view, update, delete, or a business ability such as approve.
namespace App\Access\Controls;
use App\Access\Perimeters\ClientPerimeter;
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(
ClientPerimeter::new()
->allowed(fn (User $user, Ability $ability) => $user->client_id !== null && $user->can("{$ability} client posts"))
->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);
}),
),
];
}
}
Each perimeter answers up to three questions:
allowed()is the permission: does this perimeter apply to the user, for this ability? A user who may update the posts of their client reaches the client perimeter forupdate.query()gives the rows of the perimeter in SQL, for the lists.should(), optional, checks one row in memory: when a user may only see their own posts,should()checks that the post at hand is theirs.ClientPerimeterhas none: the package checks its rows through itsquery(), in one SQL query.
The client perimeter refuses a user without a client in allowed(), so that a null client never matches the posts without one. See Perimeters.
The same control then answers everywhere:
$user->can('update', $post); // the policy
Post::query()->controlled()->paginate(); // the posts the signed-in user may view
Post::controlled('update')->count(); // the posts they may update
Post::search('budget')->controlled()->get(); // a Laravel Scout search, with the same rules
The search needs search keys on the perimeters and the ControlledSearchable trait on the model, as the Search section shows.
Why use it
- One place for each rule. The policy behind
$user->can(), thecontrolled()scope of your queries, the filter of your Scout searches and the row restriction of your laravel-rest-api resources all read the same control. A rule changed in the control changes everywhere. - Fails closed. A query without a signed-in user, a user that no perimeter allows, or a boundary without a value gives no row. A missing or wrong declaration throws an exception instead of opening rows.
- Built for real access models. Levels apply the highest level a user reaches. A boundary keeps every row inside the user's tenant or workspace. A parent gives a comment the access of its post.
- Checked.
php artisan access:checkreports in CI what would throw, open or hide rows. Test assertions prove that the policy, the queries and the search agree on your test data.
How it fits Laravel
- Policies.
Access::registerPolicies()gives every controlled model a policy built on its control, unless the model has a policy of its own.can(),@can,authorize()andGate::inspect()work as usual. See Policies. - Eloquent.
controlled(),controlledFor()anduncontrolled()are local scopes of theHasControltrait. A query is controlled only when it says so: no global scope changes your other queries. See Queries. - Laravel Scout.
ControlledSearchableindexes each document with the keys that open it, and a controlled search keeps the documents that the user may view, in one engine query. - Laravel Rest Api. With laravel-rest-api 3.6 or higher, an extension applies your controls to every resource of a controlled model, with no perimeter to write in the resources.
When to use it
Laravel Access Control fits an application where users reach only some rows of a model: the rows of their tenant, of their client, of their team, or their own rows, with rights that differ by ability. It suits list screens, exports and searches that must show exactly the rows that the policy allows.
When it does not fit
- Storing roles and permissions. The package does not store roles or permissions. Your
allowed()callbacks read them from your application, such as$user->can()with a permission package or your own tables. - Hiding columns. A control decides which rows a user reaches, not which attributes of a row they see.
- Every user sees every row. When access depends on the ability alone, never on the row, a plain Laravel policy is enough.
Requirements
Laravel Access Control requires PHP 8.3 or higher and Laravel 13. Laravel Scout and laravel-rest-api are optional, see Installation.
How it compares
- Laravel policies and query scopes. A Laravel policy authorizes an action for a model or resource, and a local scope filters a query: written by hand, they are two places to keep in agreement. Laravel Access Control builds the policy and the
controlled()scope from the same control, and gives the same rules to Laravel Scout. - spatie/laravel-permission. spatie/laravel-permission manages user permissions and roles in a database. Laravel Access Control does not store them: its
allowed()callbacks can read the permissions that spatie/laravel-permission manages, so the two packages work together. With teams, put the current team in the decision context. - PostgreSQL row-level security. Row security policies restrict, per database user, which rows a table returns or changes, for every query that reaches it, from Laravel or from any other client. Laravel Access Control works in the application: it filters only the queries that call
controlled()orcontrolledFor(), and the same control drives the policy and the Scout search, which the database does not reach.
Meet Lomkit
Lomkit is an organization dedicated to the Laravel community. We offer a collection of open source packages for developers, and we keep them up to date with the latest practices of the framework.
Community contributions are welcome. Explore our packages on GitHub, open an issue or send a pull request.