Digging Deeper

What is public in 1.x

The releases of 1.x follow semantic versioning for what this documentation describes. Learn what that covers, and what may change in any release.

The releases of 1.x follow semantic versioning for what this documentation and the upgrade guide describe, and do not mark @internal.

Covered

  • The classes, and their public and protected methods, that the documentation shows an application calling, extending, implementing or overriding.
  • The exception classes and the classes they extend, thrown in the cases the documentation gives. Their messages, and the way they are built, are not covered.
  • The refusal codes of the policies, unsaved, no_perimeter, outside_boundary, not_found and outside_rows, and the names of the search attributes, _access and _boundary.
  • The artisan commands, their options, their exit codes and the JSON of access:check. A minor release may add problems and notes to access:check, so a CI that passed may fail after it, as with the new rules of a linter.
  • The assertions of InteractsWithAccess, whose signatures do not change in 1.x. A minor release may add checks to them, so a test that passed may fail after it, when the new check reveals a disagreement.
  • Access::searchTokens() and Access::guardSearch(), with the bodies the guard accepts and the parameters it forces. A release, even a patch, may refuse a parameter or a filter that turns out to widen what a reader finds: the guard fails closed rather than keep an opening.
  • Access::indexKeysOf(), Access::indexReaderKeys(), IndexReaderKeys with its model(), isClosed() and values(), and the assertIndexKeysAgree() assertion, with the behaviour that Your own search client gives: both fields for each document and each reader, digests of 32 lowercase hexadecimal characters, never an empty list for an open reader nor in the _access of a document, and, for a closed reader, one value in each field that is not a digest and that no document carries. The values themselves change as the keys do.

The classes you extend

Your application extends Perimeter, Control and Boundary. A minor release may add methods to them, and a method of the same name in your subclass would then clash: give the methods you add to your subclasses distinctive names. Their covered members:

ClassCovered members
Perimeternew(), allowed(), should(), query(), searchKeys(), reindexWhen(), unrestricted(), admits() and checksInMemory(); the protected hooks allows(), includes() and scope()
Controlnew(), abilityFor(), decide(), applies() and reachableKeys(); the protected perimeters(), boundary() and applicablePerimeters(), and the protected $model property, declared by its default value and never assigned elsewhere
Boundarywhere(), none() and checksInMemory(); the protected hooks scope(), includes(), searchKeys() and admits(); readOnlyWhenNotNull() on the boundary that where() returns

ControlledPolicy gets no new method in 1.x, since the methods of your policy are named after your abilities: it keeps the seven standard abilities, the protected decideByControl() and declaredControl(), and nothing else.

Not covered

  • A class or a method marked @internal may change or disappear in any release, whatever its PHP visibility, and so may a public or protected method that the documentation does not describe. Do not call, extend, implement, override or type against them.
  • The classes behind the artisan commands, the control registry, and the search keys and filters, such as SearchKeyValues, SearchDocuments, SearchRules and SearchFilter, are internal.
  • AccessServiceProvider is registered by package discovery: list it in bootstrap/providers.php if your application turns the discovery off, and do not extend it.
  • Calling the protected hooks of another perimeter from a perimeter class is not supported: call admits().
  • The access keys, and their digests in your search indexes, are not an API. They live in your indexes, though: a release that changes them says so in its upgrade notes, with the reindex it needs, even a minor one.

ControlledSearchBuilder is the builder that search() returns on a ControlledSearchable model: its controlled(), controlledFor() and uncontrolled() are public.