Set excludes and terms fluently on facet fields (#1070)

* Set excludes and terms fluently on facet fields * Additional test coverage --------- Co-authored-by: Markus Kalkbrenner <[email protected]>
solariumphp · Jun 13, 2023 · 2629538 · 2629538
1 parent b780170
commit 2629538
Show file tree

Hide file tree

Showing 32 changed files with 914 additions and 111 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -11,10 +11,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Solarium\Core\Query\Result\QueryType::getStatus() and getQueryTime(), inherited by all Solarium\QueryType Results
 - Solarium\QueryType\CoreAdmin\Result\Result::getInitFailureResults()
 - Solarium\QueryType\Ping\Result::getPingStatus() and getZkConnected()
+- Fluent interface methods for adding/removing excludes in Solarium\Component\Facet\AbstractFacet
+- Fluent interface methods for adding/removing terms in Solarium\Component\Facet\Field
 
 ### Fixed
 - JSON serialization of arrays with non-consecutive indices in multivalue fields
 - PHP 8.2 deprecations
+- Handling of escaped literal commas in local parameters for faceting
 
 ### Changed
 - Update queries use the JSON request format by default
@@ -27,6 +30,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Solarium\QueryType\Server\Collections\Result\CreateResult::getStatus(), use getCreateStatus() instead
 - Solarium\QueryType\Server\Collections\Result\DeleteResult::getStatus(), use getDeleteStatus() instead
 - Solarium\QueryType\Server\Collections\Result\ReloadResult::getStatus(), use getReloadStatus() instead
+- LocalParameters::removeTerms(), use removeTerm() instead
 
 
 ## [6.2.8]

diff --git a/...lect-query/building-a-select-query/components/facetset-component/facet-field.md b/...lect-query/building-a-select-query/components/facetset-component/facet-field.md
@@ -7,9 +7,10 @@ The options below can be set as query option values, but also by using the set/g
 
 Only the facet-type specific options are listed. See [FacetSet component](facetset-component.md) for the options shared by all facet types.
 
-| Name  | Type   | Default value | Description                    |
-|-------|--------|---------------|--------------------------------|
-| field | string | id            | The index field for the facet. |
+| Name        | Type   | Default value | Description                                                                                         |
+|-------------|--------|---------------|-----------------------------------------------------------------------------------------------------|
+| field       | string | id            | The index field for the facet.                                                                      |
+| local_terms | string | null          | Limit field facet to specified terms. Specify a comma separated list. Use `\,` for a literal comma. |
 ||
 
 Example

diff --git a/...ery/building-a-select-query/components/facetset-component/facetset-component.md b/...ery/building-a-select-query/components/facetset-component/facetset-component.md
@@ -32,10 +32,10 @@ Standard facet options
 
 All facet types available in the facetset extend a base class that offers a standard set of options. The following options are available for ALL facet types:
 
-| Name     | Type   | Default value | Description                                                 |
-|----------|--------|---------------|-------------------------------------------------------------|
-| key      | string | null          | Key to identify the facet (mandatory)                       |
-| excludes | string | null          | Add one or multiple filterquery tags to exclude for a facet |
+| Name          | Type   | Default value | Description                                                  |
+|---------------|--------|---------------|--------------------------------------------------------------|
+| local_key     | string | null          | Key to identify the facet (mandatory).                       |
+| local_exclude | string | null          | Add one or multiple filterquery tags to exclude for a facet. |
 ||
 
 Pivot facet options

diff --git a/examples/2.1.5.1.1.1-facet-field-filters.php b/examples/2.1.5.1.1.1-facet-field-filters.php
@@ -29,12 +29,16 @@
 $facetSet->createFacetField('electronicsAndMore')->setField('cat')->setMatches('electronics.+');
 
 // setExcludeTerms takes a comma separated list of terms to exclude from the facet
-// escape the comma for a literal match e.g. 'yes\, this facet with be excluded'
+// escape the comma for a literal match e.g. 'yes\, this term will be excluded'
 $facetSet->createFacetField('electronicsExclude')->setField('cat')->setExcludeTerms('electronics,music');
 
 // all three restriction types can also be used on the facetset as a whole and will affect all (non json) facets
 // e.g. $facetSet->setExcludeTerms('search');
 
+// setTerms takes a comma separated list of terms to exclude from the facet
+// escape the comma for a literal match e.g. 'yes\, this term will be included'
+$facetSet->createFacetField('electronicsTerms')->setField('cat')->setTerms('electronics,music');
+
 // this executes the query and returns the result
 $resultset = $client->select($query);
 
@@ -76,4 +80,11 @@
     echo $value . ' [' . $count . ']<br/>';
 }
 
+// display facet counts
+echo '<hr/>Facet counts for field "cat"; terms limited to "electronics" and "music":<br/>';
+$facet = $resultset->getFacetSet()->getFacet('electronicsTerms');
+foreach ($facet as $value => $count) {
+    echo $value . ' [' . $count . ']<br/>';
+}
+
 htmlFooter();
diff --git a/examples/2.1.5.1.1.2-facet-field-excludes.php b/examples/2.1.5.1.1.2-facet-field-excludes.php
@@ -22,7 +22,7 @@
 $facetSet->createFacetField('category')->setField('cat');
 
 // addExcludes will exclude filters by tag
-$facetSet->createFacetField('unfiltered')->setField('cat')->getLocalParameters()->addExcludes(['electronics']);
+$facetSet->createFacetField('unfiltered')->setField('cat')->addExcludes(['electronics']);
 
 // this executes the query and returns the result
 $resultset = $client->select($query);

diff --git a/examples/2.1.5.1.4.3-facet-range-excludes.php b/examples/2.1.5.1.4.3-facet-range-excludes.php
@@ -32,7 +32,7 @@
 $facet->setStart(1);
 $facet->setGap(100);
 $facet->setEnd(1000);
-$facet->getLocalParameters()->addExcludes(['budget']);
+$facet->addExcludes(['budget']);
 
 // this executes the query and returns the result
 $resultset = $client->select($query);

diff --git a/src/Component/Facet/AbstractFacet.php b/src/Component/Facet/AbstractFacet.php
@@ -47,10 +47,94 @@ public function getKey(): ?string
      *
      * @return self Provides fluent interface
      */
-    public function setKey(string $key): FacetInterface
+    public function setKey(string $key): self
     {
         $this->getLocalParameters()->setKey($key);
 
         return $this;
     }
+
+    /**
+     * Add an exclude tag.
+     *
+     * @param string $exclude
+     *
+     * @return self Provides fluent interface
+     */
+    public function addExclude(string $exclude)
+    {
+        $this->getLocalParameters()->setExclude($exclude);
+
+        return $this;
+    }
+
+    /**
+     * Add multiple exclude tags.
+     *
+     * @param array|string $excludes array or string with comma separated exclude tags
+     *
+     * @return self Provides fluent interface
+     */
+    public function addExcludes($excludes)
+    {
+        if (\is_string($excludes)) {
+            $excludes = preg_split('/(?<!\\\\),/', $excludes);
+        }
+
+        $this->getLocalParameters()->addExcludes($excludes);
+
+        return $this;
+    }
+
+    /**
+     * Set the list of exclude tags.
+     *
+     * This overwrites any existing exclude tags.
+     *
+     * @param array|string $excludes
+     *
+     * @return self Provides fluent interface
+     */
+    public function setExcludes($excludes)
+    {
+        $this->clearExcludes()->addExcludes($excludes);
+
+        return $this;
+    }
+
+    /**
+     * Remove a single exclude tag.
+     *
+     * @param string $exclude
+     *
+     * @return self Provides fluent interface
+     */
+    public function removeExclude(string $exclude)
+    {
+        $this->getLocalParameters()->removeExclude($exclude);
+
+        return $this;
+    }
+
+    /**
+     * Remove all exclude tags.
+     *
+     * @return self Provides fluent interface
+     */
+    public function clearExcludes()
+    {
+        $this->getLocalParameters()->clearExcludes();
+
+        return $this;
+    }
+
+    /**
+     * Get the list of exclude tags.
+     *
+     * @return array
+     */
+    public function getExcludes(): array
+    {
+        return $this->getLocalParameters()->getExcludes();
+    }
 }
diff --git a/src/Component/Facet/AbstractRange.php b/src/Component/Facet/AbstractRange.php
@@ -9,8 +9,6 @@
 
 namespace Solarium\Component\Facet;
 
-use Solarium\Core\Configurable;
-
 /**
  * Facet range.
  *
@@ -272,11 +270,13 @@ public function getInclude(): array
     /**
      * @param \Solarium\Component\Facet\Pivot|array $pivot
      *
-     * @return \Solarium\Core\Configurable
+     * @return self Provides fluent interface
      */
-    public function setPivot($pivot): Configurable
+    public function setPivot($pivot): self
     {
-        return $this->setOption('pivot', $pivot);
+        $this->setOption('pivot', $pivot);
+
+        return $this;
     }
 
     /**

diff --git a/src/Component/Facet/FacetInterface.php b/src/Component/Facet/FacetInterface.php
@@ -37,7 +37,59 @@ public function getKey(): ?string;
      *
      * @param string $key
      *
-     * @return self
+     * @return self Provides fluent interface
      */
-    public function setKey(string $key): self;
+    public function setKey(string $key);
+
+    /**
+     * Add an exclude tag.
+     *
+     * @param string $exclude
+     *
+     * @return self Provides fluent interface
+     */
+    public function addExclude(string $exclude);
+
+    /**
+     * Add multiple exclude tags.
+     *
+     * @param array|string $excludes array or string with comma separated exclude tags
+     *
+     * @return self Provides fluent interface
+     */
+    public function addExcludes($excludes);
+
+    /**
+     * Set the list of exclude tags.
+     *
+     * This overwrites any existing exclude tags.
+     *
+     * @param array|string $excludes
+     *
+     * @return self Provides fluent interface
+     */
+    public function setExcludes($excludes);
+
+    /**
+     * Remove a single exclude tag.
+     *
+     * @param string $exclude
+     *
+     * @return self Provides fluent interface
+     */
+    public function removeExclude(string $exclude);
+
+    /**
+     * Remove all exclude tags.
+     *
+     * @return self Provides fluent interface
+     */
+    public function clearExcludes();
+
+    /**
+     * Get the list of exclude tags.
+     *
+     * @return array
+     */
+    public function getExcludes();
 }
diff --git a/src/Component/Facet/Field.php b/src/Component/Facet/Field.php
@@ -62,4 +62,88 @@ public function getField(): ?string
     {
         return $this->getOption('field');
     }
+
+    /**
+     * Add a term.
+     *
+     * @param string $term
+     *
+     * @return self Provides fluent interface
+     */
+    public function addTerm(string $term): self
+    {
+        $this->getLocalParameters()->setTerm($term);
+
+        return $this;
+    }
+
+    /**
+     * Add multiple terms.
+     *
+     * @param array|string $terms array or string with comma separated terms
+     *
+     * @return self Provides fluent interface
+     */
+    public function addTerms($terms): self
+    {
+        if (\is_string($terms)) {
+            $terms = preg_split('/(?<!\\\\),/', $terms);
+        }
+
+        $this->getLocalParameters()->addTerms($terms);
+
+        return $this;
+    }
+
+    /**
+     * Set the list of terms.
+     *
+     * This overwrites any existing terms.
+     *
+     * @param array|string $terms
+     *
+     * @return self Provides fluent interface
+     */
+    public function setTerms($terms): self
+    {
+        $this->clearTerms()->addTerms($terms);
+
+        return $this;
+    }
+
+    /**
+     * Remove a single term.
+     *
+     * @param string $term
+     *
+     * @return self Provides fluent interface
+     */
+    public function removeTerm(string $term): self
+    {
+        $this->getLocalParameters()->removeTerm($term);
+
+        return $this;
+    }
+
+    /**
+     * Remove all terms.
+     *
+     * @return self Provides fluent interface
+     */
+    public function clearTerms(): self
+    {
+        $this->getLocalParameters()->clearTerms();
+
+        return $this;
+    }
+
+    /**
+     * Get the list of terms.
+     *
+     * @return array
+     */
+    public function getTerms(): array
+    {
+        return $this->getLocalParameters()->getTerms();
+    }
 }