Add method to get document score from iterator

Resources/doc/results_parsing.md

@@ -60,6 +60,23 @@ Zane Heidenreich IV
 Hattie Shields MD
 ```
 
+### Getting Document Score
+
+In most cases Elasticsearch returns result score (`_score` field) for each document.
+As this score might be different per search it's not treated as document field and
+cannot be associated with document. You can get document's score from results iterator
+while iterating:
+
+```php
+$results = $repository->execute($search);
+
+foreach ($results as $document) {
+    echo $document->title, $results->getDocumentScore();
+}
+```
+
+Example above prints titles of all documents following search score.
+
 #### Important notice
 
 `DocumentIterator` doesn't cache or store generated document object. `Converter` directly returns the instance after it's requested and will generate again if it will be requested.

Result/AbstractResultsIterator.php

@@ -291,6 +291,24 @@ protected function page()
         return $this;
     }
 
+    /**
+     * Returns score of current hit.
+     *
+     * @return int
+     */
+    public function getDocumentScore()
+    {
+        if (!$this->valid()) {
+            throw new \LogicException('Document score is available only while iterating over results.');
+        }
+
+        if (!isset($this->documents[$this->key]['_score'])) {
+            return null;
+        }
+
+        return $this->documents[$this->key]['_score'];
+    }
+
     /**
      * Converts raw array to document object or array, depends on iterator type.
      *

Tests/Functional/Mapping/MetadataCollectorTest.php

@@ -60,13 +60,11 @@ public function testGetBundleMapping()
 
         $properties = $mapping['product']['properties'];
         $this->assertArrayNotHasKey('_id', $properties);
-        $this->assertArrayNotHasKey('_score', $properties);
         $this->assertArrayNotHasKey('_ttl', $properties);
         $this->assertArrayNotHasKey('_parent', $properties);
 
         $aliases = $mapping['product']['aliases'];
         $this->assertArrayHasKey('_id', $aliases);
-        $this->assertArrayHasKey('_score', $aliases);
         $this->assertArrayHasKey('_ttl', $aliases);
         $this->assertArrayHasKey('_parent', $aliases);
     }

Tests/Functional/Service/RepositoryTest.php

@@ -11,13 +11,11 @@
 
 namespace ONGR\ElasticsearchBundle\Tests\Functional;
 
-use ONGR\ElasticsearchBundle\Result\Result;
 use ONGR\ElasticsearchBundle\Tests\app\fixture\Acme\BarBundle\Document\Product;
 use ONGR\ElasticsearchDSL\Filter\PrefixFilter;
 use ONGR\ElasticsearchDSL\Query\MatchAllQuery;
 use ONGR\ElasticsearchDSL\Query\RangeQuery;
 use ONGR\ElasticsearchBundle\Service\Manager;
-use ONGR\ElasticsearchBundle\Service\Repository;
 use ONGR\ElasticsearchBundle\Test\AbstractElasticsearchTestCase;
 
 class RepositoryTest extends AbstractElasticsearchTestCase

Tests/Unit/Result/AbstractResultsIteratorTest.php

@@ -35,4 +35,76 @@ public function testClearScroll()
         // Trigger destructor call
         unset($iterator);
     }
+
+    /**
+     * Test for getDocumentScore().
+     */
+    public function testGetDocumentScore()
+    {
+        $rawData = [
+            'hits' => [
+                'total' => 3,
+                'hits' => [
+                    [
+                        '_index' => 'test',
+                        '_type' => 'product',
+                        '_id' => 'foo',
+                        '_score' => 1,
+                        '_source' => [
+                            'title' => 'Product Foo',
+                        ],
+                    ],
+                    [
+                        '_index' => 'test',
+                        '_type' => 'product',
+                        '_id' => 'bar',
+                        '_score' => 2,
+                        '_source' => [
+                            'title' => 'Product Bar',
+                        ],
+                    ],
+                    [
+                        '_index' => 'test',
+                        '_type' => 'product',
+                        '_id' => 'baz',
+                        '_score' => null,
+                        '_source' => [
+                            'title' => 'Product Baz',
+                        ],
+                    ],
+                ],
+            ],
+        ];
+
+        $manager = $this->getMockBuilder('ONGR\ElasticsearchBundle\Service\Manager')
+            ->disableOriginalConstructor()
+            ->getMock();
+
+        $results = new DummyIterator($rawData, $manager);
+
+        $expectedScores = [1, 2, null];
+        $actualScores = [];
+
+        foreach ($results as $item) {
+            $actualScores[] = $results->getDocumentScore();
+        }
+
+        $this->assertEquals($expectedScores, $actualScores);
+    }
+
+    /**
+     * Test for getDocumentScore() in case called when current iterator value is not valid.
+     *
+     * @expectedException \LogicException
+     * @expectedExceptionMessage Document score is available only while iterating over results
+     */
+    public function testGetScoreException()
+    {
+        $manager = $this->getMockBuilder('ONGR\ElasticsearchBundle\Service\Manager')
+            ->disableOriginalConstructor()
+            ->getMock();
+
+        $results = new DummyIterator([], $manager);
+        $results->getDocumentScore();
+    }
 }

Tests/app/fixture/Acme/BarBundle/Document/Product.php

@@ -28,13 +28,6 @@ class Product
      */
     public $id;
 
-    /**
-     * @var string
-     *
-     * @ES\MetaField(name="_score")
-     */
-    public $score;
-
     /**
      * @var string
      *