Abilities
use Lomkit\Access\Ability;
Ability::view(); // also create(), update(), delete(), restore(), forceDelete()
Ability::of('approve'); // any business ability
$ability->is('view'); // compare by name, with a string or an Ability
$ability->name(); // 'view'
"{$ability} posts"; // 'view posts'
Every decision is made for an ability: what the reader wants to do with the rows. Lomkit\Access\Ability is an immutable value object, open to any business ability, that every perimeter callback and hook receives.
The value object
Ability::of()throwsInvalidAbilityExceptionfor an empty name, a name with whitespace, or a name that is not valid UTF-8.- Compare with
is(), never with===: two abilities with the same name are two objects, and an ability restored byunserialize()is a new one. - It converts to its name in a string, so a permission reads
"{$ability} client posts":view client posts,approve client posts. - laravel-rest-api has its own
Lomkit\Rest\Authorization\Abilityenum, closed to its standard actions. It is a different type: import the one of the package you call.
How the callbacks receive it, and how to type their parameter, is on the Perimeters page.
From a policy method to an ability
The control maps each policy method to an ability with abilityFor():
| Policy method | Ability |
|---|---|
viewAny, view | view |
create, update, delete, restore, forceDelete | the same |
any other method, such as approve | Ability::of($method) |
The same mapping serves everywhere a name is given: the policy, controlled('update') and controlledFor($user, 'approve'), withAbilities(), Access::preload(), the abilities of assertControlAgrees(), and the row checks of laravel-rest-api. A name that the control cannot map throws InvalidAbilityException.
To change the mapping, override abilityFor() on the control, as Policies shows: the perimeters, the policy and the controlled queries then follow the new mapping, while controlled() without an ability still lists view.
Business abilities
A business ability, such as approve, export or publish, is decided by the same perimeters as the standard ones: allowed() receives Ability::of('approve'), so a permission such as "{$ability} client posts" reads approve client posts.
- In a policy, a method that calls
decideByControl()declares it, withDraft::of($row)for a row about to be created: see Policies. - In a query, list its rows with
Post::controlledFor($user, 'approve'), and decide a page withwithAbilities(['approve']). - A perimeter that grants
viewbut notapproverefuses it inallowed(), or narrows its rows inquery()andshould()with$ability->is('approve').
Without a row, a business ability means "somewhere": only the allowed() callbacks run. A policy method that receives a draft passes it on as it is; it never wraps a model in Draft::of() itself, or a saved row changed with fill() would be judged on its new values.
Deciding in code
Outside a policy, the control decides directly:
use Lomkit\Access\Ability;
use Lomkit\Access\Access;
use Lomkit\Access\Decisions\Draft;
$control = Access::controlFor(Post::class);
$control->applies($user, Ability::update(), $post); // bool
$control->decide($user, $control->abilityFor('approve'), $post); // Illuminate\Auth\Access\Response
$control->applies($user, Ability::create(), Draft::of($newPost)); // a draft, judged in memory
$control->applies($user, Ability::create()); // without a row: "somewhere"
decide() returns the same Response as the policy, with its refusal code. Both ignore the policies, Gate::before() included: they give what the control grants. Prefer the Gate in your application code, so that a policy of your own still applies.
Generators
make:control and make:perimeter scaffold the controls and the perimeter classes, from stubs that you can publish and change.
Kept decisions
What the package keeps within a request or a job, what forgets it, the writes of Laravel's own tables that do not, and when to call Access::forgetDecisions().