Hosmel Quintana
Introduction
Installation
Configuration
Basic usage
Defining a Search
Fields and Columns
Operators and Values
Text and Wildcards
Free-Text Terms
Complements and Nullable Columns
Dates and Time Zones
JSON Columns
Relations
Aggregates
Scopes and Predicates
Full-Text Search
Directives and Sorting
Field Authorization
Validation Errors
Advanced usage
Custom Resolvers
Form Request Validation
View on GitHub

Text and Wildcards

Choose exact, prefix, or substring matching, use wildcard patterns, and index the searched text.

String fields match whole values, ignoring case. They can also match a prefix or a substring, or take wildcard patterns from the query.

Choose a matching mode

String fields use exact, case-insensitive matching by default. Call prefix() or contains() to change unquoted equality values:

php
use HosmelQ\SearchSyntaxParser\Laravel\Field;

$fields = [
    Field::string('sku')->prefix(),
    Field::string('name')->contains(),
];
QueryMatch
sku:ABCStarts with ABC.
name:mugContains mug.
name:"mug"Equals mug.
name:mug,"tea cup"Contains mug or equals tea cup.

Quotes force exact equality, including inside a list. Ordering and range operators keep their comparison behavior. Use words() to search words and phrases within stored text.

Use wildcard patterns

An unquoted asterisk marks a wildcard:

text
name:Ana*
name:A*Bell
name:!=Ana*
name:"Ana Bell"*

Patterns match the whole stored value. They are not wrapped in additional wildcards. Quoted asterisks stay literal, and field:* is an existence check.

Leading wildcards are disabled by default. Enable them per field and optionally require a minimum literal length:

php
use HosmelQ\SearchSyntaxParser\Laravel\Field;

$field = Field::string('name')->allowLeadingWildcards()->minWildcardLength(3);

The core escapes literal %, _, and !. SQL LIKE predicates use ESCAPE '!', and backslashes stay literal, including with MySQL's NO_BACKSLASH_ESCAPES mode. Search values are parameter bindings.

Case and accents

DatabaseString comparison
MySQL and MariaDBUses the column or expression collation. Choose a case-insensitive collation such as utf8mb4_unicode_ci. Accent matching follows that collation.
PostgreSQLCompares lower(cast(target as text)) with lower(?). Case folding follows the database locale.
SQLiteUses COLLATE NOCASE and case-insensitive LIKE. Built-in folding covers ASCII; keep case_sensitive_like disabled.

Quoted values follow the same rules. MySQL and MariaDB JSON strings are explicitly folded to lowercase because extracted text has a binary collation; they ignore case but distinguish accents.

Numeric comparisons do not fold text. UUID, ULID, in(), and enum() values are normalized by the core and compared directly, so a native PostgreSQL UUID column can use its ordinary index.

Index the searched expression

Contains matching and ordinary free-text terms use %term% patterns, which generally cannot use a B-tree index for lookup. PostgreSQL's pg_trgm extension can index these searches with GIN or GiST.

PostgreSQL string predicates need an index on the same lower(cast(... as text)) expression. SQLite comparison indexes need COLLATE NOCASE. Prefix LIKE index use depends on the database's collation and operator support.

On PostgreSQL, comparing fractional values with an integer column casts the column to numeric, so an ordinary B-tree index is not used. Give decimal fields a scale() when storage uses whole units. Check query plans with representative data.

Operators and ValuesFree-Text Terms