Contao Utils Bundle

SearchVectorQuery
in package

Builds search conditions against the search vector of a table.

Query syntax: commas separate alternatives (OR), the words of one alternative must all match (AND), words wrapped in double quotes must match as a phrase. Words match as substrings of the stored stems, so compounds are found by their parts ("Württemberg" finds "Baden-Württemberg").

The search is stemmed in the language the records were indexed in. For tables with a language field it defaults to the language of the current request, pass $locale to search in another language.

Matches can be sorted by relevance: a word at the start of a word scores 1, a word that is a whole word 1 more, and the words of an alternative standing next to each other in the order of the search score 2 per word on top. Words of quoted phrases count individually. So "Dresdner Stollen" ranks records with both words in a row before records with the words in different places, and "Honig" ranks "Honig" before "Imkerhonig".

Table of Contents

Constants

LIKE_ESCAPE  = '!'
Escape character of the LIKE patterns. Unlike a backslash, it needs no escaping in SQL string literals and is not a default escape character anywhere, so the explicit ESCAPE clause works the same on MySQL, SQLite and PostgreSQL.

Properties

$configurationResolver  : SearchVectorConfigurationResolver
$connection  : Connection

Methods

__construct()  : mixed
apply()  : bool
Adds the search condition to the query builder with andWhere().
createCondition()  : array{0: string, 1: array}|null
Creates the search condition as SQL with named parameters, for query abstractions other than the Doctrine query builder.
createModelCriteria()  : array{0: list, 1: list}
Creates columns and values for Contao model finders, e.g. `ExampleModel::findBy($columns, $values)`.
createRelevance()  : array{0: string, 1: array}|null
Creates the relevance of the search as SQL with named parameters, for query abstractions other than the Doctrine query builder. The expression returns a number, higher is more relevant, see the class description.
orderByRelevance()  : bool
Sorts the query by relevance with addOrderBy(), see the class description. Call it before adding other sort orders, which then sort records of the same relevance. Use it together with apply(), it does not filter.
buildCondition()  : string
buildRelevance()  : string
Every word of the vector is preceded and followed by a space, so " word" matches at the start of a word and " word " a whole word.
createNamedPlaceholder()  : callable(string): string
escapeLike()  : string
Escapes the LIKE wildcards in a term, which custom normalizers or stemmers might produce.
prepare()  : array{0: string, 1: list>}

Constants

LIKE_ESCAPE

Escape character of the LIKE patterns. Unlike a backslash, it needs no escaping in SQL string literals and is not a default escape character anywhere, so the explicit ESCAPE clause works the same on MySQL, SQLite and PostgreSQL.

private mixed LIKE_ESCAPE = '!'

Properties

$configurationResolver read-only

private SearchVectorConfigurationResolver $configurationResolver

Methods

__construct()

public __construct(Connection $connection, SearchVectorConfigurationResolver $configurationResolver) : mixed
Parameters
$connection : Connection
$configurationResolver : SearchVectorConfigurationResolver

apply()

Adds the search condition to the query builder with andWhere().

public apply(QueryBuilder $queryBuilder, string $table, string $search[, string|null $alias = null ][, string|null $locale = null ]) : bool
Parameters
$queryBuilder : QueryBuilder
$table : string
$search : string
$alias : string|null = null

The table alias used in the query, defaults to the table name

$locale : string|null = null

The language of the search, see SearchVectorConfigurationResolver::getSearchLocale()

Return values
bool —

False if the search contains no searchable words. The query builder is not changed then.

createCondition()

Creates the search condition as SQL with named parameters, for query abstractions other than the Doctrine query builder.

public createCondition(string $table, string $search[, string|null $alias = null ][, string|null $locale = null ][, string $parameterPrefix = 'searchVector' ]) : array{0: string, 1: array}|null
Parameters
$table : string
$search : string
$alias : string|null = null

The table alias used in the query, defaults to the table name

$locale : string|null = null

The language of the search, see SearchVectorConfigurationResolver::getSearchLocale()

$parameterPrefix : string = 'searchVector'

The prefix of the parameter names, use different prefixes to combine several conditions in one query

Return values
array{0: string, 1: array}|null —

The condition and its parameters by name (without colon), null if the search contains no searchable words

createModelCriteria()

Creates columns and values for Contao model finders, e.g. `ExampleModel::findBy($columns, $values)`.

public createModelCriteria(string $table, string $search[, string|null $locale = null ]) : array{0: list, 1: list}
Parameters
$table : string
$search : string
$locale : string|null = null

The language of the search, see SearchVectorConfigurationResolver::getSearchLocale()

Return values
array{0: list, 1: list} —

Both lists are empty if the search contains no searchable words. Check that before querying, an empty list matches every record.

createRelevance()

Creates the relevance of the search as SQL with named parameters, for query abstractions other than the Doctrine query builder. The expression returns a number, higher is more relevant, see the class description.

public createRelevance(string $table, string $search[, string|null $alias = null ][, string|null $locale = null ][, string $parameterPrefix = 'searchVectorRelevance' ]) : array{0: string, 1: array}|null
Parameters
$table : string
$search : string
$alias : string|null = null

The table alias used in the query, defaults to the table name

$locale : string|null = null

The language of the search, see SearchVectorConfigurationResolver::getSearchLocale()

$parameterPrefix : string = 'searchVectorRelevance'

The prefix of the parameter names, use different prefixes to combine several expressions in one query

Return values
array{0: string, 1: array}|null —

The expression and its parameters by name (without colon), null if the search contains no searchable words

orderByRelevance()

Sorts the query by relevance with addOrderBy(), see the class description. Call it before adding other sort orders, which then sort records of the same relevance. Use it together with apply(), it does not filter.

public orderByRelevance(QueryBuilder $queryBuilder, string $table, string $search[, string|null $alias = null ][, string|null $locale = null ]) : bool
Parameters
$queryBuilder : QueryBuilder
$table : string
$search : string
$alias : string|null = null

The table alias used in the query, defaults to the table name

$locale : string|null = null

The language of the search, see SearchVectorConfigurationResolver::getSearchLocale()

Return values
bool —

False if the search contains no searchable words. The query builder is not changed then.

buildCondition()

private buildCondition(string $column, array<int, array<int, string>> $phrases, callable(string): string $placeholder) : string
Parameters
$column : string
$phrases : array<int, array<int, string>>
$placeholder : callable(string): string

Receives the LIKE pattern and returns its placeholder

Return values
string

buildRelevance()

Every word of the vector is preceded and followed by a space, so " word" matches at the start of a word and " word " a whole word.

private buildRelevance(string $column, array<int, array<int, string>> $alternatives, callable(string): string $placeholder) : string

Scores the words of each alternative, not its filter terms: the words of a quoted phrase count individually, and repeated words stay in the sequence that must stand in a row.

Parameters
$column : string
$alternatives : array<int, array<int, string>>

The words of each alternative, see Tokenizer::parseQueryWords()

$placeholder : callable(string): string

Receives the LIKE pattern and returns its placeholder

Return values
string

createNamedPlaceholder()

private createNamedPlaceholder(string $parameterPrefix, array<string, string>|null &$parameters) : callable(string): string
Parameters
$parameterPrefix : string
$parameters : array<string, string>|null

Receives the parameters by name

Return values
callable(string): string

escapeLike()

Escapes the LIKE wildcards in a term, which custom normalizers or stemmers might produce.

private escapeLike(string $term) : string
Parameters
$term : string
Return values
string

prepare()

private prepare(string $table, string $search, string|null $alias, string|null $locale[, bool $words = false ]) : array{0: string, 1: list>}
Parameters
$table : string
$search : string
$alias : string|null
$locale : string|null
$words : bool = false

Whether to parse the words of each phrase for the relevance (Tokenizer::parseQueryWords()) instead of the filter terms (Tokenizer::parseQuery())

Return values
array{0: string, 1: list>} —

The quoted column and the parsed search phrases


        

        
    




    

    

                                

                

                                
    

        On this page

        
    


                

                            

            

    

        

            
Search results