Merge pull request #108 from einorler/sampler_agg

added sampler aggregation

docs/Aggregation/SamplerAgg.md

+# Sampler Aggregation
+
+> More info about histogram aggregation is in the [official elasticsearch docs][1]
+
+A filtering aggregation used to limit any sub aggregations' processing to a sample of the top-scoring documents. Optionally,
+diversity settings can be used to limit the number of matches that share a common value such as an "author".
+
+## Simple example
+
+```JSON
+{
+    "aggregations": {
+        "sample": {
+            "sampler": {
+                "shard_size": 200,
+                "field" : "user.id"
+            },
+            "aggs": {
+                 "keywords": {
+                     "significant_terms": {
+                         "field": "text"
+                     }
+                 }
+            }
+        }
+    }
+}
+```
+
+And now the query via DSL:
+
+```php
+$samplerAggregation = new SamplerAggregation('sample', 'user.id', 200);
+$samplerAggregation->addAggregation(
+    new SignificantTermsAggregation('keywords', 'text')
+);
+
+$search = new Search();
+$search->addAggregation($samplerAggregation);
+
+$queryArray = $search->toArray();
+```
+
+[1]: https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-bucket-sampler-aggregation.html

src/Aggregation/SamplerAggregation.php

+<?php
+
+/*
+ * This file is part of the ONGR package.
+ *
+ * (c) NFQ Technologies UAB <info@nfq.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace ONGR\ElasticsearchDSL\Aggregation;
+
+use ONGR\ElasticsearchDSL\Aggregation\Type\BucketingTrait;
+
+/**
+ * Class representing geo bounds aggregation.
+ *
+ * @link https://www.elastic.co/guide/en/elasticsearch/reference/2.3/search-aggregations-bucket-sampler-aggregation.html
+ */
+class SamplerAggregation extends AbstractAggregation
+{
+    use BucketingTrait;
+
+    /**
+     * Defines how many results will be received from each shard
+     * @param string $shardSize
+     */
+    private $shardSize;
+
+    /**
+     * Inner aggregations container init.
+     *
+     * @param string $name
+     * @param string $field
+     * @param int    $shardSize
+     */
+    public function __construct(
+        $name,
+        $field = null,
+        $shardSize = null
+    ) {
+        parent::__construct($name);
+
+        $this->setField($field);
+        $this->setShardSize($shardSize);
+    }
+
+    /**
+     * @return int
+     */
+    public function getShardSize()
+    {
+        return $this->shardSize;
+    }
+
+    /**
+     * @param int $shardSize
+     */
+    public function setShardSize($shardSize)
+    {
+        $this->shardSize = $shardSize;
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function getType()
+    {
+        return 'sampler';
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function getArray()
+    {
+        $out = array_filter(
+            [
+                'field' => $this->getField(),
+                'shard_size' => $this->getShardSize(),
+            ]
+        );
+
+        return $out;
+    }
+}

tests/Aggregation/SamplerAggregationTest.php

+<?php
+
+/*
+ * This file is part of the ONGR package.
+ *
+ * (c) NFQ Technologies UAB <info@nfq.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace ONGR\ElasticsearchDSL\Tests\Aggregation;
+
+use ONGR\ElasticsearchDSL\Aggregation\SamplerAggregation;
+use ONGR\ElasticsearchDSL\Aggregation\TermsAggregation;
+
+/**
+ * Unit test for children aggregation.
+ */
+class SamplerAggregationTest extends \PHPUnit_Framework_TestCase
+{
+    /**
+     * Tests getType method.
+     */
+    public function testGetType()
+    {
+        $aggregation = new SamplerAggregation('foo');
+        $result = $aggregation->getType();
+        $this->assertEquals('sampler', $result);
+    }
+
+    /**
+     * Tests toArray method.
+     */
+    public function testToArray()
+    {
+        $termAggregation = new TermsAggregation('acme');
+
+        $aggregation = new SamplerAggregation('foo');
+        $aggregation->addAggregation($termAggregation);
+        $aggregation->setField('name');
+        $aggregation->setShardSize(200);
+        $result = $aggregation->toArray();
+        $expected = [
+            'sampler' => [
+                'field' => 'name',
+                'shard_size' => 200,
+            ],
+            'aggregations' => [
+                $termAggregation->getName() => $termAggregation->toArray(),
+            ],
+        ];
+        $this->assertEquals($expected, $result);
+    }
+
+    /**
+     * Tests getArray method without provided shard size.
+     */
+    public function testGetArrayNoShardSize()
+    {
+        $aggregation = new SamplerAggregation('foo', 'bar');
+        $this->assertEquals(['field' => 'bar'], $aggregation->getArray());
+    }
+}