Merge pull request #110 from einorler/significant_terms_agg

added significant terms aggregation

docs/Aggregation/SignificantTerms.md

+# Significant Terms Aggregation
+
+> More info about histogram aggregation is in the [official elasticsearch docs][1]
+
+An aggregation that returns interesting or unusual occurrences of terms in a set.
+
+## Simple example
+
+```JSON
+{
+    "query" : {
+        "terms" : {"force" : [ "British Transport Police" ]}
+    },
+    "aggregations" : {
+        "significantCrimeTypes" : {
+            "significant_terms" : { "field" : "crime_type" }
+        }
+    }
+}
+```
+
+And now the query via DSL:
+
+```php
+$significantTermsAggregation = new SignificantTermsAggregation('significantCrimeTypes', 'crime_type');
+$query = new TermsQuery('force', ['British Transport Police']);
+
+$search = new Search();
+$search->addQuery($query);
+$search->addAggregation($histogramAggregation);
+
+$queryArray = $search->toArray();
+```
+
+## Multi-set Analysis
+
+A simpler way to perform analysis across multiple categories is to use a parent-level aggregation to segment the data ready for analysis.
+
+```JSON
+
+{
+    "aggregations": {
+        "forces": {
+            "terms": {"field": "force"},
+            "aggregations": {
+                "significantCrimeTypes": {
+                    "significant_terms": {"field": "crime_type"}
+                }
+            }
+        }
+    }
+}
+
+```
+
+And now the query via DSL:
+
+```php
+
+$significantTermsAggregation = new SignificantTermsAggregation('significantCrimeTypes', 'crime_type');
+$termsAggregation = new TermsAggregation('forces', 'force');
+$termsAggregation->addAggregation($significantTermsAggregation);
+
+$search = new Search();
+$search->addAggregation($termsAggregation);
+
+$queryArray = $search->toArray();
+
+```
+
+Other top level aggregations can be used to segment the data, for example, it can be segmented by
+geographic area to identify unusual hot-spots of a particular crime:
+
+```JSON
+
+{
+    "aggs": {
+        "hotspots": {
+            "geohash_grid" : {
+                "field":"location",
+                "precision":5,
+            },
+            "aggs": {
+                "significantCrimeTypes": {
+                    "significant_terms": {"field": "crime_type"}
+                }
+            }
+        }
+    }
+}
+
+```
+
+And now via DSL:
+
+```php
+
+$significantTermsAggregation = new SignificantTermsAggregation('significantCrimeTypes', 'crime_type');
+$geoHashAggregation = new GeoHashGridAggregation('hotspots', 'location', 5);
+$geoHashAggregation->addAggregation($significantTermsAggregation);
+
+$search = new Search();
+$search->addAggregation($geoHashAggregation);
+
+$queryArray = $search->toArray();
+
+```
+
+[1]: https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-bucket-significantterms-aggregation.html

src/Aggregation/SignificantTermsAggregation.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;
+
+/**
+ * Class representing TermsAggregation.
+ *
+ * @link https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-bucket-significantterms-aggregation.html
+ */
+class SignificantTermsAggregation extends TermsAggregation
+{
+    /**
+     * {@inheritdoc}
+     */
+    public function getType()
+    {
+        return 'significant_terms';
+    }
+}

tests/Aggregation/SignificantTermsAggregationTest.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\SignificantTermsAggregation;
+
+/**
+ * Unit test for children aggregation.
+ */
+class SignificantTermsAggregationTest extends \PHPUnit_Framework_TestCase
+{
+    /**
+     * Tests getType method.
+     */
+    public function testSignificantTermsAggregationGetType()
+    {
+        $aggregation = new SignificantTermsAggregation('foo');
+        $result = $aggregation->getType();
+        $this->assertEquals('significant_terms', $result);
+    }
+
+    /**
+     * Tests getArray method.
+     */
+    public function testSignificantTermsAggregationGetArray()
+    {
+        $mock = $this->getMockBuilder('ONGR\ElasticsearchDSL\Aggregation\AbstractAggregation')
+            ->disableOriginalConstructor()
+            ->getMockForAbstractClass();
+        $aggregation = new SignificantTermsAggregation('foo', 'title');
+        $aggregation->addAggregation($mock);
+        $result = $aggregation->getArray();
+        $expected = ['field' => 'title'];
+        $this->assertEquals($expected, $result);
+    }
+}