# access:check

> php artisan access:check builds every control and reports in CI what would throw, open or hide rows, or leave search documents stale.

```bash
SCOUT_DRIVER=meilisearch php artisan access:check
```

`access:check` builds every discovered control, declares and verifies its perimeters whatever the environment, and reports what would throw, open or hide rows, or leave search documents stale, before production meets it. Run it in CI with the Scout driver of production: the engine checks use the driver of the environment the command runs in.

```txt
controls  2 built from app/Access/Controls
  cache ................................................................. not cached
  models ................................................ 2 scanned in app/Models
  scout driver ........................ meilisearch, from the config of this environment
  pivots ............ 1 BelongsToMany relation with a declared return type scanned
  App\Access\Controls\PostControl  App\Models\Post
  #1.1 GlobalPerimeter ........................................ memory, unrestricted
  #1.2 ClientPerimeter .................................... sql, search keys client
  #2 SharedPerimeter .................................................... memory
  boundary ...................... Lomkit\Access\Boundaries\ColumnBoundary, memory, searchable
  search ................ ControlledSearchable on Laravel\Scout\Engines\MeilisearchEngine
  policy ................................................ App\Policies\PostPolicy, controlled
  App\Access\Controls\CommentControl  App\Models\Comment
  #1 ThroughParent [post] ....... sql, update from the parent's update, view from the parent's view
  boundary ...................................................................... none
  search ................................................................ not searchable
  policy ............................. Lomkit\Access\Policies\AutomaticPolicy, automatic
  problems .................................................................. 1 FAILED
  ⇂ The [App\Access\Perimeters\SharedPerimeter] perimeter at #2 of the [App\Access\Controls\PostControl] control declares no search keys, so a reader that only this perimeter reaches finds none of its [App\Models\Post] rows in a controlled text search. Declare searchKeys() on the perimeter, or unrestricted() if it reaches every row
  notes ........................................................................ none

   ERROR  1 problem found.
```

Each control is listed with its model, its perimeters by position (`#1.2` is the second level of the first group), the mode of each perimeter (`memory` with a `should()` callback, `sql` without), its boundary, its `ThroughParent` relations and their delegated abilities, the search engine of a `ControlledSearchable` model, and its policy:

<table>
<thead>
  <tr>
    <th>
      Policy form
    </th>
    
    <th>
      Meaning
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        controlled
      </code>
    </td>
    
    <td>
      A policy that extends <code>
        ControlledPolicy
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        automatic
      </code>
    </td>
    
    <td>
      Registered by <code>
        Access::registerPolicies()
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        own
      </code>
    </td>
    
    <td>
      A policy that does not extend <code>
        ControlledPolicy
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        none
      </code>
    </td>
    
    <td>
      No policy
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        unresolvable
      </code>
    </td>
    
    <td>
      The Gate throws while it resolves the policy
    </td>
  </tr>
</tbody>
</table>

The command exits with `1` when it finds a problem, `0` otherwise. Notes never change the exit code.

## Problems

<table>
<thead>
  <tr>
    <th>
      Kind
    </th>
    
    <th>
      Reported when
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        control_failure
      </code>
    </td>
    
    <td>
      Building a control, its declaration or the verification of its perimeters throws: impure perimeters, empty or nested levels, a <code>
        ThroughParent
      </code>
      
       on a missing relation, a cycle, a parent without control, an invalid delegation, a duplicate search key name, a control without model. The message quotes the exception.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        duplicate_control
      </code>
    </td>
    
    <td>
      Two discovered controls, or a discovered control and <code>
        #[ControlledBy]
      </code>
      
      , declare the same model.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        uncontrolled_model
      </code>
    </td>
    
    <td>
      A model of the scanned directories uses <code>
        HasControl
      </code>
      
       and has no control.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        invalid_controlled_by
      </code>
    </td>
    
    <td>
      <code>
        #[ControlledBy]
      </code>
      
       names a class that is not a control, or the control of another model.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        stale_control_cache
      </code>
    </td>
    
    <td>
      The cache maps the models to other controls than the discovered ones.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        stale_watch_cache
      </code>
    </td>
    
    <td>
      The controls are cached, and the cache of the watched models is missing, unreadable, or lists other models than the <code>
        reindexWhen()
      </code>
      
       rules of the controls.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        unresolvable_policy
      </code>
    </td>
    
    <td>
      The Gate throws while it resolves the policy of a controlled model.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        policy_without_control
      </code>
    </td>
    
    <td>
      The policy of a controlled model extends <code>
        ControlledPolicy
      </code>
      
       without <code>
        $control
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        policy_for_another_control
      </code>
    </td>
    
    <td>
      That policy names another control than the one of its model.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        plain_searchable
      </code>
    </td>
    
    <td>
      A controlled model uses Scout's <code>
        Searchable
      </code>
      
       instead of <code>
        ControlledSearchable
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        unsupported_search_engine
      </code>
    </td>
    
    <td>
      The engine of a <code>
        ControlledSearchable
      </code>
      
       model cannot filter a controlled search: not supported nor trusted, the <code>
        collection
      </code>
      
       engine, or an engine that throws when it is built.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        unsearchable_boundary
      </code>
    </td>
    
    <td>
      On an engine that stores documents, the boundary has no search form.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        perimeter_without_search_keys
      </code>
    </td>
    
    <td>
      On an engine that stores documents, a perimeter that is neither unrestricted nor a <code>
        ThroughParent
      </code>
      
       declares no search keys. The problem names the position of the perimeter.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        search_freshness
      </code>
    </td>
    
    <td>
      Something would leave documents stale: Scout's <code>
        after_commit
      </code>
      
       off, <code>
        makeSearchableUsing()
      </code>
      
       overridden without <code>
        withAccessKeys()
      </code>
      
      , a relation that the search keys read and that nothing reindexes.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        pivot_without_using
      </code>
    </td>
    
    <td>
      A <code>
        BelongsToMany
      </code>
      
       relation reaches the table of a pivot that uses <code>
        ReindexesSearch
      </code>
      
       without <code>
        ->using()
      </code>
      
       it.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        unreadable_relation
      </code>
    </td>
    
    <td>
      A relation that the command reads throws when it is read without a database connection.
    </td>
  </tr>
</tbody>
</table>

## Notes

<table>
<thead>
  <tr>
    <th>
      Kind
    </th>
    
    <th>
      Reported when
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        inherited_memory_perimeters
      </code>
    </td>
    
    <td>
      Two discovered controls or more inherit <code>
        perimeters()
      </code>
      
       from a base class whose perimeters have a <code>
        should()
      </code>
      
       callback.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        policy_outside_control
      </code>
    </td>
    
    <td>
      The policy of a controlled model does not extend <code>
        ControlledPolicy
      </code>
      
      , so the package cannot check that it names the model's control.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        model_without_policy
      </code>
    </td>
    
    <td>
      No policy is registered for a controlled model.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        ungrantable_drafts
      </code>
    </td>
    
    <td>
      No perimeter of a control can grant a <a href="/essentials/policies#drafts">
        draft
      </a>
      
      : none has a <code>
        should()
      </code>
      
       callback or an <code>
        includes()
      </code>
      
       hook, none is unrestricted, and no <code>
        ThroughParent
      </code>
      
       delegates <code>
        create
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        boundary_refusing_drafts
      </code>
    </td>
    
    <td>
      The boundary of a control has no in-memory form, so it refuses every draft.
    </td>
  </tr>
</tbody>
</table>

When a kind has more than five notes, the human output prints them on one line, with their count, the base classes they share and the first three subjects. Problems are never grouped, and `--json` lists every note. No attribute, interface or option silences a note: fix what it reports, or read it in the JSON.

## Options

<table>
<thead>
  <tr>
    <th>
      Option
    </th>
    
    <th>
      Effect
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        --json
      </code>
    </td>
    
    <td>
      Prints the same report as one JSON document.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --only=App\Models\Post
      </code>
    </td>
    
    <td>
      Checks only these controls, given by model or control class, repeatable. The discovery, the cache and the pivots are always checked. A name that matches no control exits with <code>
        2
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --models=app/Domain/Models
      </code>
    </td>
    
    <td>
      Sets the directories scanned for models that use <code>
        HasControl
      </code>
      
       or <code>
        #[ControlledBy]
      </code>
      
      , <code>
        app/Models
      </code>
      
       by default, repeatable. Globs are accepted, such as <code>
        --models='modules/*/src/Models'
      </code>
      
      , resolved from the working directory.
    </td>
  </tr>
</tbody>
</table>

The scan of `--models` adds what discovery cannot see: the models that use `HasControl` without a control, the controls that a scanned model names with `#[ControlledBy]` outside the discovered directories, which are then checked like the others, and the `BelongsToMany` relations of the scanned models, for `pivot_without_using`. The models of the discovered controls are always checked, wherever they live.

### The JSON report

`--json` gives:

- `passed`;
- `discovery`: `paths`, `cached`, `models`, `scanned`, `scout_driver`;
- `controls`: each with `control`, `model`, `perimeters` (`position`, `perimeter`, `mode`, `unrestricted`, `search_keys`, `parent` with `relation`, `delegates` and `allowed`), `boundary` (`boundary`, `mode`, `searchable`), `search` (`searchable`, `engine`) and `policy` (`policy`, `form`);
- `pivots`: `relations`;
- `problems`: `kind`, `subject`, `position` and `message`;
- `notes`: `kind`, `subject` and `message`.

There is no runtime list of the controls: for an inventory, in CI or in a review, read `controls[].model` and `controls[].control`, with `--models` covering every directory that holds a controlled model.

## What it does not do

The command is read-only: it never writes the cache, runs no query and dispatches no job. It builds the controls, resolves the policies and the Scout engines, and reads the relations without a database connection.

- It cannot tell whether a `should()` callback describes the same rows as its `query()`, or reads a relation: [`assertControlAgrees()`](/testing-and-tooling/testing#the-decisions) proves the first on your test data.
- The pivot check only sees the public relation methods that declare a `BelongsToMany` return type, or a subclass such as `MorphToMany`.
- A minor release may add problems and notes, so a CI that passed may fail after it, as with the new rules of a linter.
