Digging Deeper

Abilities

The Ability value object names what a reader wants to do: how a policy method maps to an ability, how to change the mapping, and how business abilities work.
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() throws InvalidAbilityException for 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 by unserialize() 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\Ability enum, 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 methodAbility
viewAny, viewview
create, update, delete, restore, forceDeletethe same
any other method, such as approveAbility::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, with Draft::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 with withAbilities(['approve']).
  • A perimeter that grants view but not approve refuses it in allowed(), or narrows its rows in query() and should() 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.