access:check
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 form | Meaning |
|---|---|
controlled | A policy that extends ControlledPolicy |
automatic | Registered by Access::registerPolicies() |
own | A policy that does not extend ControlledPolicy |
none | No policy |
unresolvable | The 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
| Kind | Reported when |
|---|---|
control_failure | Building 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_control | Two discovered controls, or a discovered control and #[ControlledBy], declare the same model. |
uncontrolled_model | A 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_cache | The cache maps the models to other controls than the discovered ones. |
stale_watch_cache | The 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_policy | The Gate throws while it resolves the policy of a controlled model. |
policy_without_control | The policy of a controlled model extends ControlledPolicy without $control. |
policy_for_another_control | That policy names another control than the one of its model. |
plain_searchable | A controlled model uses Scout's Searchable instead of ControlledSearchable. |
unsupported_search_engine | The 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_boundary | On an engine that stores documents, the boundary has no search form. |
perimeter_without_search_keys | On 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_freshness | Something 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_using | A BelongsToMany relation reaches the table of a pivot that uses ReindexesSearch without ->using() it. |
unreadable_relation | A relation that the command reads throws when it is read without a database connection. |
Notes
| Kind | Reported when |
|---|---|
inherited_memory_perimeters | Two discovered controls or more inherit perimeters() from a base class whose perimeters have a should() callback. |
policy_outside_control | The policy of a controlled model does not extend ControlledPolicy, so the package cannot check that it names the model's control. |
model_without_policy | No policy is registered for a controlled model. |
ungrantable_drafts | No 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_drafts | The 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
| Option | Effect |
|---|---|
--json | Prints the same report as one JSON document. |
--only=App\Models\Post | 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 2. |
--models=app/Domain/Models | Sets 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 withcontrol,model,perimeters(position,perimeter,mode,unrestricted,search_keys,parentwithrelation,delegatesandallowed),boundary(boundary,mode,searchable),search(searchable,engine) andpolicy(policy,form);pivots:relations;problems:kind,subject,positionandmessage;notes:kind,subjectandmessage.
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 itsquery(), or reads a relation:assertControlAgrees()proves the first on your test data. - The pivot check only sees the public relation methods that declare a
BelongsToManyreturn type, or a subclass such asMorphToMany. - 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.
Testing
The InteractsWithAccess assertions prove on your test data that the levels nest, the policy and the queries agree, and the search finds what the SQL lists.
Cache and about
Cache the control of each model with access:cache in every deployment, and read the state of the package in the Access Control section of php artisan about.