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

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
#1677

Author: leflings

CHANGELOG.md

@@ -37,6 +37,7 @@ All notable changes to this project will be documented in this file based on the
 * Move Client configuration in a dedicated class
 * Added `callable` type hinting to `$callback` in `Client` constructor. [#1659](https://github.com/ruflin/Elastica/pull/1659)
 * Added `setTrackTotalHits` method to `Elastica\Query`[#1663](https://github.com/ruflin/Elastica/issues/1663)
+* Allow metadata to be set on Aggregations (via `AbstractAggregation::setMeta(array)`). [#1677](https://github.com/ruflin/Elastica/issues/1677)
 
 ### Improvements
 * Added `native_function_invocation` CS rule [#1606](https://github.com/ruflin/Elastica/pull/1606)

lib/Elastica/Aggregation/AbstractAggregation.php

@@ -8,6 +8,8 @@
 
 abstract class AbstractAggregation extends Param implements NameableInterface
 {
+    protected const METADATA_KEY = 'meta';
+
     /**
      * @var string The name of this aggregation
      */
@@ -80,6 +82,58 @@ public function addAggregation(AbstractAggregation $aggregation): self
         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): self
+    {
+        if (empty($meta)) {
+            return $this->clearMeta();
+        }
+
+        $this->_setRawParam(self::METADATA_KEY, $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(): ?array
+    {
+        return $this->_rawParams[self::METADATA_KEY] ?? null;
+    }
+
+    /**
+     * 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(): self
+    {
+        unset($this->_rawParams[self::METADATA_KEY]);
+
+        return $this;
+    }
+
     /**
      * @return array
      */

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']);
+    }
+}