Extract setting gap policy to trait (#2023)

The purpose of the introduced interface is to avoid typos by using constants for options.

That said, it also fixed the typo on Serial differencing aggregation, which is/was also a typo in the official docs. See elastic/elasticsearch#80893

CHANGELOG.md

@@ -17,6 +17,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 * Triggered deprecation in `Elastica\Result::getType()` method [#2016](https://github.com/ruflin/Elastica/pull/2016)
 * Updated `php-cs-fixer` to `3.3.2` [#2022](https://github.com/ruflin/Elastica/pull/2022)
 * Updated `composer-normalize` to `2.15.0` [#2021](https://github.com/ruflin/Elastica/pull/2021)
+* Extracted setting gap policy to `\Elastica\Aggregation\Traits\GapPolicyTrait` and introduced `\Elastica\Aggregation\GapPolicyInterface` with constants for options [#2023](https://github.com/ruflin/Elastica/pull/2023)
 ### Deprecated
 * Deprecated `Elastica\Query\Common` class, use `Elastica\Query\MatchQuery` instead [#2013](https://github.com/ruflin/Elastica/pull/2013)
 * Deprecated `Elastica\QueryBuilder\DSL\Query::common_terms()`, use `match()` instead [#2013](https://github.com/ruflin/Elastica/pull/2013)

src/Aggregation/AvgBucket.php

@@ -9,9 +9,10 @@
  *
  * @see https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-pipeline-avg-bucket-aggregation.html
  */
-class AvgBucket extends AbstractAggregation
+class AvgBucket extends AbstractAggregation implements GapPolicyInterface
 {
-    public const DEFAULT_GAP_POLICY_VALUE = 'skip';
+    use Traits\GapPolicyTrait;
+
     public const DEFAULT_FORMAT_VALUE = null;
 
     public function __construct(string $name, ?string $bucketsPath = null)
@@ -33,16 +34,6 @@ public function setBucketsPath(string $bucketsPath): self
         return $this->setParam('buckets_path', $bucketsPath);
     }
 
-    /**
-     * Set the gap policy for this aggregation.
-     *
-     * @return $this
-     */
-    public function setGapPolicy(string $gapPolicy): self
-    {
-        return $this->setParam('gap_policy', $gapPolicy);
-    }
-
     /**
      * Set the format for this aggregation.
      *

src/Aggregation/BucketScript.php

@@ -9,8 +9,10 @@
  *
  * @see https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-pipeline-bucket-script-aggregation.html
  */
-class BucketScript extends AbstractAggregation
+class BucketScript extends AbstractAggregation implements GapPolicyInterface
 {
+    use Traits\GapPolicyTrait;
+
     public function __construct(string $name, ?array $bucketsPath = null, ?string $script = null)
     {
         parent::__construct($name);
@@ -44,16 +46,6 @@ public function setScript(string $script): self
         return $this->setParam('script', $script);
     }
 
-    /**
-     * Set the gap policy for this aggregation.
-     *
-     * @return $this
-     */
-    public function setGapPolicy(string $gapPolicy = 'skip'): self
-    {
-        return $this->setParam('gap_policy', $gapPolicy);
-    }
-
     /**
      * Set the format for this aggregation.
      *

src/Aggregation/BucketSelector.php

@@ -7,8 +7,10 @@
  *
  * @see https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-pipeline-bucket-selector-aggregation.html
  */
-class BucketSelector extends AbstractSimpleAggregation
+class BucketSelector extends AbstractSimpleAggregation implements GapPolicyInterface
 {
+    use Traits\GapPolicyTrait;
+
     public function __construct(string $name, ?array $bucketsPath = null, ?string $script = null)
     {
         parent::__construct($name);
@@ -31,14 +33,4 @@ public function setBucketsPath(array $bucketsPath): self
     {
         return $this->setParam('buckets_path', $bucketsPath);
     }
-
-    /**
-     * Set the gap policy for this aggregation.
-     *
-     * @return $this
-     */
-    public function setGapPolicy(string $gapPolicy = 'skip'): self
-    {
-        return $this->setParam('gap_policy', $gapPolicy);
-    }
 }

src/Aggregation/Derivative.php

@@ -9,8 +9,10 @@
  *
  * @see https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-pipeline-derivative-aggregation.html
  */
-class Derivative extends AbstractAggregation
+class Derivative extends AbstractAggregation implements GapPolicyInterface
 {
+    use Traits\GapPolicyTrait;
+
     public function __construct(string $name, ?string $bucketsPath = null)
     {
         parent::__construct($name);
@@ -30,16 +32,6 @@ public function setBucketsPath(string $bucketsPath): self
         return $this->setParam('buckets_path', $bucketsPath);
     }
 
-    /**
-     * Set the gap policy for this aggregation.
-     *
-     * @return $this
-     */
-    public function setGapPolicy(string $gapPolicy = 'skip'): self
-    {
-        return $this->setParam('gap_policy', $gapPolicy);
-    }
-
     /**
      * Set the format for this aggregation.
      *

src/Aggregation/ExtendedStatsBucket.php

@@ -7,8 +7,10 @@
  *
  * @see https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-pipeline-extended-stats-bucket-aggregation.html
  */
-class ExtendedStatsBucket extends AbstractAggregation
+class ExtendedStatsBucket extends AbstractAggregation implements GapPolicyInterface
 {
+    use Traits\GapPolicyTrait;
+
     public function __construct(string $name, string $bucketsPath)
     {
         parent::__construct($name);
@@ -20,11 +22,6 @@ public function setBucketsPath(string $bucketsPath): self
         return $this->setParam('buckets_path', $bucketsPath);
     }
 
-    public function setGapPolicy(string $gapPolicy): self
-    {
-        return $this->setParam('gap_policy', $gapPolicy);
-    }
-
     public function setFormat(string $format): self
     {
         return $this->setParam('format', $format);

src/Aggregation/GapPolicyInterface.php

@@ -0,0 +1,36 @@
+<?php
+
+namespace Elastica\Aggregation;
+
+use Elastica\Aggregation\Traits\GapPolicyTrait;
+
+/**
+ * Dealing with gaps in the data.
+ *
+ * @see https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-pipeline.html#gap-policy
+ * @see GapPolicyTrait
+ */
+interface GapPolicyInterface
+{
+    /**
+     * Treats missing data as if the bucket does not exist. It will skip the bucket and continue calculating using the next available value.
+     */
+    public const SKIP = 'skip';
+
+    /**
+     * Will replace missing values with a zero (0) and pipeline aggregation computation will proceed as normal.
+     */
+    public const INSERT_ZEROS = 'insert_zeros';
+
+    /**
+     * Is similar to skip, except if the metric provides a non-null, non-NaN value this value is used, otherwise the empty bucket is skipped.
+     */
+    public const KEEP_VALUES = 'keep_values';
+
+    /**
+     * Set the gap policy for this aggregation.
+     *
+     * @return $this
+     */
+    public function setGapPolicy(string $gapPolicy);
+}

src/Aggregation/PercentilesBucket.php

@@ -9,8 +9,9 @@
  *
  * @see https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-pipeline-percentiles-bucket-aggregation.html
  */
-class PercentilesBucket extends AbstractAggregation
+class PercentilesBucket extends AbstractAggregation implements GapPolicyInterface
 {
+    use Traits\GapPolicyTrait;
     use Traits\KeyedTrait;
 
     /**
@@ -46,14 +47,6 @@ public function setBucketsPath(string $bucketsPath): self
         return $this->setParam('buckets_path', $bucketsPath);
     }
 
-    /**
-     * Set the gap policy for this aggregation.
-     */
-    public function setGapPolicy(string $gapPolicy): self
-    {
-        return $this->setParam('gap_policy', $gapPolicy);
-    }
-
     /**
      * Set the format for this aggregation.
      */

src/Aggregation/SerialDiff.php

@@ -9,9 +9,9 @@
  *
  * @see https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-pipeline-serialdiff-aggregation.html
  */
-class SerialDiff extends AbstractAggregation
+class SerialDiff extends AbstractAggregation implements GapPolicyInterface
 {
-    public const DEFAULT_GAP_POLICY_VALUE = 'insert_zero';
+    public const DEFAULT_GAP_POLICY_VALUE = GapPolicyInterface::INSERT_ZEROS;
 
     public function __construct(string $name, ?string $bucketsPath = null)
     {
@@ -47,7 +47,7 @@ public function setLag(int $lag = 1): self
      *
      * @return $this
      */
-    public function setGapPolicy(string $gapPolicy): self
+    public function setGapPolicy(string $gapPolicy = self::DEFAULT_GAP_POLICY_VALUE): self
     {
         return $this->setParam('gap_policy', $gapPolicy);
     }

src/Aggregation/StatsBucket.php

@@ -9,8 +9,10 @@
  *
  * @see https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-pipeline-stats-bucket-aggregation.html
  */
-class StatsBucket extends AbstractAggregation
+class StatsBucket extends AbstractAggregation implements GapPolicyInterface
 {
+    use Traits\GapPolicyTrait;
+
     public function __construct(string $name, ?string $bucketsPath = null)
     {
         parent::__construct($name);
@@ -30,16 +32,6 @@ public function setBucketsPath(string $bucketsPath): self
         return $this->setParam('buckets_path', $bucketsPath);
     }
 
-    /**
-     * Set the gap policy for this aggregation.
-     *
-     * @return $this
-     */
-    public function setGapPolicy(string $gapPolicy): self
-    {
-        return $this->setParam('gap_policy', $gapPolicy);
-    }
-
     /**
      * Set the format for this aggregation.
      *

src/Aggregation/SumBucket.php

@@ -9,8 +9,10 @@
  *
  * @see https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-pipeline-sum-bucket-aggregation.html
  */
-class SumBucket extends AbstractAggregation
+class SumBucket extends AbstractAggregation implements GapPolicyInterface
 {
+    use Traits\GapPolicyTrait;
+
     public function __construct(string $name, ?string $bucketsPath = null)
     {
         parent::__construct($name);
@@ -30,16 +32,6 @@ public function setBucketsPath(string $bucketsPath): self
         return $this->setParam('buckets_path', $bucketsPath);
     }
 
-    /**
-     * Set the gap policy for this aggregation.
-     *
-     * @return $this
-     */
-    public function setGapPolicy(string $gapPolicy): self
-    {
-        return $this->setParam('gap_policy', $gapPolicy);
-    }
-
     /**
      * Set the format for this aggregation.
      *

src/Aggregation/Traits/GapPolicyTrait.php

@@ -0,0 +1,16 @@
+<?php
+
+namespace Elastica\Aggregation\Traits;
+
+use Elastica\Aggregation\GapPolicyInterface;
+
+/**
+ * @see GapPolicyInterface
+ */
+trait GapPolicyTrait
+{
+    public function setGapPolicy(string $gapPolicy = GapPolicyInterface::SKIP): self
+    {
+        return $this->setParam('gap_policy', $gapPolicy);
+    }
+}