2.0.0 refactor

Author: chr15k

README.md

@@ -30,110 +30,139 @@ composer require chr15k/laravel-meilisearch-advanced-query
 use App\Models\User;
 use Chr15k\MeilisearchAdvancedQuery\Facades\FilterBuilder;
 
-// build custom Meilisearch query callback
-$callback = FilterBuilder::where('name', 'Chris')
+$builder = MeilisearchQuery::for(User::class)
+    ->where('name', 'Chris')
     ->whereIn('email', ['[email protected]', '[email protected]'])
     ->orWhere(fn ($query) => $query
         ->whereTo('login_count', 50, 400)
         ->orWhereIsEmpty('verified_at')
-    )->sort('name', 'desc')
-    ->callback();
-
-// include callback in Scout's search method
-$builder = User::search($term, $callback);
+    )->sort(['name:desc', 'email:asc'])
+     ->search($term); // returns Scout Builder instance
 
 // continue to chain Scout methods
 $results = $builder->paginate();
 ```
 
-### Raw Meilisearch query
-
-If you just need the generated query from the builder then call `->compile()` instead of `->callback()`
-
 ## Builder Methods
 
 #### # where(column, operator(optional), value(optional), boolean(optional))
 
 ```php
-FilterBuilder::where('name', 'Chris')->compile(); // "name = 'Chris'"
+MeilisearchQuery::for(User::class)->where('name', 'Chris');
+
+// "name = 'Chris'"
 ```
 
 #### # orWhere(column, operator(optional), value(optional))
 
 ```php
-FilterBuilder::orWhere('name', 'Chris')->compile(); // "name = 'Chris'"
+MeilisearchQuery::for(User::class)->orWhere('name', 'Chris')
+
+// "name = 'Chris'"
 
-FilterBuilder::where('name', 'Bob')
+MeilisearchQuery::for(User::class)
+    ->where('name', 'Bob')
     ->orWhere('name', 'Chris')
-    ->compile(); // "name = 'Bob' OR name = 'Chris'"
+
+// "name = 'Bob' OR name = 'Chris'"
 ```
 
 #### # whereIn(column, value(optional))
 
 ```php
-FilterBuilder::whereIn('name', ['Chris', 'Bob'])->compile(); // "name IN ['Chris','Bob']"
+MeilisearchQuery::for(User::class)
+    ->whereIn('name', ['Chris', 'Bob']);
+
+// "name IN ['Chris','Bob']"
 ```
 
 #### # orWhereIn(column, value(optional))
 
 ```php
-FilterBuilder::orWhereIn('name', ['Chris', 'Bob'])->compile(); // "name IN ['Chris','Bob']"
+MeilisearchQuery::for(User::class)
+    ->orWhereIn('name', ['Chris', 'Bob']);
+
+// "name IN ['Chris','Bob']"
 
-FilterBuilder::where('email', '[email protected]')
-    ->orWhereIn('name', ['Chris', 'Bob'])->compile(); // "email = '[email protected]' OR name IN ['Chris','Bob']"
+MeilisearchQuery::for(User::class)
+    ->where('email', '[email protected]')
+    ->orWhereIn('name', ['Chris', 'Bob']) ;
+
+// "email = '[email protected]' OR name IN ['Chris','Bob']"
 ```
 
 #### # whereNotIn(column, value(optional))
 
 ```php
-FilterBuilder::whereNotIn('name', ['Chris', 'Bob'])->compile(); // "name NOT IN ['Chris','Bob']"
+MeilisearchQuery::for(User::class)
+    ->whereNotIn('name', ['Chris', 'Bob']);
+
+// "name NOT IN ['Chris','Bob']"
 ```
 
 #### # orWhereNotIn(column, value(optional))
 
 ```php
-FilterBuilder::where('email', '[email protected]')
-    ->orWhereNotIn('name', ['Chris', 'Bob'])->compile(); // "email = '[email protected]' OR name NOT IN ['Chris','Bob']"
+MeilisearchQuery::for(User::class)
+    ->where('email', '[email protected]')
+    ->orWhereNotIn('name', ['Chris', 'Bob']);
+
+// "email = '[email protected]' OR name NOT IN ['Chris','Bob']"
 ```
 
 #### # whereNot(column, value(optional))
 
 ```php
-FilterBuilder::whereNot('name', 'Chris')->compile(); // => "NOT name 'Chris'"
+MeilisearchQuery::for(User::class)
+    ->whereNot('name', 'Chris');
+
+// "NOT name 'Chris'"
 ```
 
 #### # orWhereNot(column, value(optional))
 
 ```php
-FilterBuilder::where('email', '[email protected]')
-    ->orWhereNot('name', 'Chris')->compile(); // => "email = '[email protected]' OR NOT name 'Chris'"
+MeilisearchQuery::for(User::class)
+    ->where('email', '[email protected]')
+    ->orWhereNot('name', 'Chris');
+
+// "email = '[email protected]' OR NOT name 'Chris'"
 ```
 
 #### # whereIsEmpty(column)
 
 ```php
-FilterBuilder::whereIsEmpty('name')->compile(); // => "name IS EMPTY"
+MeilisearchQuery::for(User::class)->whereIsEmpty('name');
+
+// "name IS EMPTY"
 ```
 
 #### # orWhereIsEmpty(column)
 
 ```php
-FilterBuilder::whereNot('name', 'Chris')
-    ->orWhereIsEmpty('name')
-    ->compile(); // => "NOT name 'Chris' OR name IS EMPTY"
+MeilisearchQuery::for(User::class)
+    ->whereNot('name', 'Chris')
+    ->orWhereIsEmpty('name');
+
+// "NOT name 'Chris' OR name IS EMPTY"
 ```
 
 #### # whereTo(column, from, to)
 
 ```php
-FilterBuilder::whereTo('count', 1, 10)->compile(); // => "count 1 TO 10"
+MeilisearchQuery::for(User::class)->whereTo('count', 1, 10);
+
+// "count 1 TO 10"
 ```
 
 #### # orWhereTo(column, from, to)
 
 ```php
-FilterBuilder::where('email', '[email protected]')
-    ->orWhereTo('count', 1, 10)->compile(); // => "email = '[email protected]' OR count 1 TO 10"
+MeilisearchQuery::for(User::class)
+    ->where('email', '[email protected]')
+    ->orWhereTo('count', 1, 10);
+
+// "email = '[email protected]' OR count 1 TO 10"
 ```
 
 #### # whereExists(column)
@@ -149,22 +178,40 @@ FilterBuilder::where('email', '[email protected]')
 ### Nested / grouped queries
 
 ```php
-FilterBuilder::where(fn ($query) => $query
-    ->whereNot('name', 'Chris')
-    ->orWhereIsEmpty('name')
-)
-->orWhere('email', '[email protected]')
-->compile(); // => "(NOT name 'Chris' OR name IS EMPTY) OR email = '[email protected]'"
+MeilisearchQuery::for(User::class)
+    ->where(fn ($query) => $query
+        ->whereNot('name', 'Chris')
+        ->orWhereIsEmpty('name')
+    )
+    ->orWhere('email', '[email protected]');
+
+// "(NOT name 'Chris' OR name IS EMPTY) OR email = '[email protected]'"
 ```
 
 ### Sorting
 
 In addition to the above methods, you can also call sort on the builder instance as follows:
 
+#### Single column sort:
+
 ```php
-FilterBuilder::where('name', 'Chris')->sort('name', 'desc')->compile();
+MeilisearchQuery::for(User::class)
+    ->where('name', 'Chris')
+    ->orWhere('name', 'Bob')
+    ->sort('name:desc');
 ```
 
+#### Multiple column sort:
+
+```php
+MeilisearchQuery::for(User::class)
+    ->where('name', 'Chris')
+    ->orWhere('name', 'Bob')
+    ->sort(['name:desc', 'email:asc']);
+```
+
+For more information on sorting see this [link](https://www.meilisearch.com/docs/learn/filtering_and_sorting/sort_search_results)
+
 ### Supported search engine operators
 
 Docs: [Meilisearch operators](https://www.meilisearch.com/docs/learn/filtering_and_sorting/filter_expression_reference#filter-operators)
@@ -176,15 +223,43 @@ Docs: [Meilisearch operators](https://www.meilisearch.com/docs/learn/filtering_a
 Alternatively to the methods above, any of these operators can be called on `where()` or `orWhere()` methods, example:
 
 ```php
-FilterBuilder::where('name', 'NOT', 'Chris')->compile(); // => "NOT name 'Chris'"
-FilterBuilder::where('count', 'TO', [1, 10])->compile(); // => "count 1 TO 10"
-FilterBuilder::where('name', 'IS EMPTY')->compile(); // => "name IS EMPTY"
+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):
 
 ```php
-FilterBuilder::where('name', 'Chris')->compile(); // => "name = 'Chris'"
+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()`
+
+```php
+MeilisearchQuery::for(User::class)
+    ->where(fn ($query) => $query
+        ->whereIn('name', ['Chris', 'Bob'])
+        ->orWhereIsEmpty('verified_at')
+    )
+    ->orWhere('email', '[email protected]')
+    ->compile();
+
+// "(name IN ['Chris','Bob'] OR verified_at IS EMPTY) OR email = '[email protected]'"
+```
+
+To inspect the current builder instance properties:
+
+```php
+MeilisearchQuery::for(User::class)->where('name', 'Chris')->inspect();
+```
+
+Or use the `dump` helper:
+
+```php
+MeilisearchQuery::for(User::class)->where('name', 'Chris')->dump();
 ```
 
 ## Tests

src/Contracts/Builder.php

@@ -0,0 +1,43 @@
+<?php
+
+namespace Chr15k\MeilisearchAdvancedQuery\Contracts;
+
+use Closure;
+
+interface QueryBuilder
+{
+    /**
+     * @see https://www.meilisearch.com/docs/learn/filtering_and_sorting/filter_expression_reference#filter-operators
+     */
+    const OPERATORS = ['=', '!=', 'in', '>=', '<=', '>', '<', 'to', 'not', 'and', 'or'];
+
+    /**
+     * @see https://www.meilisearch.com/docs/learn/filtering_and_sorting/filter_expression_reference#filter-operators
+     */
+    const OPERATORS_COLUMN_ONLY = ['exists', 'is empty', 'is null'];
+
+    /**
+     * Create a new builder instance for a searchable model.
+     */
+    public static function for(string $modelClass): self;
+
+    /**
+     * Return the Scout builder instance.
+     */
+    public function search(string $term = ''): \Laravel\Scout\Builder;
+
+    /**
+     * Return the compiled query.
+     */
+    public function compile(): string|self;
+
+    /**
+     * Add a where clause to the segments array.
+     */
+    public function where(
+        string|Closure $column,
+        mixed $operator = '=',
+        mixed $value = null,
+        string $boolean = 'AND'
+    ): self;
+}

src/Contracts/QueryBuilder.php

@@ -2,7 +2,7 @@
 
 namespace Chr15k\MeilisearchAdvancedQuery\Contracts;
 
-interface FilterSegment
+interface QuerySegment
 {
     public function compile(): string;
 }

src/Contracts/FilterSegment.php src/Contracts/QuerySegment.phpsrc/Contracts/FilterSegment.php renamed to src/Contracts/QuerySegment.php

@@ -2,9 +2,9 @@
 
 namespace Chr15k\MeilisearchAdvancedQuery;
 
-use Chr15k\MeilisearchAdvancedQuery\Contracts\FilterSegment;
+use Chr15k\MeilisearchAdvancedQuery\Contracts\QuerySegment;
 
-class Expression implements FilterSegment
+class Expression implements QuerySegment
 {
     public function __construct(
         public string $column,