Merge pull request #111 from einorler/date_histogram_agg

added date histogram aggregation

docs/Aggregation/DateHistogram.md

+# Date Histogram Aggregation
+
+> More info about histogram aggregation is in the [official elasticsearch docs][1]
+
+A multi-bucket aggregation similar to the histogram except it can only be applied on date values.
+Example of expressions for interval: `year`, `quarter`, `month`, `week`, `day`, `hour`, `minute`, `second`
+
+## Simple example
+
+```JSON
+{
+    "aggregations": {
+        "articles_over_time" : {
+            "date_histogram" : {
+                "field" : "date",
+                "interval" : "month"
+            }
+        }
+    }
+}
+```
+
+And now the query via DSL:
+
+```php
+$dateHistogramAggregation = new DateHistogramAggregation('articles_over_time', 'date', 'month');
+
+$search = new Search();
+$search->addAggregation($dateHistogramAggregation);
+
+$queryArray = $search->toArray();
+```
+
+## Adding parameters example
+
+Additional parameters can be added to the aggregation. In the following example we will demonstrate how
+to provide a custom format to the results of the query:
+
+```JSON
+{
+    "aggregations": {
+        "articles_over_time" : {
+            "date_histogram" : {
+                "field" : "date",
+                "interval" : "1M",
+                "format" : "yyyy-MM-dd"
+            }
+        }
+    }
+}
+```
+
+And now the query via DSL:
+
+```php
+
+$dateHistogramAggregation = new DateHistogramAggregation('articles_over_time', 'date', 'month');
+$dateHistogramAggregation->addParameter('format', 'yyyy-MM-dd');
+
+$search = new Search();
+$search->addAggregation($dateHistogramAggregation);
+
+$queryArray = $search->toArray();
+
+```
+[1]: https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-bucket-datehistogram-aggregation.html
\ No newline at end of file

src/Aggregation/DateHistogramAggregation.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 Histogram aggregation.
+ *
+ * @link https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-bucket-datehistogram-aggregation.html
+ */
+class DateHistogramAggregation extends AbstractAggregation
+{
+    use BucketingTrait;
+
+    /**
+     * @var string
+     */
+    protected $interval;
+
+    /**
+     * Inner aggregations container init.
+     *
+     * @param string $name
+     * @param string $field
+     * @param string $interval
+     */
+    public function __construct(
+        $name,
+        $field = null,
+        $interval = null
+    ) {
+        parent::__construct($name);
+
+        $this->setField($field);
+        $this->setInterval($interval);
+    }
+
+    /**
+     * @return int
+     */
+    public function getInterval()
+    {
+        return $this->interval;
+    }
+
+    /**
+     * @param string $interval
+     */
+    public function setInterval($interval)
+    {
+        $this->interval = $interval;
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function getType()
+    {
+        return 'date_histogram';
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function getArray()
+    {
+        if (!$this->getField() || !$this->getInterval()) {
+            throw new \LogicException('Date histogram aggregation must have field and interval set.');
+        }
+
+        $out = [
+            'field' => $this->getField(),
+            'interval' => $this->getInterval(),
+        ];
+        $out = $this->processArray($out);
+
+        return $out;
+    }
+}

tests/Aggregation/DateHistogramAggregationTest.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\DateHistogramAggregation;
+
+/**
+ * Unit test for children aggregation.
+ */
+class DateHistogramAggregationTest extends \PHPUnit_Framework_TestCase
+{
+    /**
+     * Tests if ChildrenAggregation#getArray throws exception when expected.
+     *
+     * @expectedException \LogicException
+     */
+    public function testGetArrayException()
+    {
+        $aggregation = new DateHistogramAggregation('foo');
+        $aggregation->getArray();
+    }
+
+    /**
+     * Tests getType method.
+     */
+    public function testDateHistogramAggregationGetType()
+    {
+        $aggregation = new DateHistogramAggregation('foo');
+        $result = $aggregation->getType();
+        $this->assertEquals('date_histogram', $result);
+    }
+
+    /**
+     * Tests getArray method.
+     */
+    public function testChildrenAggregationGetArray()
+    {
+        $mock = $this->getMockBuilder('ONGR\ElasticsearchDSL\Aggregation\AbstractAggregation')
+            ->disableOriginalConstructor()
+            ->getMockForAbstractClass();
+        $aggregation = new DateHistogramAggregation('foo');
+        $aggregation->addAggregation($mock);
+        $aggregation->setField('date');
+        $aggregation->setInterval('month');
+        $result = $aggregation->getArray();
+        $expected = ['field' => 'date', 'interval' => 'month'];
+        $this->assertEquals($expected, $result);
+    }
+}