Download the PHP package chr15k/laravel-meilisearch-advanced-query without Composer

Meilisearch Advanced Query provides a fluent, expressive API for building Meilisearch filter expressions in Laravel — the same filters you'd otherwise write by hand when customising Scout engine searches.

It handles compound conditions, nested groups, range queries, geo filters, and Meilisearch-specific operators, keeping your code readable as queries grow in complexity.

[!WARNING] v3 contains breaking changes. If you are upgrading from v2, see the upgrade guide.

Requirements

• PHP 8.3+
• Laravel 12 or 13
• Laravel Scout 11+
• Meilisearch PHP SDK 1.16+

Installation

The service provider is registered automatically via Laravel's package discovery.

Usage

Building a filter string

Use the Query facade (or resolve MeilisearchAdvancedQuery from the container directly) to build a filter string without touching Scout at all:

Running a Scout search

Chain forModel() on the query builder to hand off to Scout. This returns a Scout Builder instance that you can continue to chain as normal:

Sorting

Pass a sort expression (or array of expressions) to search():

For Meilisearch's sort syntax, see the sorting documentation.

The Query Facade

The Query facade proxies to a fresh MeilisearchAdvancedQuery instance on each call, so there is no shared state between requests.

You can also resolve the builder from the container directly if you prefer:

Builder Methods

where(field, operator, value, boolean)

The primary method. Operator defaults to Operator::EQ. Boolean defaults to AND.

orWhere(field, operator, value)

Identical to where() but joins with OR.

whereNot(field, value) / orWhereNot(field, value)

Negates a field equality check.

whereIn(field, values) / orWhereIn(field, values)

Matches any value in the given array.

whereNotIn(field, values) / orWhereNotIn(field, values)

Excludes any value in the given array.

whereBetween(field, from, to) / orWhereBetween(field, from, to)

Range filter using Meilisearch's TO operator.

whereExists(field) / orWhereExists(field)

Matches documents where the field exists.

whereIsNull(field) / orWhereIsNull(field)

Matches documents where the field is null.

whereIsEmpty(field) / orWhereIsEmpty(field)

Matches documents where the field is empty.

whereRaw(query) / orWhereRaw(query)

Passes a raw filter string through the compiler unchanged. Useful for filter expressions the builder does not yet support natively.

Geo filters

whereGeoRadius(lat, lng, distanceInMeters) / orWhereGeoRadius

whereGeoBoundingBox(lat1, lng1, lat2, lng2) / orWhereGeoBoundingBox

Nested / Grouped Queries

Pass a closure to where() or orWhere() to create a parenthesised group:

Groups can be nested to any depth:

Supported Operators

See the Meilisearch filter expression reference for full documentation on each operator.

Advanced: Using ScoutAdapter Directly

forModel() is a convenience wrapper around ScoutAdapter. If you need more control — for example, to swap in a custom compiler — you can instantiate ScoutAdapter directly:

ScoutAdapter validates at instantiation that the given class exists, is an Eloquent model, and uses the Searchable trait — throwing InvalidArgumentException if any check fails.

Debugging

Call compile() at any point in the chain to get the raw filter string without executing a search:

Architecture

The package is structured around four concerns:

• Nodes — immutable, typed value objects representing a single filter clause (ComparisonNode, InNode, NotInNode, BetweenNode, GroupNode, RawNode)
• Compiler — walks the node tree and produces a Meilisearch filter string (MeilisearchCompiler)
• Query builder — fluent API that constructs the node tree (MeilisearchAdvancedQuery)
• Scout adapter — bridges the compiled filter string to a Scout Builder (ScoutAdapter)

The Compiler and Query contracts are independently extensible — you can implement your own compiler (for a different search engine's filter syntax) or your own query builder without touching the rest of the package.

Running Tests

Individual checks:

Resources

• Building Advanced Meilisearch Queries in Laravel — a practical walkthrough of the package with real-world examples

License

MIT — see LICENSE for details.