# 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.

```php
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](/essentials/perimeters#the-ability) page.

## From a policy method to an ability

The control maps each policy method to an ability with `abilityFor()`:

<table>
<thead>
  <tr>
    <th>
      Policy method
    </th>
    
    <th>
      Ability
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        viewAny
      </code>
      
      , <code>
        view
      </code>
    </td>
    
    <td>
      <code>
        view
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        create
      </code>
      
      , <code>
        update
      </code>
      
      , <code>
        delete
      </code>
      
      , <code>
        restore
      </code>
      
      , <code>
        forceDelete
      </code>
    </td>
    
    <td>
      the same
    </td>
  </tr>
  
  <tr>
    <td>
      any other method, such as <code>
        approve
      </code>
    </td>
    
    <td>
      <code>
        Ability::of($method)
      </code>
    </td>
  </tr>
</tbody>
</table>

The same mapping serves everywhere a name is given: the [policy](/essentials/policies), `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](/essentials/policies#abilities) 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](/essentials/policies#business-abilities).
- 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:

```php
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](/essentials/policies#refusals). 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.
