class SearchApiSolrDocument in Search API Solr 7

Holds Key / Value pairs that represent a Solr Document along with any associated boost values. Field values can be accessed by direct dereferencing such as:

$document->title = 'Something';
echo $document->title;

Additionally, the field values can be iterated with foreach:

foreach ($document as $fieldName => $fieldValue) {

  // ...
}

Hierarchy

class \SearchApiSolrDocument implements \IteratorAggregate

Expanded class hierarchy of SearchApiSolrDocument

File

includes/document.inc, line 76

View source

class SearchApiSolrDocument implements IteratorAggregate {

  /**
   * Document boost value.
   *
   * @var float|false
   */
  protected $documentBoost = FALSE;

  /**
   * Document field values, indexed by name.
   *
   * @var array
   */
  protected $fields = array();

  /**
   * Document field boost values, indexed by name.
   *
   * @var array
   */
  protected $fieldBoosts = array();

  /**
   * Document field update values, indexed by name.
   *
   * @var array
   */
  protected $fieldUpdates = array();

  /**
   * Document nested objects.
   *
   * @var SearchApiSolrDocument[]
   */
  protected $nestedObjects = array();

  /**
   * Clears all boosts and fields from this document.
   */
  public function clear() {
    $this->documentBoost = FALSE;
    $this->fields = array();
    $this->fieldBoosts = array();
    $this->fieldUpdates = array();
    $this->nestedObjects = array();
  }

  /**
   * Gets the current document boost.
   *
   * @return float|false
   *   The current document boost, or FALSE if none is set.
   */
  public function getBoost() {
    return $this->documentBoost;
  }

  /**
   * Sets the document boost factor.
   *
   * @param float|false $boost
   *   FALSE for default boost, or a positive number for setting a document
   *   boost.
   */
  public function setBoost($boost) {
    $boost = (double) $boost;
    if ($boost > 0.0) {
      $this->documentBoost = $boost;
    }
    else {
      $this->documentBoost = FALSE;
    }
  }

  /**
   * Adds a value to a multi-valued field
   *
   * NOTE: the solr XML format allows you to specify boosts PER value even
   * though the underlying Lucene implementation only allows a boost per field.
   * To remedy this, the final field boost value will be the product of all
   * specified boosts on field values - this is similar to SolrJ's
   * functionality.
   *
   * @code
   *   $doc = new ApacheSolrDocument();
   *   $doc->addField('foo', 'bar', 2.0);
   *   $doc->addField('foo', 'baz', 3.0);
   *   // Resultant field boost will be 6!
   *   echo $doc->getFieldBoost('foo');
   * @endcode
   *
   * @param string $key
   *   The name of the field.
   * @param $value
   *   The value to add for the field.
   * @param float|false $boost
   *   FALSE for default boost, or a positive number for setting a field boost.
   */
  public function addField($key, $value, $boost = FALSE) {
    if (!isset($this->fields[$key])) {

      // create holding array if this is the first value
      $this->fields[$key] = array();
    }
    else {
      if (!is_array($this->fields[$key])) {

        // move existing value into array if it is not already an array
        $this->fields[$key] = array(
          $this->fields[$key],
        );
      }
    }
    if ($this
      ->getFieldBoost($key) === FALSE) {

      // boost not already set, set it now
      $this
        ->setFieldBoost($key, $boost);
    }
    else {
      if ((double) $boost > 0.0) {

        // multiply passed boost with current field boost - similar to SolrJ implementation
        $this->fieldBoosts[$key] *= (double) $boost;
      }
    }

    // add value to array
    $this->fields[$key][] = $value;
  }

  /**
   * Gets information about a field stored in Solr.
   *
   * @param string $key
   *   The name of the field.
   *
   * @return array|false
   *   An associative array of info if the field exists, FALSE otherwise.
   */
  public function getField($key) {
    if (isset($this->fields[$key])) {
      return array(
        'name' => $key,
        'value' => $this->fields[$key],
        'boost' => $this
          ->getFieldBoost($key),
      );
    }
    return FALSE;
  }

  /**
   * Sets a field value.
   *
   * Multi-valued fields should be set as arrays or via the addField()
   * function which will automatically make sure the field is an array.
   *
   * @param string $key
   *   The name of the field.
   * @param string|array $value
   *   The value to set for the field.
   * @param float|false $boost
   *   FALSE for default boost, or a positive number for setting a field boost.
   */
  public function setField($key, $value, $boost = FALSE) {
    $this->fields[$key] = $value;
    $this
      ->setFieldBoost($key, $boost);
  }

  /**
   * Gets the currently set field boost for a document field.
   *
   * @param string $key
   *   The name of the field.
   *
   * @return float|false
   *   The currently set field boost, or FALSE if none was set.
   */
  public function getFieldBoost($key) {
    return isset($this->fieldBoosts[$key]) ? $this->fieldBoosts[$key] : FALSE;
  }

  /**
   * Sets the field boost for a document field.
   *
   * @param string $key
   *   The name of the field.
   * @param float|false $boost
   *   FALSE for default boost, or a positive number for setting a field boost.
   */
  public function setFieldBoost($key, $boost) {
    $boost = (double) $boost;
    if ($boost > 0.0) {
      $this->fieldBoosts[$key] = $boost;
    }
    else {
      $this->fieldBoosts[$key] = FALSE;
    }
  }

  /**
   * Returns all current field boosts, indexed by field name.
   *
   * @return array
   *   An associative array in the format $field_name => $field_boost.
   */
  public function getFieldBoosts() {
    return $this->fieldBoosts;
  }

  /**
   * Gets the currently set field's 'update' attribute for a document field.
   *
   * @param string $key
   *   The name of the field.
   *
   * @return string|false
   *   The currently set field's update attribute, or FALSE if none was set.
   */
  public function getFieldUpdate($key) {
    return isset($this->fieldUpdates[$key]) ? $this->fieldUpdates[$key] : FALSE;
  }

  /**
   * Sets the field's 'update' attribute for a document field.
   *
   * @param string $key
   *   The name of the field.
   * @param string|false $update
   *   One of the allowed update values ('add', 'set', 'inc').
   */
  public function setFieldUpdate($key, $update) {
    $this->fieldUpdates[$key] = $update;
  }

  /**
   * Retrieves all currently set field updates.
   *
   * @return string[]
   *   Associative array of field's "update" attributes that were set, keyed by
   *   field name.
   */
  public function getFieldUpdates() {
    return $this->fieldUpdates;
  }

  /**
   * Gets the names of all fields in this document.
   *
   * @return array
   *   The names of all fields in this document.
   */
  public function getFieldNames() {
    return array_keys($this->fields);
  }

  /**
   * Gets the values of all fields in this document.
   *
   * @return array
   *   The values of all fields in this document.
   */
  public function getFieldValues() {
    return array_values($this->fields);
  }

  /**
   * Retrieves the nested documents set on this document.
   *
   * @return \SearchApiSolrDocument[]
   *   The nested documents.
   */
  public function getNestedObjects() {
    return $this->nestedObjects;
  }

  /**
   * Sets an array of nested documents.
   *
   * Populate nested documents for use with block join queries. Note that this
   * will lead to errors when used with Solr versions older than 4.5.
   *
   * @param SearchApiSolrDocument[] $nested_documents
   *   An array of SearchApiSolrDocument objects.
   */
  public function setNestedDocuments(array $nested_documents) {
    $this->nestedObjects = $nested_documents;
  }

  /**
   * Implements IteratorAggregate::getIterator().
   *
   * Implementing the IteratorAggregate interface allows the following usage:
   * @code
   *   foreach ($document as $key => $value) {
   *     // ...
   *   }
   * @endcode
   *
   * @return Traversable
   *   An iterator over this document's fields.
   */
  public function getIterator() {
    $arrayObject = new ArrayObject($this->fields);
    return $arrayObject
      ->getIterator();
  }

  /**
   * Magic getter for field values.
   *
   * @param string $key
   *   The name of the field.
   *
   * @return string|array|null
   *   The value that was set for the field.
   */
  public function __get($key) {
    return $this->fields[$key];
  }

  /**
   * Magic setter for field values.
   *
   * Multi-valued fields should be set as arrays or via the addField() function
   * which will automatically make sure the field is an array.
   *
   * @param string $key
   *   The name of the field.
   * @param string|array $value
   *   The value to set for the field.
   */
  public function __set($key, $value) {
    $this
      ->setField($key, $value);
  }

  /**
   * Magic isset for fields values.
   *
   * Do not call directly. Allows the following usage:
   * @code
   *   isset($document->some_field);
   * @endcode
   *
   * @param string $key
   *   The name of the field.
   *
   * @return bool
   *   Whether the given key is set in this document.
   */
  public function __isset($key) {
    return isset($this->fields[$key]);
  }

  /**
   * Magic unset for field values.
   *
   * Do not call directly. Allows the following usage:
   * @code
   *   unset($document->some_field);
   * @endcode
   *
   * @param string $key
   *   The name of the field.
   */
  public function __unset($key) {
    unset($this->fields[$key]);
    unset($this->fieldBoosts[$key]);
  }

  /**
   * Create an XML fragment from this document.
   *
   * This string can then be used inside a Solr add call.
   *
   * @return string
   *   An XML formatted string for this document.
   */
  public function toXml() {
    $xml = '<doc';
    if ($this->documentBoost !== FALSE) {
      $xml .= ' boost="' . $this->documentBoost . '"';
    }
    $xml .= '>';
    foreach ($this->fields as $key => $values) {
      $fieldBoost = $this
        ->getFieldBoost($key);
      $fieldUpdate = $this
        ->getFieldUpdate($key);
      $key = htmlspecialchars($key, ENT_COMPAT, 'UTF-8');
      if (!is_array($values)) {
        $values = array(
          $values,
        );
      }
      foreach ($values as $value) {
        $xml .= '<field name="' . $key . '"';
        if ($fieldBoost !== FALSE) {
          $xml .= ' boost="' . $fieldBoost . '"';

          // Only set the boost for the first field in the set.
          $fieldBoost = FALSE;
        }
        if ($fieldUpdate !== FALSE) {
          $xml .= ' update="' . $fieldUpdate . '"';
        }
        $xml .= '>' . htmlspecialchars($value, ENT_NOQUOTES, 'UTF-8') . '</field>';
      }
    }

    // If nested objects have been added, include them in the XML to be indexed.
    foreach ($this->nestedObjects as $object) {

      // Skip any documents that aren't of the correct type.
      if (!$object instanceof SearchApiSolrDocument) {
        $vars['@type'] = is_object($object) ? get_class($object) : gettype($object);
        watchdog('search_api_solr', 'Attempt to add an invalid nested Solr document of type @type.', $vars, WATCHDOG_ERROR);
        continue;
      }

      // Generate the markup for each nested document.
      $xml .= $object
        ->toXml();
    }
    $xml .= '</doc>';

    // Remove any control characters to avoid Solr XML parser exception.
    return self::stripCtrlChars($xml);
  }

  /**
   * Sanitizes XML for sending to Solr.
   *
   * Replaces control (non-printable) characters that are invalid to Solr's XML
   * parser with a space.
   *
   * @param string $string
   *   The string to sanitize.
   *
   * @return string
   *   A string safe for including in a Solr request.
   */
  public static function stripCtrlChars($string) {

    // See:  http://w3.org/International/questions/qa-forms-utf-8.html
    // Printable utf-8 does not include any of these chars below x7F
    return preg_replace('@[\\x00-\\x08\\x0B\\x0C\\x0E-\\x1F]@', ' ', $string);
  }

}

Members

Name	Modifiers	Type	Description
SearchApiSolrDocument::$documentBoost	protected	property	Document boost value.
SearchApiSolrDocument::$fieldBoosts	protected	property	Document field boost values, indexed by name.
SearchApiSolrDocument::$fields	protected	property	Document field values, indexed by name.
SearchApiSolrDocument::$fieldUpdates	protected	property	Document field update values, indexed by name.
SearchApiSolrDocument::$nestedObjects	protected	property	Document nested objects.
SearchApiSolrDocument::addField	public	function	Adds a value to a multi-valued field
SearchApiSolrDocument::clear	public	function	Clears all boosts and fields from this document.
SearchApiSolrDocument::getBoost	public	function	Gets the current document boost.
SearchApiSolrDocument::getField	public	function	Gets information about a field stored in Solr.
SearchApiSolrDocument::getFieldBoost	public	function	Gets the currently set field boost for a document field.
SearchApiSolrDocument::getFieldBoosts	public	function	Returns all current field boosts, indexed by field name.
SearchApiSolrDocument::getFieldNames	public	function	Gets the names of all fields in this document.
SearchApiSolrDocument::getFieldUpdate	public	function	Gets the currently set field's 'update' attribute for a document field.
SearchApiSolrDocument::getFieldUpdates	public	function	Retrieves all currently set field updates.
SearchApiSolrDocument::getFieldValues	public	function	Gets the values of all fields in this document.
SearchApiSolrDocument::getIterator	public	function	Implements IteratorAggregate::getIterator().
SearchApiSolrDocument::getNestedObjects	public	function	Retrieves the nested documents set on this document.
SearchApiSolrDocument::setBoost	public	function	Sets the document boost factor.
SearchApiSolrDocument::setField	public	function	Sets a field value.
SearchApiSolrDocument::setFieldBoost	public	function	Sets the field boost for a document field.
SearchApiSolrDocument::setFieldUpdate	public	function	Sets the field's 'update' attribute for a document field.
SearchApiSolrDocument::setNestedDocuments	public	function	Sets an array of nested documents.
SearchApiSolrDocument::stripCtrlChars	public static	function	Sanitizes XML for sending to Solr.
SearchApiSolrDocument::toXml	public	function	Create an XML fragment from this document.
SearchApiSolrDocument::__get	public	function	Magic getter for field values.
SearchApiSolrDocument::__isset	public	function	Magic isset for fields values.
SearchApiSolrDocument::__set	public	function	Magic setter for field values.
SearchApiSolrDocument::__unset	public	function	Magic unset for field values.

You are here

class SearchApiSolrDocument in Search API Solr 7

Hierarchy

File

Members

API Navigation