Added request explanation

Author: babenkoivan

README.md

@@ -19,6 +19,7 @@ Check out its [features](#features)!
 * [Console commands](#console-commands)
 * [Search rules](#search-rules)
 * [Available filters](#available-filters)
+* [Debug](#debug)
 
 ## Tutorial
 
@@ -375,3 +376,14 @@ whereNotExists($field) | whereNotExists('unemployed') | Checks if a value isn't
 whereRegexp($field, $value, $flags = 'ALL') | whereRegexp('name.raw', 'A.+') | Filters records according to a given regular expression. [Here](https://www.elastic.co/guide/en/elasticsearch/reference/5.2/query-dsl-regexp-query.html#regexp-syntax) you can find more about syntax.
 
 In most cases it's better to use raw fields to filter records, i.e. not analyzed fields.
+
+## Debug
+
+To analyze results of a search query you can set the `explain` flag to true and get explanation from received models:
+ 
+```php
+App\MyModel::search('Brazil')
+    ->explain(true)
+    ->first()
+    ->getExplanation();
+```

src/Builders/FilterBuilder.php

@@ -4,7 +4,10 @@
 
 use Laravel\Scout\Builder;
 
-class FilterBuilder extends Builder {
+class FilterBuilder extends Builder
+{
+    public $explain = false;
+
     public function __construct($model, $callback = null)
     {
         $this->model = $model;
@@ -118,4 +121,11 @@ public function whereRegexp($field, $value, $flags = 'ALL')
 
         return $this;
     }
+
+    public function explain($bool)
+    {
+        $this->explain = $bool;
+
+        return $this;
+    }
 }

src/Builders/SearchBuilder.php

@@ -2,7 +2,8 @@
 
 namespace ScoutElastic\Builders;
 
-class SearchBuilder extends FilterBuilder {
+class SearchBuilder extends FilterBuilder
+{
     public $rules = [];
 
     public function __construct($model, $query, $callback = null)

src/ElasticEngine.php

@@ -183,6 +183,10 @@ protected function buildSearchQueryPayload(Builder $builder, $queryPayload, arra
             }
         }
 
+        if ($builder->explain) {
+            $payload['explain'] = true;
+        }
+
         return $this->buildTypePayload(
             $builder->model,
             $payload
@@ -315,7 +319,14 @@ public function map($results, $model)
             $id = $hit['_id'];
 
             if (isset($models[$id])) {
-                return $models[$id];
+                /** @var Searchable $model */
+                $model = $models[$id];
+
+                if (isset($hit['_explanation'])) {
+                    $model->setExplanation($hit['_explanation']);
+                }
+
+                return $model;
             }
         })->filter();
     }

src/Features/HasExplanation.php

@@ -0,0 +1,18 @@
+<?php
+
+namespace ScoutElastic\Features;
+
+trait HasExplanation
+{
+    protected $explanation;
+
+    public function getExplanation()
+    {
+        return $this->explanation;
+    }
+
+    public function setExplanation(array $explanation)
+    {
+        $this->explanation = $explanation;
+    }
+}

src/Searchable.php

@@ -6,9 +6,11 @@
 use ScoutElastic\Builders\FilterBuilder;
 use ScoutElastic\Builders\SearchBuilder;
 use \Exception;
+use ScoutElastic\Features\HasExplanation;
 
 trait Searchable {
-    use ScoutSearchable;
+    use ScoutSearchable,
+        HasExplanation;
 
     /**
      * @return IndexConfigurator