Search

Your own search client

Keep the access filter when you query the search engine with your own client, or feed your own index with Access::indexKeysOf() and Access::indexReaderKeys().

Four ways

An application that queries the engine with its own client keeps the access filter in one of four ways:

You needUse
A multi-search, a vector search or an option that Scout does not expose, on the index of a ControlledSearchable modelA search callback: Post::search('budget', fn ($client, $query, $options) => ...)->controlled()
A search that your server proxies for a front endAccess::guardSearch() in your route
One index per model, written by your own clientA Scout engine of your application: a subclass of Scout's Algolia, Meilisearch, Typesense or Turbopuffer engine, or an engine passed to Access::trustSearchEngine()
An index that is not the index of one Scout modelAccess::indexKeysOf() and Access::indexReaderKeys()
  • The options that a search callback receives hold the access filter of the reader for the index of this model: pass them on to your client, never rebuild them, and never apply them to another index, where keys of the same name may have another meaning. In a multi-search, each model takes the filter of its own search.
  • Never combine a filter of the package with yours by hand: filter() on a browser token is for logs and tests.
  • With your own Scout engine, the documents, their freshness, access:check and assertSearchAgrees() follow as for any engine.

An index of your own

An index that is not the index of one Scout model, such as a collection shared by several models, chunks of documents for a semantic search or an ingestion pipeline, takes its values from two read-only methods:

  • Access::indexKeysOf($rows) gives the values to store on the documents of each row;
  • Access::indexReaderKeys($reader, $model) gives the values that the search of a reader filters on.

A common use keeps the list in SQL with controlledFor() and asks the engine only for the rows that their content finds, filtered by the keys of the reader so that the documents the reader may not view do not take the top results:

use Lomkit\Access\Access;

// Indexing: the rows of one model at a time
$posts = Post::query()->whereKey($ids)->get();

foreach (Access::indexKeysOf($posts) as $id => $keys) {
    foreach ($chunks[$id] as $chunk) {
        $index->upsert([...$chunk, '_access' => $keys['_access'], '_boundary' => $keys['_boundary']]);
    }
}

// Searching
$keys = Access::indexReaderKeys($request->user(), Post::class);

if ($keys->isClosed()) {
    return [];
}

$hits = $index->search($query, filters: [
    ['_access', 'in', $keys->values()['_access']],
    ['_boundary', 'in', $keys->values()['_boundary']],
]);

$index stands for the client of your engine. Declare _access and _boundary as arrays of strings that the engine filters on, compared as whole values.

indexKeysOf()

  • It takes the saved rows of one model, as a collection or any iterable, and returns, by the key of each row, ['_access' => [...], '_boundary' => [...]]. A string key written as a decimal integer, such as "123", comes back as the int 123, as in any PHP array.
  • It loads the load relations of the keys once for all the rows, and never loads lazily.
  • It throws InvalidIndexRowException for rows of two models, a value that is not a model, an unsaved, deleted or soft-deleted row, and a key that is not an int or a string.

indexReaderKeys()

  • It returns a Lomkit\Access\Search\IndexReaderKeys, with model(), isClosed() and values(), the values of _access and _boundary as two lists of strings.
  • The keys of the reader are the ones controlledFor() lists the rows with: for view, in the current decision context. It takes no ability: one given after the model throws UnsearchableAbilityException.
  • A reader that controlled() would show an empty page (no reader, no perimeter that allows them, no key, or a null boundary value) is closed: isClosed() is true, and each field holds one value that no document carries, so a filter that ignores isClosed() still finds nothing. Skip the engine when it is true.

Matching

A document matches a reader when it shares at least one value with the reader in _access and at least one in _boundary.

  • Every open reader has values in both fields, and every document in _access, so a filter on both fields is always right: an unrestricted reader holds the value that every document of the model carries, and a model without a boundary gives the same _boundary value to its documents and its readers.
  • The _boundary of a document is empty when its row has no boundary value: no reader finds it.
  • The values are digests of 32 lowercase hexadecimal characters. The morph class of the model is part of each digest, so one collection holds several models without a field of its own: the values of one model never match another model's. A model whose morph class names another model, as a child model of single table inheritance does, throws SharedMorphClassException: give it a morph class of its own.
  • The values never match the documents of a ControlledSearchable model, even of the same model: never store or filter one kind with the other.
  • A change of the morph alias, or the rename of a class without one, changes every value: write the documents again.

Requirements

The model needs a control, not ControlledSearchable. Both methods throw:

  • MissingControlException without a control;
  • UnsearchableBoundaryException when the boundary class has no searchKeys();
  • PerimeterWithoutSearchKeysException when a perimeter that is neither unrestricted nor a ThroughParent declares no search keys, in the control or in the control of a parent, since the rows it grants would be missing from the index;
  • UnsearchableThroughParentException for a ThroughParent that delegates view to another ability of the parent, or whose parent has a boundary without a search form. The relation needs no inverse on a model that is not ControlledSearchable.

access:check does not check a model indexed only by your own pipeline: call both methods in a test, as assertIndexKeysAgree() does.

Freshness

The package reindexes nothing outside Scout. A document keeps the values it was written with, and a stale value can show a row to a reader who lost access until the document is written again. Compute the values again and rewrite the documents when what the keys read changes:

  • the columns that the row callbacks and the boundary read, and the models they load through load;
  • the models that a reindexWhen() watches, the parent of a ThroughParent and what changes its keys, and the pivots that a key reads;
  • the rules themselves, after a deployment, and the writes that Eloquent does not see.

Delete the documents of a row when it is deleted or soft deleted, and write them again when it is restored; a parent deleted or restored changes the keys of its children. Keeping the keys fresh lists what the package does for a Scout model in each case: your pipeline does the same for its index. The reader side needs nothing, since indexReaderKeys() computes the keys at each call.