Added Match Scoring support. Closes #4.

README.md

@@ -168,6 +168,36 @@ You can fetch a single document from an index directly, by it's unique Doc ID:
 $obj_index->get('some-document-id-here');
 ```
 
+## Scoring ##
+
+You can enable the MatchScorer by calling the `Query::score` method.
+
+If you do this, each document in the result set will be scored by the Search API "according to search term frequency" - Google.
+
+Without it, documents will all have a score of 0.
+
+```php
+$obj_query->score();
+```
+
+And the results...
+
+```php
+foreach($obj_response->results as $obj_result) {
+    echo $obj_result->score, '<br />'; // Score will be a float
+}
+```
+
+### Multiple Sorts and Scoring ###
+
+If you apply `score()` and `sort()` you may be wasting cycles and costing money. Only score documents when you intend to sort by score.
+
+If you need to mix sorting of score and another field, you can use the magic field name `_score` like this - here we sort by price then score, so records with the same price are sorted by their score.
+
+```php
+$obj_query->score()->sort('price')->sort('_score');
+```
+
 # Helper Queries & Tools #
 
 ## Distance From ##

src/Search/Gateway.php

@@ -24,6 +24,7 @@
 use google\appengine\ListDocumentsResponse;
 use google\appengine\runtime\ApiProxy;
 use google\appengine\runtime\ApplicationError;
+use google\appengine\ScorerSpec\Scorer;
 use google\appengine\SearchRequest;
 use google\appengine\SearchResponse;
 use google\appengine\SearchResult;
@@ -121,6 +122,13 @@ public function search(Query $obj_query)
             }
         }
 
+        // Match Scoring
+        if(Query::SCORE_REGULAR === $obj_query->getScorer()) {
+            $obj_params->mutableScorerSpec()->setScorer(Scorer::MATCH_SCORER)->setLimit($obj_query->getLimit());
+        } elseif (Query::SCORE_RESCORING === $obj_query->getScorer()) {
+            $obj_params->mutableScorerSpec()->setScorer(Scorer::RESCORING_MATCH_SCORER)->setLimit($obj_query->getLimit());
+        }
+
         // Return Fields
         $arr_return_fields = $obj_query->getReturnFields();
         if(null !== $arr_return_fields && count($arr_return_fields) > 0) {
@@ -222,7 +230,7 @@ private function processSearchResponse()
             /** @var SearchResult $obj_result */
             $obj_doc = $obj_mapper->fromGoogle($obj_result->getDocument(), $obj_result->getExpressionList());
             $obj_response->results[] = (object)[
-                'score' => null, // $obj_result->getScore()
+                'score' => ($obj_result->getScoreSize() > 0 ? $obj_result->getScore(0) : 0),
                 'doc' => $obj_doc
             ];
         }

src/Search/Query.php

@@ -24,9 +24,19 @@
 class Query
 {
 
+    /**
+     * Sort directions
+     */
     const DESC = 'DESCENDING';
     const ASC = 'ASCENDING';
 
+    /**
+     * Match scorers
+     */
+    const SCORE_NONE = 'NONE';
+    const SCORE_REGULAR = 'REGULAR';
+    const SCORE_RESCORING = 'RESCORING';
+
     /**
      * Query string
      *
@@ -69,6 +79,13 @@ class Query
      */
     private $arr_sorts = [];
 
+    /**
+     * Scorer type
+     *
+     * @var string
+     */
+    private $str_scorer = self::SCORE_NONE;
+
     /**
      * Set the query string on construction
      *
@@ -174,6 +191,28 @@ public function getSorts()
         return $this->arr_sorts;
     }
 
+    /**
+     * Should we use a MatchScorer?
+     *
+     * @param $str_type
+     * @return $this
+     */
+    public function score($str_type = self::SCORE_REGULAR)
+    {
+        $this->str_scorer = $str_type;
+        return $this;
+    }
+
+    /**
+     * Get the defined scorer
+     *
+     * @return string
+     */
+    public function getScorer()
+    {
+        return $this->str_scorer;
+    }
+
     /**
      * Set the required return fields
      *

tests/QueryTest.php

@@ -120,4 +120,15 @@ public function testDistance()
         $this->assertSame($obj_query, $obj_query2);
     }
 
+    /**
+     * Validate scorer get/set
+     */
+    public function testScorer()
+    {
+        $obj_query = new \Search\Query();
+        $this->assertEquals(\Search\Query::SCORE_NONE, $obj_query->getScorer());
+        $obj_query->score();
+        $this->assertEquals(\Search\Query::SCORE_REGULAR, $obj_query->getScorer());
+    }
+
 }