Oihana Php Arango

SearchTrait uses trait:short, \oihana\traits\LazyTrait

This class is the generic Model class.

Constants

SEARCHABLE : string = 'searchable': The 'searchable' parameter key.

Properties

$searchable : array<string|int, mixed>|null: The searchable fields swept by the classic `?search=` `LIKE` (see {@see prepareSearch()}). A list of field names; an entry may instead be an array carrying its name under {@see Search::KEY} plus options such as {@see Search::REQUIRES} to gate the field by permission:
$searchOperator : string: The default operator combining the words of a `?search=` term **within a field** during the classic `LIKE` sweep ({@see prepareSearch()}): {@see \oihana\arango\db\enums\Logic::AND} (every word must be found in the field, order-independent) or {@see \oihana\arango\db\enums\Logic::OR} (the whole term matched as one substring — the default, backward-compatible).
$searchSeparators : string: The extra characters (beyond whitespace) that split a `?search=` term into words for the `AND` operator of the classic `LIKE` sweep ({@see prepareSearch()}).
$view : array<string|int, mixed>|null: The model-level ArangoSearch declaration (`AQL::VIEW` block, see {@see Search}).

Methods

bind() : string: Bind a value to an AQL query variable.
bindCollection() : string: Bind a collection name to an AQL query variable.
binder() : callable(mixed): string: Returns a binder over `$binds` — the callable {@see Arango::BINDER} carries down to the `alt` engine, so a parameter that arrived with a request becomes a bound value instead of text written into the query.
bindView() : string: Bind the model's declared View name (`AQL::VIEW` block, {@see Search::NAME}) to an AQL query variable — collection bind parameters (`@@view`) are valid for View names as well.
getViewLinks() : array<string, ArangoSearchLink>: Returns the desired per-collection link map of the declared View — the model's collection linked with {@see buildViewLink()} — or an empty map when the model has no collection.
getViewName() : string|null: Returns the name of the declared View ({@see Search::NAME} of the `AQL::VIEW` block), or `null` when the model declares none.
hasViewSearch() : bool: Indicates whether the View search is active: the model declares a named View (`AQL::VIEW` block) with at least one searched field, **and** the request carries a non-empty search term.
initializeSearchable() : static: Initialize the 'searchable' property.
initializeSearchOperator() : static: Initialize the `LIKE` sweep operator ({@see $searchOperator}) from the `Search::OPERATOR` init key. An explicit value is normalized to {@see Logic::AND} / {@see Logic::OR}; an absent key keeps the default ({@see Logic::OR}, backward-compatible).
initializeSearchSeparators() : static: Initialize the `LIKE` sweep word separators ({@see $searchSeparators}) from the `Search::SEPARATORS` init key. Accepts a string of characters or a list of characters (joined to a string); an absent key keeps the default (the hyphen). Only meaningful with the `AND` operator. See {@see Search::SEPARATORS}.
initializeView() : static: Initialize the model-level ArangoSearch declaration (`AQL::VIEW` block) and lazily provision the View, mirroring the collection provisioning of `initializeCollection()`: when the model is lazy and the declared View does not exist, it is created from the declaration — the searched fields (dotted paths supported) are linked on the model's collection with the declared {@see Search::ANALYZER}. An existing View is never altered — inspect and resynchronize explicitly with {@see viewDiff()} / {@see viewSync()} (or the `views` action of the `arangodb` command).
prepareSearch() : string|null: Prepare the searchable AQL conditions — the classic `?search=` `LIKE` sweep, a parenthesized `OR` of case-insensitive `LIKE()` predicates over every (permitted) searchable field, used when no View search is active.
prepareViewSearch() : string|null: Prepare the relevance-ranked `SEARCH` expression of an active View search, or `null` when the View search is inactive (no `AQL::VIEW` declaration, no searched fields, or no search term) — the caller then falls back to the classic `LIKE` sweep of {@see prepareSearch()}.
viewDiff() : DiffReport: Compares the model's View declaration with the server state and reports the differences, without touching anything.
viewSync() : DiffReport: Reconciles the model's View with its declaration: creates it when missing, repairs a drift with `updateProperties()` (the View stays available while the inverted index rebuilds in the background), and leaves {@see DiffStatus::IN_SYNC}, {@see DiffStatus::INVALID} or {@see DiffStatus::UNREACHABLE} reports untouched.
buildViewLink() : ArangoSearchLink: Builds the View link of the model's collection from the `AQL::VIEW` declaration: every searched field (dotted paths become nested fields) is indexed with its resolved Analyzer — the per-field {@see Search::ANALYZER} when declared, otherwise the View-level one.
buildViewSearchGroups() : array<string, array<string|int, string>>: Builds the per-Analyzer expression groups of the View search under the historical `OR` grammar : each comma-separated term is bound whole and matched in one shot per field (`doc.<field> IN TOKENS(@search_N, …)`, whose `IN` semantics already `OR` the term's tokens), plus the optional phrase and fuzzy branches. This is the exact grammar emitted when no field opts into {@see Search::OPERATOR} `AND` — see {@see prepareViewSearch()}.
buildViewSearchGroupsWithOperator() : array<string, array<string|int, string>>: Builds the per-Analyzer expression groups when at least one field opts into {@see Search::OPERATOR} `AND`. Each comma-separated term is split into words (whitespace) ; a field then combines those words with its resolved operator :
getSearchableSpecs() : array<string, array<string, mixed>>: Normalizes the model's `AQL::SEARCHABLE` list into a per-field specification map `field => [ (Search::REQUIRES => …)? ]`, the single source consumed by {@see prepareSearch()} (the `LIKE` sweep) and by the `searchable` fallback of {@see getViewFieldSpecs()}.
getViewFieldSpecs() : array<string, array<string, mixed>>: Normalizes the searched fields of the `AQL::VIEW` declaration into a per-field specification map `field => [ Search::BOOST => float, … ]` — the single source of truth from which {@see getViewSearchFields()} derives the boost map and {@see prepareViewSearch()} resolves the per-field options.
getViewSearchFields() : array<string, float>: Normalizes the searched fields into a `field => boost` map — a boost-only façade over {@see getViewFieldSpecs()}, used by {@see buildViewLink()} and {@see viewDiff()} which only care about the field paths and their weights.
ngramMatch() : string: Builds the `NGRAM_MATCH(doc.<field>, @term [, threshold], "<analyzer>")` core of a {@see Search::NGRAM} branch (without the surrounding boost). The threshold is inlined only when the field declares one, else the server default applies. Shared by the whole-term and the per-word emissions.
pushWholeTermField() : void: Pushes the whole-term match of one field onto the Analyzer groups — the base `doc.<field> IN TOKENS(@term, …)` (boosted when the field weight is not `1`), the optional exact-phrase bonus and the optional fuzzy branch, plus the {@see Search::NGRAM} branch when declared. This is the `OR`-grammar emission, shared by {@see buildViewSearchGroups()} (every field) and by the `OR` fields of {@see buildViewSearchGroupsWithOperator()}.
resolveFieldSearchSpec() : array{0: string[], 1: float, 2: int, 3: bool, 4: string}: Resolves the per-field search facets shared by both group builders : the Analyzers indexing the field (a per-field {@see Search::ANALYZER} overrides the View-level one, a single Analyzer normalized to a one-element list), the boost, the fuzzy tolerance and phrase bonus (a per-field value overrides the View-level default), and the `doc.<field>` accessor (with the `[*]` array marker stripped — the flat path already matches any element of the indexed array, and the `SEARCH` grammar rejects the expansion form).
splitSearchTermWords() : array<string|int, string>: Splits an `AND`-operator search term into its words, on whitespace plus the given extra separator characters ({@see Search::SEPARATORS}). Whitespace always splits; `$separators` adds literal characters (a string, or a list of characters joined to one), `null` falls back to the hyphen default, and an empty value splits on whitespace only. The extra characters are regex-escaped, so any punctuation is safe. Empty words are dropped.

SEARCHABLE

The 'searchable' parameter key.


    public
        string
    SEARCHABLE
    = 'searchable'

$searchable

The searchable fields swept by the classic `?search=` `LIKE` (see {@see prepareSearch()}). A list of field names; an entry may instead be an array carrying its name under {@see Search::KEY} plus options such as {@see Search::REQUIRES} to gate the field by permission:


        public
            array<string|int, mixed>|null
    $searchable
     = []

AQL::SEARCHABLE =>
[
    'name' ,                                                       // public
    [ Search::KEY => 'salary' , Search::REQUIRES => 'hr:salary' ], // gated
]

$searchOperator

The default operator combining the words of a `?search=` term **within a field** during the classic `LIKE` sweep ({@see prepareSearch()}): {@see \oihana\arango\db\enums\Logic::AND} (every word must be found in the field, order-independent) or {@see \oihana\arango\db\enums\Logic::OR} (the whole term matched as one substring — the default, backward-compatible).


        public
            string
    $searchOperator
     = \oihana\arango\db\enums\Logic::OR

Set once per model through the Search::OPERATOR init key. The View search carries its own operator inside the AQL::VIEW block (per field), see Search::OPERATOR.

$searchSeparators

The extra characters (beyond whitespace) that split a `?search=` term into words for the `AND` operator of the classic `LIKE` sweep ({@see prepareSearch()}).


        public
            string
    $searchSeparators
     = \oihana\enums\Char::HYPHEN

A string of characters; set once per model through the Search::SEPARATORS init key (a list of characters is normalized to a string at init). The default is the hyphen (-) so « Jean-Marc » splits like « Jean Marc »; an empty string keeps hyphenated codes whole. Only used in AND mode. See Search::SEPARATORS.

$view

The model-level ArangoSearch declaration (`AQL::VIEW` block, see {@see Search}).


        public
            array<string|int, mixed>|null
    $view
     = null

When present (with a Search::NAME), the ?search= parameter switches from the simple LIKE sweep to an index-accelerated, relevance-ranked SEARCH against the declared View.

bind()

Bind a value to an AQL query variable.


    public
                    bind(mixed $value[, array<string|int, mixed> &$binds = [] ][, string|null $to = null ]) : string

Parameters

$value : mixed: The value to bind to the query.
$binds : array<string|int, mixed> = []: Reference to the array of existing bind variables.
$to : string|null = null: Optional name of the bind variable. If null, a unique name is generated.

Return values

string —

The formatted bind variable (including the "@" prefix as needed) for use in the query.

bindCollection()

Bind a collection name to an AQL query variable.


    public
                    bindCollection([array<string|int, mixed> &$binds = [] ][, array<string|int, mixed> $init = [] ]) : string

Prepares a bind variable for a collection name. Uses the collection defined in $init or falls back to $this->collection if none is provided.

Parameters

$binds : array<string|int, mixed> = []

Reference to the array of existing bind variables. If null, a new array is used.

$init : array<string|int, mixed> = []

Optional initialization array with keys:

Arango::COLLECTION => the collection name to bind
Arango::NAME => optional bind variable name

Return values

string —

The formatted bind variable representing the collection.

binder()

Returns a binder over `$binds` — the callable {@see Arango::BINDER} carries down to the `alt` engine, so a parameter that arrived with a request becomes a bound value instead of text written into the query.


    public
                    binder([array<string|int, mixed>|null &$binds = null ]) : callable(mixed): string

⚠ Deliberately a function () use ( &$binds ) and not an arrow function: fn() captures by value, so the bind would land in a copy and the query would declare a parameter nothing ever fills. That mistake costs a 400 from the server and is invisible to any assertion made on the emitted AQL — which is why the closure is built here, once, rather than at each reading point.

Parameters

$binds : array<string|int, mixed>|null = null: Reference to the array of existing bind variables; a null is initialised in place.

Return values

callable(mixed): string —

A callable registering a value and returning its @name.

bindView()

Bind the model's declared View name (`AQL::VIEW` block, {@see Search::NAME}) to an AQL query variable — collection bind parameters (`@@view`) are valid for View names as well.


    public
                    bindView([array<string|int, mixed> &$binds = [] ]) : string

Parameters

$binds : array<string|int, mixed> = []: Reference to the array of existing bind variables.

Return values

string —

The formatted bind variable representing the View.

getViewLinks()

Returns the desired per-collection link map of the declared View — the model's collection linked with {@see buildViewLink()} — or an empty map when the model has no collection.


    public
                    getViewLinks() : array<string, ArangoSearchLink>

Return values

array<string, ArangoSearchLink>

getViewName()

Returns the name of the declared View ({@see Search::NAME} of the `AQL::VIEW` block), or `null` when the model declares none.


    public
                    getViewName() : string|null

Return values

string|null

hasViewSearch()

Indicates whether the View search is active: the model declares a named View (`AQL::VIEW` block) with at least one searched field, **and** the request carries a non-empty search term.


    public
                    hasViewSearch([array<string|int, mixed>|string|null $search = [] ]) : bool

Parameters

$search : array<string|int, mixed>|string|null = []: The $init array (reads Arango::SEARCH) or the search term itself.

Return values

bool

initializeSearchable()

Initialize the 'searchable' property.


    public
                    initializeSearchable([array<string|int, mixed> $init = [] ]) : static

Parameters

$init : array<string|int, mixed> = []

Return values

static

initializeSearchOperator()

Initialize the `LIKE` sweep operator ({@see $searchOperator}) from the `Search::OPERATOR` init key. An explicit value is normalized to {@see Logic::AND} / {@see Logic::OR}; an absent key keeps the default ({@see Logic::OR}, backward-compatible).


    public
                    initializeSearchOperator([array<string|int, mixed> $init = [] ]) : static

Parameters

$init : array<string|int, mixed> = []

Return values

static

initializeSearchSeparators()

Initialize the `LIKE` sweep word separators ({@see $searchSeparators}) from the `Search::SEPARATORS` init key. Accepts a string of characters or a list of characters (joined to a string); an absent key keeps the default (the hyphen). Only meaningful with the `AND` operator. See {@see Search::SEPARATORS}.


    public
                    initializeSearchSeparators([array<string|int, mixed> $init = [] ]) : static

Parameters

$init : array<string|int, mixed> = []

Return values

static

initializeView()

Initialize the model-level ArangoSearch declaration (`AQL::VIEW` block) and lazily provision the View, mirroring the collection provisioning of `initializeCollection()`: when the model is lazy and the declared View does not exist, it is created from the declaration — the searched fields (dotted paths supported) are linked on the model's collection with the declared {@see Search::ANALYZER}. An existing View is never altered — inspect and resynchronize explicitly with {@see viewDiff()} / {@see viewSync()} (or the `views` action of the `arangodb` command).


    public
                    initializeView([array<string|int, mixed> $init = [] ]) : static

Parameters

$init : array<string|int, mixed> = []

Return values

static

prepareSearch()

Prepare the searchable AQL conditions — the classic `?search=` `LIKE` sweep, a parenthesized `OR` of case-insensitive `LIKE()` predicates over every (permitted) searchable field, used when no View search is active.


    public
                    prepareSearch([array<string|int, mixed>|string|null $search = [] ][, array<string|int, mixed>|null &$binds = null ][, array<string|int, mixed>|null $searchable = null ][, string $docRef = AQL::DOC ]) : string|null

The comma-separated terms and the fields are always OR-ed. How the words of a single term combine within a field follows the model's $searchOperator (Search::OPERATOR init key):

Logic::OR (default) matches the whole term as one substring (LIKE(doc.name, "%marc fourcade%")), so it needs the words adjacent and in order — the historical, byte-for-byte grammar;
Logic::AND splits the term on whitespace and requires every word in the same field (( LIKE(doc.name, "%marc%") && LIKE(doc.name, "%fourcade%") )), order-independent.

Parameters

$search : array<string|int, mixed>|string|null = []
$binds : array<string|int, mixed>|null = null
$searchable : array<string|int, mixed>|null = null
$docRef : string = AQL::DOC

Return values

string|null

prepareViewSearch()

Prepare the relevance-ranked `SEARCH` expression of an active View search, or `null` when the View search is inactive (no `AQL::VIEW` declaration, no searched fields, or no search term) — the caller then falls back to the classic `LIKE` sweep of {@see prepareSearch()}.


    public
                    prepareViewSearch([array<string|int, mixed>|string|null $search = [] ][, array<string|int, mixed>|null &$binds = null ][, string $docRef = AQL::DOC ]) : string|null

The grammar keeps the ?search= contract (comma-separated terms, OR everywhere, values bound — never inlined). Per term and per field:

the base match doc.<field> IN TOKENS(@search_N, "<analyzer>") (both sides analyzed), weighted by BOOST(…, <boost>) when the field boost differs from 1; a field reaching into an array of objects has its [*] expansion marker stripped here (doc.contactPoints.email IN …, not doc.contactPoints[*].email): the SEARCH grammar rejects array expansion, and the flat path already matches any element of the indexed array — see buildViewLink();
with a per-field or View-level Search::PHRASE, an exact-phrase bonus BOOST(PHRASE(doc.<field>, @search_N), <boost × 2>); a field may override the View-level flag (an explicit false opts that field out);
with a per-field or View-level Search::FUZZY > 0, a typo-tolerant LEVENSHTEIN_MATCH(doc.<field>, @search_N, <fuzzy>); a field may override the View-level tolerance — an explicit 0 opts that field out while the rest stays fuzzy.

Field expressions are grouped by their resolved Analyzer (a field may override the View-level Search::ANALYZER) and each group is wrapped in its own ANALYZER(…, "<analyzer>"), the groups being OR-ed together. With a single Analyzer the output is a single ANALYZER(…) wrap, byte for byte the classic form.

Search::REQUIRES gates the search by the request authorizer (Arango::AUTHORIZER, see isAuthorized()) at two levels: on the AQL::VIEW block it gates the whole search, inside a field entry it gates that field; the two combine with AND (fail-open without an authorizer). If the View-level gate is denied, or permissions remove every field, the expression is false — the search matches nothing and never falls back to searching everything.

When the request carries an active language (Arango::LANG, the ?lang= parameter), localized fields (those declaring Search::LANG) join the SEARCH only when their locale matches; locale-agnostic fields always do. An active language matching no field is ignored — the SEARCH is never emptied (within the permitted set).

Parameters

$search : array<string|int, mixed>|string|null = []: The $init array (reads Arango::SEARCH) or the search term itself.
$binds : array<string|int, mixed>|null = null: Bind variables, populated by reference.
$docRef : string = AQL::DOC: The document variable the fields hang off.

Return values

string|null —

The SEARCH expression, or null when the View search is inactive.

viewDiff()

Compares the model's View declaration with the server state and reports the differences, without touching anything.


    public
                    viewDiff() : DiffReport

On top of the field/analyzer drift detected by ViewManagementTrait::viewDiff(), the model-level report validates the coherence of the declaration itself: a missing Search::NAME, no searched field, no collection, an analyzer or a collection unknown to the server all resolve to DiffStatus::INVALID — such a View is never created nor synchronized automatically.

Return values

DiffReport

viewSync()

Reconciles the model's View with its declaration: creates it when missing, repairs a drift with `updateProperties()` (the View stays available while the inverted index rebuilds in the background), and leaves {@see DiffStatus::IN_SYNC}, {@see DiffStatus::INVALID} or {@see DiffStatus::UNREACHABLE} reports untouched.


    public
                    viewSync() : DiffReport

Return values

DiffReport —

The viewDiff() report, with $applied set when the View has been created or updated.

buildViewLink()

Builds the View link of the model's collection from the `AQL::VIEW` declaration: every searched field (dotted paths become nested fields) is indexed with its resolved Analyzer — the per-field {@see Search::ANALYZER} when declared, otherwise the View-level one.


    protected
                    buildViewLink() : ArangoSearchLink

A field may reach a sub-field of an array of objects with the [*] expansion marker (e.g. contactPoints[*].email). The marker is stripped here (stripArrayExpansion()) so the link declares the flat nested path (contactPoints → email): ArangoSearch (Community) descends into the array on its own — no Enterprise nested flag is needed for this (non-correlated) search. The matching query strips the marker too — the SEARCH grammar rejects array expansion, see prepareViewSearch(). The stripped path is validated (assertAttributeName()) to reject a malformed declaration early.

A field whose resolved Analyzer equals the link-level default is emitted as an empty node (no analyzers key) rather than spelling the default out: the server normalizes a field whose analyzers equal the link default to } (the redundant mention is dropped), so spelling it out would make the declared form differ forever from the stored one and viewDiff() would report a permanent false drift. The link carries no link-level analyzers, so its default is the server default (identity) — computed here rather than hard-coded so the elimination stays correct if a link-level analyzer is introduced later.

Return values

ArangoSearchLink

buildViewSearchGroups()

Builds the per-Analyzer expression groups of the View search under the historical `OR` grammar : each comma-separated term is bound whole and matched in one shot per field (`doc.<field> IN TOKENS(@search_N, …)`, whose `IN` semantics already `OR` the term's tokens), plus the optional phrase and fuzzy branches. This is the exact grammar emitted when no field opts into {@see Search::OPERATOR} `AND` — see {@see prepareViewSearch()}.


    protected
                    buildViewSearchGroups(string $search, array<string|int, mixed>|null &$binds, string $docRef, array<string|int, mixed> $fields, string $modelAnalyzer, bool $globalPhrase, int $globalFuzzy) : array<string, array<string|int, string>>

Parameters

$search : string: The raw ?search= term string (comma-separated).
$binds : array<string|int, mixed>|null: Bind variables, populated by reference.
$docRef : string: The document variable the fields hang off.
$fields : array<string|int, mixed>: The resolved, gated per-field specs.
$modelAnalyzer : string: The View-level Analyzer (a per-field override is respected).
$globalPhrase : bool: The View-level phrase-bonus default.
$globalFuzzy : int: The View-level Levenshtein tolerance default.

Return values

array<string, array<string|int, string>> —

Analyzer name => list of expressions, in first-seen order.

buildViewSearchGroupsWithOperator()

Builds the per-Analyzer expression groups when at least one field opts into {@see Search::OPERATOR} `AND`. Each comma-separated term is split into words (whitespace) ; a field then combines those words with its resolved operator :


    protected
                    buildViewSearchGroupsWithOperator(string $search, array<string|int, mixed>|null &$binds, string $docRef, array<string|int, mixed> $fields, string $modelAnalyzer, bool $globalPhrase, int $globalFuzzy, string $globalOperator[, string|array<string|int, mixed>|null $separators = null ]) : array<string, array<string|int, string>>

OR (default) reproduces the whole-term match (pushWholeTermField()), so a mixed View keeps its loose fields loose ;
AND requires every word in the same field (( doc.<field> IN TOKENS(@w0, …) && doc.<field> IN TOKENS(@w1, …) )), the fuzzy branch (when enabled) widening each word (( … IN TOKENS(@w, …) || LEVENSHTEIN_MATCH(…, @w, …) )), and the phrase bonus (when enabled) kept on the whole term as a ranking boost OR-ed on top — an adjacency match implies the words, so the matched set is unchanged.

The whole-term bind is materialized only when a field needs it (an OR field, or an AND field carrying the phrase bonus), never left dangling. Groups are OR-ed between fields and between terms by prepareViewSearch().

Parameters

$search : string: The raw ?search= term string (comma-separated).
$binds : array<string|int, mixed>|null: Bind variables, populated by reference.
$docRef : string: The document variable the fields hang off.
$fields : array<string|int, mixed>: The resolved, gated per-field specs.
$modelAnalyzer : string: The View-level Analyzer (a per-field override is respected).
$globalPhrase : bool: The View-level phrase-bonus default.
$globalFuzzy : int: The View-level Levenshtein tolerance default.
$globalOperator : string: The View-level operator default (Logic::AND / Logic::OR).
$separators : string|array<string|int, mixed>|null = null: The extra AND word separators (Search::SEPARATORS); null = the hyphen default.

Return values

array<string, array<string|int, string>> —

Analyzer name => list of expressions, in first-seen order.

getSearchableSpecs()

Normalizes the model's `AQL::SEARCHABLE` list into a per-field specification map `field => [ (Search::REQUIRES => …)? ]`, the single source consumed by {@see prepareSearch()} (the `LIKE` sweep) and by the `searchable` fallback of {@see getViewFieldSpecs()}.


    protected
                    getSearchableSpecs([array<string|int, mixed>|null $searchable = null ]) : array<string, array<string, mixed>>

Each entry of the list is either:

a plain field name (string) → a public field, no options;
an array carrying the field name under Search::KEY plus its options (e.g. Search::REQUIRES) → keeps the list homogeneous (no mixed numeric/string keys). The map form field => [ … ] is also tolerated (the field falls back to the entry key).

Parameters

$searchable : array<string|int, mixed>|null = null: An explicit list overriding the model's searchable property.

Return values

array<string, array<string, mixed>>

getViewFieldSpecs()

Normalizes the searched fields of the `AQL::VIEW` declaration into a per-field specification map `field => [ Search::BOOST => float, … ]` — the single source of truth from which {@see getViewSearchFields()} derives the boost map and {@see prepareViewSearch()} resolves the per-field options.


    protected
                    getViewFieldSpecs() : array<string, array<string, mixed>>

Search::FIELDS entries accept a numeric boost shorthand or an array carrying Search::BOOST, Search::FUZZY, Search::ANALYZER, Search::LANG, Search::PHRASE and Search::REQUIRES; when the declaration has no fields, the model's searchable list is used with a neutral boost. A per-field option is kept in the spec only when it is explicitly declared — an absent key means "inherit the View-level default", which prepareViewSearch() resolves so that an explicit value (0 included) overrides the global tolerance.

Return values

array<string, array<string, mixed>>

getViewSearchFields()

Normalizes the searched fields into a `field => boost` map — a boost-only façade over {@see getViewFieldSpecs()}, used by {@see buildViewLink()} and {@see viewDiff()} which only care about the field paths and their weights.


    protected
                    getViewSearchFields() : array<string, float>

Return values

array<string, float>

ngramMatch()

Builds the `NGRAM_MATCH(doc.<field>, @term [, threshold], "<analyzer>")` core of a {@see Search::NGRAM} branch (without the surrounding boost). The threshold is inlined only when the field declares one, else the server default applies. Shared by the whole-term and the per-word emissions.


    protected
                    ngramMatch(array<string|int, mixed> $spec, string $path, string $term) : string

Parameters

$spec : array<string|int, mixed>: The field spec (must carry a Search::NGRAM entry).
$path : string: The doc.<field> accessor.
$term : string: The bound term (@search_N or @search_N_M).

Return values

string —

The NGRAM_MATCH(…) expression.

pushWholeTermField()

Pushes the whole-term match of one field onto the Analyzer groups — the base `doc.<field> IN TOKENS(@term, …)` (boosted when the field weight is not `1`), the optional exact-phrase bonus and the optional fuzzy branch, plus the {@see Search::NGRAM} branch when declared. This is the `OR`-grammar emission, shared by {@see buildViewSearchGroups()} (every field) and by the `OR` fields of {@see buildViewSearchGroupsWithOperator()}.


    protected
                    pushWholeTermField(array<string|int, mixed> &$groups, array<string|int, mixed> $spec, string $path, string $term, array<string|int, mixed> $analyzers, float $weight, bool $phrase, int $fuzzy) : void

Parameters

$groups : array<string|int, mixed>: Analyzer name => list of expressions, mutated by reference.
$spec : array<string|int, mixed>: The resolved field spec.
$path : string: The doc.<field> accessor.
$term : string: The bound whole term (@search_N).
$analyzers : array<string|int, mixed>: The Analyzers indexing the field (IN TOKENS side).
$weight : float: The field boost.
$phrase : bool: Whether to add the exact-phrase bonus.
$fuzzy : int: The Levenshtein tolerance (0 disables the branch).

resolveFieldSearchSpec()

Resolves the per-field search facets shared by both group builders : the Analyzers indexing the field (a per-field {@see Search::ANALYZER} overrides the View-level one, a single Analyzer normalized to a one-element list), the boost, the fuzzy tolerance and phrase bonus (a per-field value overrides the View-level default), and the `doc.<field>` accessor (with the `[*]` array marker stripped — the flat path already matches any element of the indexed array, and the `SEARCH` grammar rejects the expansion form).


    protected
                    resolveFieldSearchSpec(array<string|int, mixed> $spec, int|string $field, string $modelAnalyzer, bool $globalPhrase, int $globalFuzzy, string $docRef) : array{0: string[], 1: float, 2: int, 3: bool, 4: string}

Parameters

$spec : array<string|int, mixed>: The resolved field spec.
$field : int|string: The field key (the dotted path, [*] allowed).
$modelAnalyzer : string: The View-level Analyzer.
$globalPhrase : bool: The View-level phrase-bonus default.
$globalFuzzy : int: The View-level Levenshtein tolerance default.
$docRef : string: The document variable the field hangs off.

Return values

array{0: string[], 1: float, 2: int, 3: bool, 4: string} —

[ analyzers, weight, fuzzy, phrase, path ].

splitSearchTermWords()

Splits an `AND`-operator search term into its words, on whitespace plus the given extra separator characters ({@see Search::SEPARATORS}). Whitespace always splits; `$separators` adds literal characters (a string, or a list of characters joined to one), `null` falls back to the hyphen default, and an empty value splits on whitespace only. The extra characters are regex-escaped, so any punctuation is safe. Empty words are dropped.


    protected
                    splitSearchTermWords(string $term[, string|array<string|int, mixed>|null $separators = null ]) : array<string|int, string>

Parameters

$term : string: The raw comma-term (may hold several words).
$separators : string|array<string|int, mixed>|null = null: The extra separator characters (string / list / null=default hyphen).

Return values

array<string|int, string> —

The non-empty words, in order.

SearchTrait uses trait:short, \oihana\traits\LazyTrait

Table of Contents

Constants

Properties

Methods

Constants

SEARCHABLE

Properties

$searchable

$searchOperator

$searchSeparators

$view

Methods

bind()

Parameters

Tags

Return values

bindCollection()

Parameters

Tags

Return values

binder()

Parameters

Return values

bindView()

Parameters

Tags

Return values

getViewLinks()

Tags

Return values

getViewName()

Return values

hasViewSearch()

Parameters

Tags

Return values

initializeSearchable()

Parameters

Return values

initializeSearchOperator()

Parameters

Return values

initializeSearchSeparators()

Parameters

Return values

initializeView()

Parameters

Tags

Return values

prepareSearch()

Parameters

Tags

Return values

prepareViewSearch()

Parameters

Tags

Return values

viewDiff()

Tags

Return values

viewSync()

Tags

Return values

buildViewLink()

Tags

Return values

buildViewSearchGroups()

Parameters

Tags

Return values

buildViewSearchGroupsWithOperator()

Parameters

Tags

Return values

getSearchableSpecs()

Parameters

Return values

getViewFieldSpecs()

Tags