Allow metadata to be set on AbstractAggregation (ruflin#1677)

ElasticSearch allows metadata to be set on an aggregation that will be
returned as-is with the aggregation result.

See https://www.elastic.co/guide/en/elasticsearch/reference/6.8/agg-metadata.html

Using `setParam` generates invalid query, hence these additions. See
ruflin#1677

CHANGELOG.md

@@ -9,6 +9,7 @@ All notable changes to this project will be documented in this file based on the
 * Always set the Guzzle `base_uri` to support connecting to multiple ES hosts. [#1618](https://github.com/ruflin/Elastica/pull/1618) [#1644](https://github.com/ruflin/Elastica/issues/1644)
 
 ### Added
+* Allow metadata to be set on Aggregations (via `AbstractAggregation::setMeta(array)`). [#1677](https://github.com/ruflin/Elastica/issues/1677)
 
 ### Improvements
 

lib/Elastica/Aggregation/AbstractAggregation.php

@@ -18,6 +18,11 @@ abstract class AbstractAggregation extends Param implements NameableInterface
      */
     protected $_aggs = [];
 
+    /**
+     * @var array|null Metadata belonging to this aggregation
+     */
+    protected $_meta;
+
     /**
      * @param string $name the name of this aggregation
      */
@@ -80,6 +85,54 @@ public function addAggregation(AbstractAggregation $aggregation)
         return $this;
     }
 
+    /**
+     * Add metadata to the aggregation.
+     *
+     * @see https://www.elastic.co/guide/en/elasticsearch/reference/current/agg-metadata.html
+     * @see \Elastica\Aggregation\AbstractAggregation::getMeta()
+     * @see \Elastica\Aggregation\AbstractAggregation::clearMeta()
+     *
+     * @param array $meta Metadata to be attached to the aggregation
+     *
+     * @return $this
+     */
+    public function setMeta(array $meta)
+    {
+        $this->_meta = $meta;
+
+        return $this;
+    }
+
+    /**
+     * Retrieve the currently configured metadata for the aggregation
+     *
+     * @see https://www.elastic.co/guide/en/elasticsearch/reference/current/agg-metadata.html
+     * @see \Elastica\Aggregation\AbstractAggregation::setMeta()
+     * @see \Elastica\Aggregation\AbstractAggregation::clearMeta()
+     *
+     * @return array|null
+     */
+    public function getMeta()
+    {
+        return $this->_meta;
+    }
+
+    /**
+     * Clears any previously set metadata for this aggregation.
+     *
+     * @see https://www.elastic.co/guide/en/elasticsearch/reference/current/agg-metadata.html
+     * @see \Elastica\Aggregation\AbstractAggregation::setMeta()
+     * @see \Elastica\Aggregation\AbstractAggregation::getMeta()
+     *
+     * @return $this
+     */
+    public function clearMeta()
+    {
+        $this->_meta = null;
+
+        return $this;
+    }
+
     /**
      * @return array
      */
@@ -91,6 +144,9 @@ public function toArray()
             // compensate for class name GlobalAggregation
             $array = ['global' => new \stdClass()];
         }
+        if (isset($this->_meta) && sizeof($this->_meta)) {
+            $array['meta'] = $this->_convertArrayable($this->_meta);
+        }
         if (sizeof($this->_aggs)) {
             $array['aggs'] = $this->_convertArrayable($this->_aggs);
         }

test/Elastica/Aggregation/AggregationMetadataTest.php

@@ -0,0 +1,63 @@
+<?php
+
+namespace Elastica\Test\Aggregation;
+
+use Elastica\Aggregation\Cardinality;
+use Elastica\Query;
+
+class AggregationMetadataTest extends BaseAggregationTest
+{
+    protected function _getIndexForTest()
+    {
+        $index = $this->_createIndex();
+
+        $index->refresh();
+
+        return $index;
+    }
+
+    /**
+     * @group functional
+     */
+    public function testAggregationSimpleMetadata()
+    {
+        $aggName = 'mock';
+        $metadata = ['color' => 'blue'];
+
+        $agg = new Cardinality($aggName);
+        $agg->setField('mock_field');
+        $agg->setMeta($metadata);
+
+        $query = new Query();
+        $query->addAggregation($agg);
+        $results = $this->_getIndexForTest()->search($query)->getAggregation($aggName);
+
+        $this->assertEquals($metadata, $results['meta']);
+    }
+
+    /**
+     * @group functional
+     */
+    public function testAggregationComplexMetadata()
+    {
+        $aggName = 'mock';
+        $metadata = [
+            'color' => 'blue',
+            'status' => 'green',
+            'users' => [
+                'foo' => 'bar',
+                'moo' => 'baz',
+            ],
+        ];
+
+        $agg = new Cardinality($aggName);
+        $agg->setField('mock_field');
+        $agg->setMeta($metadata);
+
+        $query = new Query();
+        $query->addAggregation($agg);
+        $results = $this->_getIndexForTest()->search($query)->getAggregation($aggName);
+
+        $this->assertEquals($metadata, $results['meta']);
+    }
+}