updated to 7.x-1.11

includes/query.inc

@@ -1,5 +1,10 @@
 <?php
 
+/**
+ * @file
+ * Contains SearchApiQueryInterface and SearchApiQuery.
+ */
+
 /**
  * Interface representing a search query on an Search API index.
  *
@@ -33,6 +38,10 @@ interface SearchApiQueryInterface {
    *     implementation to use.
    *   - 'search id': A string that will be used as the identifier when storing
    *     this search in the Search API's static cache.
+   *   - 'skip result count': If present and set to TRUE, the result's
+   *     "result count" key will not be needed. Service classes can check for
+   *     this option to possibly avoid executing expensive operations to compute
+   *     the result count in cases where it is not needed.
    *   - search_api_access_account: The account which will be used for entity
    *     access checks, if available and enabled for the index.
    *   - search_api_bypass_access: If set to TRUE, entity access checks will be
@@ -62,11 +71,15 @@ interface SearchApiQueryInterface {
    *
    * @param string $conjunction
    *   The conjunction to use for the filter - either 'AND' or 'OR'.
+   * @param $tags
+   *   (Optional) An arbitrary set of tags. Can be used to identify this filter
+   *   down the line if necessary. This is primarily used by the facet system
+   *   to support OR facet queries.
    *
    * @return SearchApiQueryFilterInterface
    *   A filter object that is set to use the specified conjunction.
    */
-  public function createFilter($conjunction = 'AND');
+  public function createFilter($conjunction = 'AND', $tags = array());
 
   /**
    * Sets the keys to search for.
@@ -175,7 +188,9 @@ interface SearchApiQueryInterface {
    *   An associative array containing the search results. The following keys
    *   are standardized:
    *   - 'result count': The overall number of results for this query, without
-   *     range restrictions. Might be approximated, for large numbers.
+   *     range restrictions. Might be approximated, for large numbers, or
+   *     skipped entirely if the "skip result count" option was set on this
+   *     query.
    *   - results: An array of results, ordered as specified. The array keys are
    *     the items' IDs, values are arrays containing the following keys:
    *     - id: The item's ID.
@@ -318,7 +333,8 @@ interface SearchApiQueryInterface {
    * @param mixed $value
    *   The new value of the option.
    *
-   * @return The option's previous value.
+   * @return mixed
+   *   The option's previous value.
    */
   public function setOption($name, $value);
 
@@ -341,12 +357,21 @@ interface SearchApiQueryInterface {
 class SearchApiQuery implements SearchApiQueryInterface {
 
   /**
-   * The index.
+   * The index this query will use.
    *
    * @var SearchApiIndex
    */
   protected $index;
 
+  /**
+   * The index's machine name.
+   *
+   * used during serialization to avoid serializing the whole index object.
+   *
+   * @var string
+   */
+  protected $index_id;
+
   /**
    * The search keys. If NULL, this will be a filter-only search.
    *
@@ -503,9 +528,9 @@ class SearchApiQuery implements SearchApiQueryInterface {
   /**
    * {@inheritdoc}
    */
-  public function createFilter($conjunction = 'AND') {
+  public function createFilter($conjunction = 'AND', $tags = array()) {
     $filter_class = $this->options['filter class'];
-    return new $filter_class($conjunction);
+    return new $filter_class($conjunction, $tags);
   }
 
   /**
@@ -616,6 +641,9 @@ class SearchApiQuery implements SearchApiQueryInterface {
    *
    * @param array $languages
    *   The languages for which results should be returned.
+   *
+   * @throws SearchApiException
+   *   If there was a logical error in the combination of filters and languages.
    */
   protected function addLanguages(array $languages) {
     if (array_search(LANGUAGE_NONE, $languages) === FALSE) {
@@ -776,6 +804,13 @@ class SearchApiQuery implements SearchApiQueryInterface {
     }
   }
 
+  /**
+   * Implements the magic __clone() method to clone the filter, too.
+   */
+  public function __clone() {
+    $this->filter = clone $this->filter;
+  }
+
 }
 
 /**
@@ -790,9 +825,13 @@ interface SearchApiQueryFilterInterface {
    * Constructs a new filter that uses the specified conjunction.
    *
    * @param string $conjunction
-   *   The conjunction to use for this filter - either 'AND' or 'OR'.
+   *   (optional) The conjunction to use for this filter - either 'AND' or 'OR'.
+   * @param array $tags
+   *   (optional) An arbitrary set of tags. Can be used to identify this filter
+   *   down the line if necessary. This is primarily used by the facet system
+   *   to support OR facet queries.
    */
-  public function __construct($conjunction = 'AND');
+  public function __construct($conjunction = 'AND', array $tags = array());
 
   /**
    * Sets this filter's conjunction.
@@ -856,6 +895,25 @@ interface SearchApiQueryFilterInterface {
    */
   public function &getFilters();
 
+  /**
+   * Checks whether a certain tag was set on this filter.
+   *
+   * @param string $tag
+   *   A tag to check for.
+   *
+   * @return bool
+   *   TRUE if the tag was set for this filter, FALSE otherwise.
+   */
+  public function hasTag($tag);
+
+  /**
+   * Retrieves the tags set on this filter.
+   *
+   * @return array
+   *   The tags associated with this filter, as both the array keys and values.
+   */
+  public function &getTags();
+
 }
 
 /**
@@ -883,9 +941,10 @@ class SearchApiQueryFilter implements SearchApiQueryFilterInterface {
   /**
    * {@inheritdoc}
    */
-  public function __construct($conjunction = 'AND') {
+  public function __construct($conjunction = 'AND', array $tags = array()) {
     $this->setConjunction($conjunction);
     $this->filters = array();
+    $this->tags = drupal_map_assoc($tags);
   }
 
   /**
@@ -926,4 +985,29 @@ class SearchApiQueryFilter implements SearchApiQueryFilterInterface {
     return $this->filters;
   }
 
+  /**
+   * {@inheritdoc}
+   */
+  public function hasTag($tag) {
+    return isset($this->tags[$tag]);
+  }
+
+  /**
+   * {@inheritdoc}
+   */
+  public function &getTags() {
+    return $this->tags;
+  }
+
+  /**
+   * Implements the magic __clone() method to clone nested filters, too.
+   */
+  public function __clone() {
+    foreach ($this->filters as $i => $filter) {
+      if (is_object($filter)) {
+        $this->filters[$i] = clone $filter;
+      }
+    }
+  }
+
 }