Support for ordering by relevance (#27)

Author: pascalbaljet

CHANGELOG.md

@@ -2,6 +2,10 @@
 
 All notable changes to `laravel-cross-eloquent-search` will be documented in this file
 
+## 2.2.0 - 2021-09-17
+
+- Support for ordering by relevance
+
 ## 2.1.0 - 2021-08-09
 
 - Support for Table prefixes

README.md

@@ -23,6 +23,7 @@ Hey! We've built a Docker-based deployment tool to launch apps and sites fully c
 * Search through one or more [Eloquent models](https://laravel.com/docs/master/eloquent).
 * Support for cross-model [pagination](https://laravel.com/docs/master/pagination#introduction).
 * Search through single or multiple columns.
+* Order by (cross-model) columns or by relevance.
 * Use [constraints](https://laravel.com/docs/master/eloquent#retrieving-models) and [scoped queries](https://laravel.com/docs/master/eloquent#query-scopes).
 * [Eager load relationships](https://laravel.com/docs/master/eloquent-relationships#eager-loading) for each model.
 * In-database [sorting](https://laravel.com/docs/master/queries#ordering-grouping-limit-and-offset) of the combined result.
@@ -141,12 +142,26 @@ Search::add(Post::class, 'title')
 If you want to sort the results by another column, you can pass that column to the `add` method as a third parameter. Call the `orderByDesc` method to sort the results in descending order.
 
 ```php
-Search::add(Post::class, 'title', 'publihed_at')
+Search::add(Post::class, 'title', 'published_at')
     ->add(Video::class, 'title', 'released_at')
     ->orderByDesc()
     ->get('learn');
 ```
 
+You can call the `orderByRelevance` method to sort the results by the number of occurrences of the search terms. Imagine these two sentences:
+
+* Apple introduces iPhone 13 and iPhone 13 mini
+* Apple unveils new iPad mini with breakthrough performance in stunning new design
+
+If you search for *Apple iPad*, the second sentence will come up first, as there are more matches of the search terms.
+
+```php
+Search::add(Post::class, 'title')
+    ->beginWithWildcard()
+    ->orderByRelevance()
+    ->get('Apple iPad');
+```
+
 ### Pagination
 
 We highly recommend paginating your results. Call the `paginate` method before the `get` method, and you'll get an instance of `\Illuminate\Contracts\Pagination\LengthAwarePaginator` as a result. The `paginate` method takes three (optional) parameters to customize the paginator. These arguments are [the same](https://laravel.com/docs/master/pagination#introduction) as Laravel's database paginator.

src/Searcher.php

@@ -47,6 +47,11 @@ class Searcher
      */
     protected Collection $terms;
 
+    /**
+     * Collection of search terms.
+     */
+    protected Collection $termsWithoutWildcards;
+
     /**
      * The number of items to be shown per page.
      */
@@ -108,6 +113,18 @@ public function orderByDesc(): self
         return $this;
     }
 
+    /**
+     * Sort the results in relevance order.
+     *
+     * @return self
+     */
+    public function orderByRelevance(): self
+    {
+        $this->orderByDirection = 'relevance';
+
+        return $this;
+    }
+
     /**
      * Disable the parsing of the search term.
      */
@@ -291,17 +308,17 @@ protected function initializeTerms(string $terms): self
     {
         $terms = $this->parseTerm ? $this->parseTerms($terms) : $terms;
 
-        $this->terms = Collection::wrap($terms)
-            ->filter()
-            ->unless($this->soundsLike, function ($terms) {
-                return $terms->map(function ($term) {
-                    return implode([
-                        $this->beginWithWildcard ? '%' : '',
-                        $term,
-                        $this->endWithWildcard ? '%' : '',
-                    ]);
-                });
+        $this->termsWithoutWildcards = Collection::wrap($terms)->filter();
+
+        $this->terms = Collection::make($this->termsWithoutWildcards)->unless($this->soundsLike, function ($terms) {
+            return $terms->map(function ($term) {
+                return implode([
+                    $this->beginWithWildcard ? '%' : '',
+                    $term,
+                    $this->endWithWildcard ? '%' : '',
+                ]);
             });
+        });
 
         return $this;
     }
@@ -324,6 +341,34 @@ public function addSearchQueryToBuilder(Builder $builder, ModelToSearchThrough $
         });
     }
 
+    /**
+     * Adds a word count so we can order by relevance.
+     *
+     * @param \Illuminate\Database\Eloquent\Builder $builder
+     * @param \ProtoneMedia\LaravelCrossEloquentSearch\ModelToSearchThrough $modelToSearchThrough
+     * @return void
+     */
+    private function addRelevanceQueryToBuilder($builder, $modelToSearchThrough)
+    {
+        if ($this->orderByDirection !== 'relevance') {
+            return;
+        }
+
+        $expressionsAndBindings = $modelToSearchThrough->getQualifiedColumns()->flatMap(function ($field) use ($builder) {
+            return $this->termsWithoutWildcards->map(function ($term) use ($field) {
+                return [
+                    'expression' => "COALESCE(CHAR_LENGTH(LOWER({$field})) - CHAR_LENGTH(REPLACE(LOWER({$field}), ?, ?)), 0)",
+                    'bindings'   => [strtolower($term), substr(strtolower($term), 1)],
+                ];
+            });
+        });
+
+        $selects  = $expressionsAndBindings->map->expression->implode(' + ');
+        $bindings = $expressionsAndBindings->flatMap->bindings->all();
+
+        $builder->selectRaw("{$selects} as terms_count", $bindings);
+    }
+
     /**
      * Builds an array with all qualified columns for
      * both the ids and ordering.
@@ -375,6 +420,7 @@ protected function buildQueries(): Collection
                 ->select($this->makeSelects($modelToSearchThrough))
                 ->tap(function ($builder) use ($modelToSearchThrough) {
                     $this->addSearchQueryToBuilder($builder, $modelToSearchThrough);
+                    $this->addRelevanceQueryToBuilder($builder, $modelToSearchThrough);
                 });
         });
     }
@@ -395,6 +441,10 @@ protected function getCompiledQueryBuilder(): QueryBuilder
         // union the other queries together
         $queries->each(fn (Builder $query) => $firstQuery->union($query));
 
+        if ($this->orderByDirection === 'relevance') {
+            return $firstQuery->orderBy('terms_count', 'desc');
+        }
+
         // sort by the given columns and direction
         return $firstQuery->orderBy(DB::raw($this->makeOrderBy()), $this->orderByDirection);
     }

tests/SearchTest.php

@@ -308,6 +308,22 @@ public function it_can_eager_load_relations()
         $this->assertTrue($results->first()->relationLoaded('comments'));
     }
 
+    /** @test */
+    public function it_can_sort_by_word_occurrence()
+    {
+        $videoA = Video::create(['title' => 'Apple introduces', 'subtitle' => 'iPhone 13 and iPhone 13 mini']);
+        $videoB = Video::create(['title' => 'Apple unveils', 'subtitle' => 'new iPad mini with breakthrough performance in stunning new design']);
+
+        $results = Search::new()
+            ->add(Video::class, ['title', 'subtitle'])
+            ->beginWithWildcard()
+            ->orderByRelevance()
+            ->get('Apple iPad');
+
+        $this->assertCount(2, $results);
+        $this->assertTrue($results->first()->is($videoB));
+    }
+
     /** @test */
     public function it_uses_length_aware_paginator_by_default()
     {