README

This library provides an intuitive query builder that makes generating more complex Meilisearch queries (compound, nested, meilisearch specific operators, ranking etc.) easier, replacing the need to construct your own raw Meilisearch queries when working with Scout's advanced filter option. Check out the Usage section below :)

Note

This package assumes you have installed and setup the following:

1. Laravel Scout
2. Meilisearch driver

Install

composer require chr15k/laravel-meilisearch-advanced-query

Usage

For context, go here to see how custom search engine queries are typically used with Laravel Scout.

Note

The following example effectively replaces the standard User::search($term, $callback) method and will return a Scout Builder instance after calling search() as expected:

<?php
use App\Models\User;
use Chr15k\MeilisearchAdvancedQuery\MeilisearchQuery;

$builder = MeilisearchQuery::for(User::class)
    ->where('name', 'Chris')
    ->whereIn('email', ['chris@example.com', 'bob@example.com'])
    ->orWhere(fn ($query) => $query
        ->whereTo('login_count', 50, 400)
        ->orWhereIsEmpty('verified_at')
    )->sort(['name:desc', 'email:asc'])
     ->search($term); // returns Scout Builder instance

// continue to chain Scout methods
$results = $builder->paginate();

Builder Methods

# where(column, operator(optional), value(optional), boolean(optional))

MeilisearchQuery::for(User::class)->where('name', 'Chris');

// "name = 'Chris'"

# orWhere(column, operator(optional), value(optional))

MeilisearchQuery::for(User::class)->orWhere('name', 'Chris')

// "name = 'Chris'"

MeilisearchQuery::for(User::class)
    ->where('name', 'Bob')
    ->orWhere('name', 'Chris')

// "name = 'Bob' OR name = 'Chris'"

# whereIn(column, value(optional))

MeilisearchQuery::for(User::class)
    ->whereIn('name', ['Chris', 'Bob']);

// "name IN ['Chris','Bob']"

# orWhereIn(column, value(optional))

MeilisearchQuery::for(User::class)
    ->orWhereIn('name', ['Chris', 'Bob']);

// "name IN ['Chris','Bob']"

MeilisearchQuery::for(User::class)
    ->where('email', 'chris@example.com')
    ->orWhereIn('name', ['Chris', 'Bob']) ;

// "email = 'chris@example.com' OR name IN ['Chris','Bob']"

# whereNotIn(column, value(optional))

MeilisearchQuery::for(User::class)
    ->whereNotIn('name', ['Chris', 'Bob']);

// "name NOT IN ['Chris','Bob']"

# orWhereNotIn(column, value(optional))

MeilisearchQuery::for(User::class)
    ->where('email', 'chris@example.com')
    ->orWhereNotIn('name', ['Chris', 'Bob']);

// "email = 'chris@example.com' OR name NOT IN ['Chris','Bob']"

# whereNot(column, value(optional))

MeilisearchQuery::for(User::class)
    ->whereNot('name', 'Chris');

// "NOT name 'Chris'"

# orWhereNot(column, value(optional))

MeilisearchQuery::for(User::class)
    ->where('email', 'chris@example.com')
    ->orWhereNot('name', 'Chris');

// "email = 'chris@example.com' OR NOT name 'Chris'"

# whereIsEmpty(column)

MeilisearchQuery::for(User::class)->whereIsEmpty('name');

// "name IS EMPTY"

# orWhereIsEmpty(column)

MeilisearchQuery::for(User::class)
    ->whereNot('name', 'Chris')
    ->orWhereIsEmpty('name');

// "NOT name 'Chris' OR name IS EMPTY"

# whereTo(column, from, to)

MeilisearchQuery::for(User::class)->whereTo('count', 1, 10);

// "count 1 TO 10"

# orWhereTo(column, from, to)

MeilisearchQuery::for(User::class)
    ->where('email', 'chris@example.com')
    ->orWhereTo('count', 1, 10);

// "email = 'chris@example.com' OR count 1 TO 10"

# whereRaw(rawQuery)

MeilisearchQuery::for(User::class)
    ->whereRaw("name = 'Chris' OR name = 'Bob'")
    ->compile();

// "name = 'Chris' OR name = 'Bob'"

# orWhereRaw(rawQuery)

MeilisearchQuery::for(User::class)
    ->whereRaw("name = 'Chris'")
    ->orWhereRaw("name = 'Bob'")
    ->compile();

// "name = 'Chris' OR name = 'Bob'"

# whereGeoRadius([lat, lng], radius)

MeilisearchQuery::for(Hotel::class)
  ->where('active', true)
  ->whereGeoRadius([45.810741058569405, 9.086351912290523], 20000)
  ->search();
  
// "active = true AND _geoRadius(45.810741058569405, 9.086351912290523, 20000)"

# whereGeoBoundingBox([lat, lng], [lat, lng])

MeilisearchQuery::for(Hotel::class)
  ->where('active', true)
  ->whereGeoBoundingBox([45.810741058569405, 9.086351912290523], [45.810741058569405, 9.086351912290523])
  ->search();
  
// "active = true AND _geoBoundingBox([45.810741058569405, 9.086351912290523], [45.810741058569405, 9.086351912290523])"

# whereExists(column)

# orWhereExists(column)

# whereIsNull(column)

# orWhereIsNull(column)

Nested / grouped queries

MeilisearchQuery::for(User::class)
    ->where(fn ($query) => $query
        ->whereNot('name', 'Chris')
        ->orWhereIsEmpty('name')
    )
    ->orWhere('email', 'chris@example.com');

// "(NOT name 'Chris' OR name IS EMPTY) OR email = 'chris@example.com'"

Sorting

In addition to the above methods, you can also call sort on the builder instance as follows:

Single column sort:

MeilisearchQuery::for(User::class)
    ->where('name', 'Chris')
    ->orWhere('name', 'Bob')
    ->sort('name:desc');

Multiple column sort:

MeilisearchQuery::for(User::class)
    ->where('name', 'Chris')
    ->orWhere('name', 'Bob')
    ->sort(['name:desc', 'email:asc']);

For more information on sorting see this link

Supported search engine operators

Docs: Meilisearch operators

'=', '!=', 'IN', 'NOT IN', '>=', '<=', '>', '<', 'TO', 'NOT', 'EXISTS', 'IS EMPTY', 'IS NULL'

Alternatively to the methods above, any of these operators can be called on where() or orWhere() methods, example:

MeilisearchQuery::for(User::class)->where('name', 'NOT', 'Chris'); // "NOT name 'Chris'"
MeilisearchQuery::for(User::class)->where('count', 'TO', [1, 10]); // "count 1 TO 10"
MeilisearchQuery::for(User::class)->where('name', 'IS EMPTY'); // "name IS EMPTY"

Calling without operator will default to equals (same behaviour as Eloquent):

MeilisearchQuery::for(User::class)->where('name', 'Chris'); // "name = 'Chris'"

Debugging / helpers

To get the raw query string from the builder, call compile() instead of search()

MeilisearchQuery::for(User::class)
    ->where(fn ($query) => $query
        ->whereIn('name', ['Chris', 'Bob'])
        ->orWhereIsEmpty('verified_at')
    )
    ->orWhere('email', 'chris@example.com')
    ->compile();

// "(name IN ['Chris','Bob'] OR verified_at IS EMPTY) OR email = 'chris@example.com'"

To inspect the current builder instance properties:

MeilisearchQuery::for(User::class)->where('name', 'Chris')->inspect();

Or use the dump helper:

MeilisearchQuery::for(User::class)->where('name', 'Chris')->dump();

Tests

composer test