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

Custom Resolvers

Write the SQL for a field with a resolver class or closure that receives compiled clauses.

A custom resolver writes the SQL for a field when the built-in targets do not fit, such as core array fields or dates with a custom input format.

Register a resolver

Pass a Contracts\Resolver or a closure to using(). Both receive (Builder $query, Clause $clause, Context $context):

php
use HosmelQ\SearchSyntaxParser\Laravel\Context;
use HosmelQ\SearchSyntaxParser\Laravel\Contracts\Resolver;
use HosmelQ\SearchSyntaxParser\Laravel\Field;
use HosmelQ\SearchSyntaxParser\Query\Clause;
use Illuminate\Database\Eloquent\Builder;

final class QuantityResolver implements Resolver
{
    #[\Override]
    public function apply(Builder $query, Clause $clause, Context $context): void
    {
        $column = $query->qualifyColumn('quantity');

        $query->where($column, $clause->operator->value, $clause->value);

        if ($clause->negated && $context->field->isNullable()) {
            $query->orWhereNull($column);
        }
    }
}

$field = Field::integer('quantity')
    ->operators('=', '!=', '>', '>=', '<', '<=')
    ->withoutLists()
    ->withoutRanges()
    ->withoutExists()
    ->withoutWildcards()
    ->nullable()
    ->using(new QuantityResolver());

Filter resolvers receive a builder isolated in a leaf group. Directive resolvers receive the root builder. Always add a predicate, even when it matches no rows: an empty group contributes no SQL.

Restrict the field to shapes the resolver supports. The example above accepts only scalar comparison operators.

Read a clause

Resolvers receive HosmelQ\SearchSyntaxParser\Query\Clause from the core parser. It exposes readonly properties:

PropertyValue
fieldThe public field name.
operatorA core Query\Operator, already complemented for NOT.
valueA storage scalar, list, core Query\Bounds, core Query\TextPattern, or null for existence.
positionSource offset, or null for defaults. Directives retain the written value offset.
negatedWhether the clause is a set complement.
textWhether the built-in resolver would use case-insensitive text comparison.
fullTextA core Support\FullText object for word matching, otherwise null. It exposes words, phrase, and prefix.

Query\Operator includes equality, ordering, list, range, existence, and LIKE variants. complement() returns the inverse. Clause::positive() recovers the positive clause while preserving its other properties. Query\Bounds has inclusive from and to endpoints; a null endpoint is open.

The core clause compiler prepares values, operators, and text metadata, including positional array conversions. Two open range bounds become existence clauses; text without words becomes a constant group before a resolver is called. It also supplies their ClauseGroup tree through SearchParser::compile(); this package translates the tree into SQL.

Field::comparisonType($value), comparesNumbers(), getAllowedValues(), getValueType(), isDate(), and isCalendarDate() expose the core comparison contract. Use keyOf($clause->field) to extract a dynamic key.

The context exposes the field definition, connection driver, resolved user DateTimeZone, and the invocation's shared DateTimeImmutable clock.

Resolve date intervals

Handle date existence operators directly. For other format-less date clauses, use DateBounds::forClause($clause, $context->timezone, $context->now) from HosmelQ\SearchSyntaxParser\Date, then toStorage($zone, $format) on each interval. These date helpers handle positive intervals, storage precision, and supported years; apply the clause's complement in SQL. Null storage bounds mean no matching stored value, while two open endpoints mean every present value. Custom input formats still need their own parsing.

Compile values consistently

Resolvers own SQL type handling, text folding, NULL complements, and negative conditions across several targets. You can reuse Resolvers\ColumnResolver for standard column and JSON behavior.

LIKE values contain literal segments separated by wildcards. Bind $clause->value->toLike() to escape %, _, and ! with !, and emit LIKE ? ESCAPE '!' or NOT LIKE ? ESCAPE '!'. Laravel's whereLike() does not add this required escape clause. Parenthesize trusted expression targets, including before NULL checks.

Built-in dates use interval comparisons; custom input formats require a custom resolver. Relation and aggregate targets use built-in resolvers and cannot be combined with using().

Strict complements

Use Context::complement() to exclude all rows matched by a callback, including rows where SQL NOT would return NULL:

php
use HosmelQ\SearchSyntaxParser\Laravel\Context;
use HosmelQ\SearchSyntaxParser\Laravel\Field;
use HosmelQ\SearchSyntaxParser\Query\Clause;
use Illuminate\Database\Eloquent\Builder;

$field = Field::boolean('late')
    ->operators('=', '!=')
    ->withoutLists()->withoutRanges()->withoutWildcards()->withoutExists()
    ->using(function (Builder $query, Clause $clause, Context $context): void {
        $positive = function (Builder $matches): void {
            $matches->where('due_at', '<', now());
        };

        if ((bool) $clause->value !== $clause->negated) {
            $query->where($positive);
        } else {
            $context->complement($query, $positive);
        }
    });

The helper excludes primary keys selected by the positive predicate. Its subquery starts without global scopes and groups the callback's conditions. Root constraints and global scopes still apply. Here, NULL due dates match late:false and late:!=true.

The model must have one named primary key; absent or composite keys throw LogicException. The callback must constrain its builder without executing it. For standard value mappings and booleans, use scope and predicate fields.

Validation ErrorsForm Request Validation