Testing and Tooling

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

  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:

Policy formMeaning
controlledA policy that extends ControlledPolicy
automaticRegistered by Access::registerPolicies()
ownA policy that does not extend ControlledPolicy
noneNo policy
unresolvableThe Gate throws while it resolves the policy

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

Problems

KindReported when
control_failureBuilding a control, its declaration or the verification of its perimeters throws: impure perimeters, empty or nested levels, a ThroughParent 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.
duplicate_controlTwo discovered controls, or a discovered control and #[ControlledBy], declare the same model.
uncontrolled_modelA model of the scanned directories uses HasControl and has no control.
invalid_controlled_by#[ControlledBy] names a class that is not a control, or the control of another model.
stale_control_cacheThe cache maps the models to other controls than the discovered ones.
stale_watch_cacheThe controls are cached, and the cache of the watched models is missing, unreadable, or lists other models than the reindexWhen() rules of the controls.
unresolvable_policyThe Gate throws while it resolves the policy of a controlled model.
policy_without_controlThe policy of a controlled model extends ControlledPolicy without $control.
policy_for_another_controlThat policy names another control than the one of its model.
plain_searchableA controlled model uses Scout's Searchable instead of ControlledSearchable.
unsupported_search_engineThe engine of a ControlledSearchable model cannot filter a controlled search: not supported nor trusted, the collection engine, or an engine that throws when it is built.
unsearchable_boundaryOn an engine that stores documents, the boundary has no search form.
perimeter_without_search_keysOn an engine that stores documents, a perimeter that is neither unrestricted nor a ThroughParent declares no search keys. The problem names the position of the perimeter.
search_freshnessSomething would leave documents stale: Scout's after_commit off, makeSearchableUsing() overridden without withAccessKeys(), a relation that the search keys read and that nothing reindexes.
pivot_without_usingA BelongsToMany relation reaches the table of a pivot that uses ReindexesSearch without ->using() it.
unreadable_relationA relation that the command reads throws when it is read without a database connection.

Notes

KindReported when
inherited_memory_perimetersTwo discovered controls or more inherit perimeters() from a base class whose perimeters have a should() callback.
policy_outside_controlThe policy of a controlled model does not extend ControlledPolicy, so the package cannot check that it names the model's control.
model_without_policyNo policy is registered for a controlled model.
ungrantable_draftsNo perimeter of a control can grant a draft: none has a should() callback or an includes() hook, none is unrestricted, and no ThroughParent delegates create.
boundary_refusing_draftsThe boundary of a control has no in-memory form, so it refuses every draft.

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

OptionEffect
--jsonPrints the same report as one JSON document.
--only=App\Models\PostChecks 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 2.
--models=app/Domain/ModelsSets the directories scanned for models that use HasControl or #[ControlledBy], app/Models by default, repeatable. Globs are accepted, such as --models='modules/*/src/Models', resolved from the working directory.

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() 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.