fixes #744, deprecate erroneous Helper::cacheControl() (#748)

* fixes #744, deprecate erromneous Helper::cacheControl() and add cache and cost local params

CHANGELOG.md

@@ -8,10 +8,14 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 ### Added
 - Range facet pivot support
 - Support for useConfiguredElevatedOrder
+- FilterQuery::setCache and FilterQuery::setCost()
 
 ### Fixed
 - setting limit for pivot facets
 
+### Deprecated
+- Helper::cacheControl(). Use FilterQuery::setCache() and FilterQuery::setCost() instead.
+
 
 ## [5.1.5]
 ### Security

src/Core/Query/Helper.php

@@ -427,6 +427,8 @@ public function qparserTerm(string $field, float $weight): string
      * @param float|null $cost
      *
      * @return string
+     *
+     * @deprecated Will be removed in Solarium 6. Use FilterQuery::setCache() and FilterQuery::setCost() instead.
      */
     public function cacheControl(bool $useCache, float $cost = null): string
     {

src/Core/Query/LocalParameters/LocalParameter.php

@@ -39,6 +39,10 @@ class LocalParameter implements LocalParameterInterface
 
     public const TYPE_VALUE = 'v';
 
+    public const TYPE_CACHE = 'cache';
+
+    public const TYPE_COST = 'cost';
+
     public const PARAMETER_MAP = [
         self::TYPE_KEY => 'local_key',
         self::TYPE_EXCLUDE => 'local_exclude',
@@ -54,6 +58,8 @@ class LocalParameter implements LocalParameterInterface
         self::TYPE_MEAN => 'local_mean',
         self::TYPE_MIN => 'local_min',
         self::TYPE_VALUE => 'local_value',
+        self::TYPE_CACHE => 'local_cache',
+        self::TYPE_COST => 'local_cost',
     ];
 
     /**

src/Core/Query/LocalParameters/LocalParameters.php

@@ -744,6 +744,70 @@ public function getLocalValues(): array
         return $this->getValues(LocalParameter::TYPE_VALUE);
     }
 
+    /**
+     * @param bool $cache
+     *
+     * @throws \Solarium\Exception\OutOfBoundsException
+     *
+     * @return $this
+     */
+    public function setCache(bool $cache): self
+    {
+        return $this->clearCache()->addValue(LocalParameter::TYPE_CACHE, $cache ? 'true' : 'false');
+    }
+
+    /**
+     * @throws \Solarium\Exception\OutOfBoundsException
+     *
+     * @return $this
+     */
+    public function clearCache(): self
+    {
+        return $this->clearValues(LocalParameter::TYPE_CACHE);
+    }
+
+    /**
+     * @throws \Solarium\Exception\OutOfBoundsException
+     *
+     * @return array
+     */
+    public function getCache(): array
+    {
+        return $this->getValues(LocalParameter::TYPE_CACHE);
+    }
+
+    /**
+     * @param int $cost
+     *
+     * @throws \Solarium\Exception\OutOfBoundsException
+     *
+     * @return $this
+     */
+    public function setCost(int $cost): self
+    {
+        return $this->clearCost()->addValue(LocalParameter::TYPE_COST, $cost);
+    }
+
+    /**
+     * @throws \Solarium\Exception\OutOfBoundsException
+     *
+     * @return $this
+     */
+    public function clearCost(): self
+    {
+        return $this->clearValues(LocalParameter::TYPE_COST);
+    }
+
+    /**
+     * @throws \Solarium\Exception\OutOfBoundsException
+     *
+     * @return array
+     */
+    public function getCost(): array
+    {
+        return $this->getValues(LocalParameter::TYPE_COST);
+    }
+
     /**
      * {@inheritdoc}
      */

src/Core/Query/LocalParameters/LocalParametersTrait.php

@@ -150,8 +150,8 @@ protected function initLocalParameters(): void
 
                     $this->getLocalParameters()->addExcludes($value);
                     unset($this->options[$name]);
-
                     break;
+
                 case 'key':
                     if ($this instanceof FilterQuery) {
                         break;
@@ -160,8 +160,8 @@ protected function initLocalParameters(): void
                 case LocalParameter::PARAMETER_MAP[LocalParameter::TYPE_KEY]:
                     $this->getLocalParameters()->setKey($value);
                     unset($this->options[$name]);
-
                     break;
+
                 case 'tag':
                     @trigger_error('setting local parameter using the "tag" option is deprecated in Solarium 5 and will be removed in Solarium 6. Use "local_tag" instead', E_USER_DEPRECATED);
                 case LocalParameter::PARAMETER_MAP[LocalParameter::TYPE_TAG]:
@@ -171,17 +171,17 @@ protected function initLocalParameters(): void
 
                     $this->getLocalParameters()->addTags($value);
                     unset($this->options[$name]);
-
                     break;
+
                 case LocalParameter::PARAMETER_MAP[LocalParameter::TYPE_RANGE]:
                     if (!\is_array($value)) {
                         $value = explode(',', $value);
                     }
 
                     $this->getLocalParameters()->addRanges($value);
                     unset($this->options[$name]);
-
                     break;
+
                 case 'stats':
                     @trigger_error('setting local parameter using the "stats" option is deprecated in Solarium 5 and will be removed in Solarium 6. Use "local_stats" instead', E_USER_DEPRECATED);
                 case LocalParameter::PARAMETER_MAP[LocalParameter::TYPE_STAT]:
@@ -191,56 +191,65 @@ protected function initLocalParameters(): void
 
                     $this->getLocalParameters()->addStats($value);
                     unset($this->options[$name]);
-
                     break;
+
                 case LocalParameter::PARAMETER_MAP[LocalParameter::TYPE_TERM]:
                     if (!\is_array($value)) {
                         $value = explode(',', $value);
                     }
 
                     $this->getLocalParameters()->addTerms($value);
                     unset($this->options[$name]);
-
                     break;
+
                 case LocalParameter::PARAMETER_MAP[LocalParameter::TYPE_TYPE]:
                     $this->getLocalParameters()->setType($value);
                     unset($this->options[$name]);
-
                     break;
+
                 case LocalParameter::PARAMETER_MAP[LocalParameter::TYPE_QUERY]:
                     $this->getLocalParameters()->setQuery($value);
                     unset($this->options[$name]);
-
                     break;
+
                 case LocalParameter::PARAMETER_MAP[LocalParameter::TYPE_QUERY_FIELD]:
                     $this->getLocalParameters()->setQueryField($value);
                     unset($this->options[$name]);
-
                     break;
+
                 case LocalParameter::PARAMETER_MAP[LocalParameter::TYPE_DEFAULT_FIELD]:
                     $this->getLocalParameters()->setDefaultField($value);
                     unset($this->options[$name]);
-
                     break;
+
                 case LocalParameter::PARAMETER_MAP[LocalParameter::TYPE_MAX]:
                     $this->getLocalParameters()->setMax($value);
                     unset($this->options[$name]);
-
                     break;
+
                 case LocalParameter::PARAMETER_MAP[LocalParameter::TYPE_MEAN]:
                     $this->getLocalParameters()->setMean($value);
                     unset($this->options[$name]);
-
                     break;
+
                 case LocalParameter::PARAMETER_MAP[LocalParameter::TYPE_MIN]:
                     $this->getLocalParameters()->setMin($value);
                     unset($this->options[$name]);
-
                     break;
+
                 case LocalParameter::PARAMETER_MAP[LocalParameter::TYPE_VALUE]:
                     $this->getLocalParameters()->setLocalValue($value);
                     unset($this->options[$name]);
+                    break;
 
+                case LocalParameter::PARAMETER_MAP[LocalParameter::TYPE_CACHE]:
+                    $this->getLocalParameters()->setCache($value);
+                    unset($this->options[$name]);
+                    break;
+
+                case LocalParameter::PARAMETER_MAP[LocalParameter::TYPE_COST]:
+                    $this->getLocalParameters()->setCost($value);
+                    unset($this->options[$name]);
                     break;
             }
         }

src/QueryType/Select/Query/FilterQuery.php

@@ -136,6 +136,58 @@ public function setTags(array $tags): self
         return $this;
     }
 
+    /**
+     * Cache the filter query or not.
+     *
+     * @param bool $cache
+     *
+     * @return self Provides fluent interface
+     */
+    public function setCache(bool $cache): self
+    {
+        $this->getLocalParameters()->setCache($cache);
+
+        return $this;
+    }
+
+    /**
+     * Get the information if the filter query should be cached or not.
+     *
+     * @return bool
+     */
+    public function getCache(): bool
+    {
+        $cache = $this->getLocalParameters()->getCache();
+        // The default is to cache the filter Query.
+        return 'false' !== reset($cache);
+    }
+
+    /**
+     * Set the cost to cache the filter query.
+     *
+     * @param int $cost
+     *
+     * @return self Provides fluent interface
+     */
+    public function setCost(int $cost): self
+    {
+        $this->getLocalParameters()->setCost($cost);
+
+        return $this;
+    }
+
+    /**
+     * Get the cost of the filter query to be cached or not.
+     *
+     * @return int
+     */
+    public function getCost(): int
+    {
+        $cost = $this->getLocalParameters()->getCost();
+        // The default cost for filter queries is 0.
+        return (int) reset($cost);
+    }
+
     /**
      * Returns a query helper.
      *

tests/QueryType/Select/Query/FilterQueryTest.php

@@ -82,4 +82,22 @@ public function testSetTags()
         $this->filterQuery->setTags(['t3', 't4']);
         $this->assertSame(['t3', 't4'], $this->filterQuery->getTags());
     }
+
+    public function testSetAndGetCache()
+    {
+        $this->assertTrue($this->filterQuery->getCache());
+        $this->filterQuery->setCache(false);
+        $this->assertFalse($this->filterQuery->getCache());
+        $this->filterQuery->setCache(true);
+        $this->assertTrue($this->filterQuery->getCache());
+    }
+
+    public function testSetAndGetCost()
+    {
+        $this->assertSame(0, $this->filterQuery->getCost());
+        $this->filterQuery->setCost(123);
+        $this->assertSame(123, $this->filterQuery->getCost());
+        $this->filterQuery->setCost(99);
+        $this->assertSame(99, $this->filterQuery->getCost());
+    }
 }

tests/QueryType/Select/RequestBuilderTest.php

@@ -93,6 +93,25 @@ public function testSelectUrlWithSortAndFilters()
         );
     }
 
+    public function testSelectUrlWithCachedFilters()
+    {
+        $this->query->addFilterQuery(
+            new FilterQuery(['key' => 'f1', 'query' => 'published:true', 'local_cache' => false, 'local_cost' => 95])
+        );
+        $this->query->addFilterQuery(
+            new FilterQuery(['key' => 'f2', 'local_tag' => ['t1', 't2'], 'query' => 'category:23', 'local_cache' => true])
+        );
+        $request = $this->builder->build($this->query);
+
+        $this->assertNull($request->getRawData());
+
+        $this->assertSame(
+            'select?omitHeader=true&wt=json&json.nl=flat&q=*:*&start=0&rows=10&fl=*,score'.
+            '&fq={!cache=false cost=95}published:true&fq={!tag=t1,t2 cache=true}category:23',
+            urldecode($request->getUri())
+        );
+    }
+
     public function testWithComponentNoBuilder()
     {
         $this->builder->build($this->query);