Engines
Index settings
Declare _access and _boundary as filterable in the settings of each searchable model. Access::searchFilterables() returns ['_access', '_boundary']:
// config/scout.php
'meilisearch' => [
'index-settings' => [
Post::class => [
'filterableAttributes' => [...Access::searchFilterables(), 'status'],
],
],
],
// config/scout.php
'typesense' => [
'model-settings' => [
Post::class => [
'collection-schema' => [
'fields' => [
// your fields
['name' => '_access', 'type' => 'string[]'],
['name' => '_boundary', 'type' => 'string[]'],
],
],
],
],
],
// config/scout.php
'algolia' => [
'index-settings' => [
Post::class => [
'attributesForFaceting' => ['filterOnly(_access)', 'filterOnly(_boundary)'],
],
],
],
// config/scout.php, the schema that Scout sends with each write
'turbopuffer' => [
'model-settings' => [
Post::class => [
'schema' => [
'_access' => ['type' => '[]string', 'filterable' => true],
'_boundary' => ['type' => '[]string', 'filterable' => true],
],
],
],
],
Then push the settings and index the documents:
php artisan scout:sync-index-settings
php artisan scout:import "App\Models\Post"
Turbopuffer sets the type of an attribute on its first write and cannot change it: declare the schema before the first write, or delete the namespace (scout:flush) and import it again.
Why digests
Each key leaves the application as a digest of 32 lowercase hexadecimal characters. Search engines do not compare indexed strings verbatim: Typesense drops symbols such as . and _ and cuts values at 100 characters, so author.1.23 would match author.12.3, and Meilisearch cuts a stored value at 468 bytes. A digest has a fixed length and no symbol, so every engine compares it exactly, and the engines need no setting for it: no symbols_to_index or token_separators on Typesense.
Supported engines
| Engine | Controlled search |
|---|---|
| Algolia, Meilisearch, Typesense | Filtered with whereIn on _access and _boundary |
| Turbopuffer | Filtered with its native ContainsAny operator |
database | The control's SQL inside the search query, without keys |
null | Accepted: it finds nothing |
collection | Refused: it paginates before it filters |
| Any other engine | Refused, unless you trust it |
The package checks the engines with instanceof, so a subclass of a supported engine is trusted as it is.
...$options does in the multi-search engine below. The package does not check what a subclass overrides.The database engine
The database engine searches with SQL: a controlled search applies the control's SQL inside the search query, through Scout's query() callback, which still runs the callback you pass to query(). No keys are computed for it. It is also the engine for your tests: the collection engine throws UnsupportedSearchEngineException on a controlled search.
Trusting another engine
Any other engine throws UnsupportedSearchEngineException: an engine that ignored whereIn would return every document. When your engine filters correctly, trust it in the boot() method of a service provider:
Access::trustSearchEngine(ElasticsearchEngine::class);
A trusted engine must:
- render
whereInon an array attribute as "at least one element in common", and AND the fields together,_boundarywith_access; - compare each value as a whole string;
- apply the
whereInsof the search on every read path:get(),paginate(),simplePaginate(),keys(),raw()andcursor(); - write
scoutMetadata()with each document, as the Meilisearch and Typesense engines do, or no key is indexed; - for laravel-rest-api, have an engine profile that implements
MatchesStringLists, or its searches throwUnsupportedRestSearchException.
It needs nothing for a reader who reaches nothing: the package never calls the engine for them.
Your own filters
Your where() and whereIn() clauses narrow a controlled search on every engine. Filters passed through options() behave differently on each engine:
- Typesense. A
filter_byfromoptions()ortypesenseSearchParameters()is combined with the access filter as(<your filter_by>) && (<access filter>), on every read path and in a search callback, so it can only narrow the results. Your filter must end on its own: a filter that is not a string, or that leaves a backtick-quoted value, a geo filter, a reference or an object filter open, throwsUncombinableSearchFilterException. - Meilisearch and Algolia. Scout sends its own filter, built from the
where()andwhereIn()clauses and the access filter, in place of thefilter(Meilisearch) orfilters(Algolia) ofoptions(). Put your conditions inwhere()andwhereIn(). Algolia still ANDs thefacetFiltersandnumericFiltersofoptions(). - Turbopuffer. The access filter is added to the native filters of
options['filters'], joined withAnd, and applied again when the search runs, so a lateroptions()orwhereIn()cannot remove it.
Some engine features would show documents that the filter does not keep, so a controlled search turns them off:
- Typesense:
filter_curated_hitsis alwaystrue, so pinned hits and curated documents go through the filter. Natural-language search (nl_query) throwsNaturalLanguageSearchException; do not use a preset that turns it on for a controlled model. - Algolia:
enableRulesandenableABTestare alwaysfalse, since a rule can promote records whatever the filters and an A/B test can answer from another index.
An unrestricted reader without a boundary has no access filter: their search is sent as you wrote it, with these features on.
Readers with many keys
A reader with many keys sends a long filter. Scout's Typesense engine searches with a GET request, and Typesense refuses a query string longer than 4,000 encoded characters with HTTP 400: the search fails, it never shows a row too many. Each key costs about 36 encoded characters, so a search holds about 100 keys, _boundary and _access together. The keys through a parent multiply.
When your readers hold more, search through Typesense's multi_search endpoint, which takes the filter in a POST body, with a subclass of Scout's engine registered under the typesense driver. It needs Scout 11.7 or later:
use Laravel\Scout\Builder;
use Laravel\Scout\EngineManager;
use Laravel\Scout\Engines\TypesenseEngine;
use Typesense\Client;
use Typesense\Documents;
class MultiSearchTypesenseEngine extends TypesenseEngine
{
protected function executeSearch(Builder $builder, Documents $documents, array $options): mixed
{
$results = $this->typesense->getMultiSearch()->perform([
'searches' => [[...$options, 'collection' => $builder->index ?? $builder->model->searchableAs()]],
]);
$result = $results['results'][0] ?? [];
if (isset($result['error'])) {
throw $this->marshalMultiSearchException($result);
}
return $result;
}
}
// In the boot() method of a service provider
resolve(EngineManager::class)->extend('typesense', fn () => new MultiSearchTypesenseEngine(
new Client(config('scout.typesense.client-settings')),
config('scout.typesense.max_total_results', 1000),
config('scout.typesense'),
));
The subclass is trusted without Access::trustSearchEngine(), since it passes the options it receives, the access filter included, to the engine. Its browser tokens keep working, and it covers the searches of laravel-rest-api too. Algolia accepts at most 1,000 filters in a query, so a reader with more keys than that cannot search an Algolia index.
The engine is the only barrier
A controlled search shows what the index says. An index that lags behind can show a row that just left the reader's perimeters until the row is indexed again, and documents keep the keys of a former rule until they are reindexed. Keeping the keys fresh covers what reindexes them.
Search overview
A controlled Laravel Scout search keeps, in one engine query, the documents the reader may view: each document carries the keys that open it.
Keeping the keys fresh
Search keys are computed at indexing time. Declare with reindexWhen() and ReindexesSearch what reindexes the documents when the data behind them changes.