Source for file Document.php

Documentation is available at Document.php

  1. <?php
  2. /**
  3.  * Copyright (c) 2007-2011, Servigistics, Inc.
  4.  * All rights reserved.
  5.  *
  6.  * Redistribution and use in source and binary forms, with or without
  7.  * modification, are permitted provided that the following conditions are met:
  8.  *
  9.  *  - Redistributions of source code must retain the above copyright notice,
  10.  *    this list of conditions and the following disclaimer.
  11.  *  - Redistributions in binary form must reproduce the above copyright
  12.  *    notice, this list of conditions and the following disclaimer in the
  13.  *    documentation and/or other materials provided with the distribution.
  14.  *  - Neither the name of Servigistics, Inc. nor the names of
  15.  *    its contributors may be used to endorse or promote products derived from
  16.  *    this software without specific prior written permission.
  17.  *
  18.  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
  19.  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  20.  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  21.  * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
  22.  * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  23.  * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  24.  * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  25.  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  26.  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  27.  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  28.  * POSSIBILITY OF SUCH DAMAGE.
  29.  *
  30.  * @copyright Copyright 2007-2011 Servigistics, Inc. (http://servigistics.com)
  31.  * @license http://solr-php-client.googlecode.com/svn/trunk/COPYING New BSD
  32.  * @version $Id: Document.php 54 2011-02-04 16:29:18Z donovan.jimenez $
  33.  *
  34.  * @package Apache
  35.  * @subpackage Solr
  36.  * @author Donovan Jimenez <djimenez@conduit-it.com>
  37.  */
  38.  
  39. /**
  40.  * Holds Key / Value pairs that represent a Solr Document along with any associated boost
  41.  * values. Field values can be accessed by direct dereferencing such as:
  42.  * <code>
  43.  * ...
  44.  * $document->title = 'Something';
  45.  * echo $document->title;
  46.  * ...
  47.  * </code>
  48.  *
  49.  * Additionally, the field values can be iterated with foreach
  50.  *
  51.  * <code>
  52.  * foreach ($document as $fieldName => $fieldValue)
  53.  * {
  54.  * ...
  55.  * }
  56.  * </code>
  57.  */
  58. class Apache_Solr_Document implements IteratorAggregate
  59. {
  60.     /**
  61.      * SVN Revision meta data for this class
  62.      */
  63.     const SVN_REVISION = '$Revision: 54 $';
  64.  
  65.     /**
  66.      * SVN ID meta data for this class
  67.      */
  68.     const SVN_ID = '$Id: Document.php 54 2011-02-04 16:29:18Z donovan.jimenez $';
  69.  
  70.     /**
  71.      * Document boost value
  72.      *
  73.      * @var float 
  74.      */
  75.     protected $_documentBoost = false;
  76.  
  77.     /**
  78.      * Document field values, indexed by name
  79.      *
  80.      * @var array 
  81.      */
  82.     protected $_fields = array();
  83.  
  84.     /**
  85.      * Document field boost values, indexed by name
  86.      *
  87.      * @var array array of floats
  88.      */
  89.     protected $_fieldBoosts = array();
  90.  
  91.     /**
  92.      * Clear all boosts and fields from this document
  93.      */
  94.     public function clear()
  95.     {
  96.         $this->_documentBoost = false;
  97.  
  98.         $this->_fields = array();
  99.         $this->_fieldBoosts = array();
  100.     }
  101.  
  102.     /**
  103.      * Get current document boost
  104.      *
  105.      * @return mixed will be false for default, or else a float
  106.      */
  107.     public function getBoost()
  108.     {
  109.         return $this->_documentBoost;
  110.     }
  111.  
  112.     /**
  113.      * Set document boost factor
  114.      *
  115.      * @param mixed $boost Use false for default boost, else cast to float that should be > 0 or will be treated as false
  116.      */
  117.     public function setBoost($boost)
  118.     {
  119.         $boost = (float) $boost;
  120.  
  121.         if ($boost > 0.0)
  122.         {
  123.             $this->_documentBoost = $boost;
  124.         }
  125.         else
  126.         {
  127.             $this->_documentBoost = false;
  128.         }
  129.     }
  130.  
  131.     /**
  132.      * Add a value to a multi-valued field
  133.      *
  134.      * NOTE: the solr XML format allows you to specify boosts
  135.      * PER value even though the underlying Lucene implementation
  136.      * only allows a boost per field. To remedy this, the final
  137.      * field boost value will be the product of all specified boosts
  138.      * on field values - this is similar to SolrJ's functionality.
  139.      *
  140.      * <code>
  141.      * $doc = new Apache_Solr_Document();
  142.      *
  143.      * $doc->addField('foo', 'bar', 2.0);
  144.      * $doc->addField('foo', 'baz', 3.0);
  145.      *
  146.      * // resultant field boost will be 6!
  147.      * echo $doc->getFieldBoost('foo');
  148.      * </code>
  149.      *
  150.      * @param string $key 
  151.      * @param mixed $value 
  152.      * @param mixed $boost Use false for default boost, else cast to float that should be > 0 or will be treated as false
  153.      */
  154.     public function addField($key, $value, $boost = false)
  155.     {
  156.         if (!isset($this->_fields[$key]))
  157.         {
  158.             // create holding array if this is the first value
  159.             $this->_fields[$key] = array();
  160.         }
  161.         else if (!is_array($this->_fields[$key]))
  162.         {
  163.             // move existing value into array if it is not already an array
  164.             $this->_fields[$key] = array($this->_fields[$key]);
  165.         }
  166.  
  167.         if ($this->getFieldBoost($key) === false)
  168.         {
  169.             // boost not already set, set it now
  170.             $this->setFieldBoost($key, $boost);
  171.         }
  172.         else if ((float) $boost > 0.0)
  173.         {
  174.             // multiply passed boost with current field boost - similar to SolrJ implementation
  175.             $this->_fieldBoosts[$key] *= (float) $boost;
  176.         }
  177.  
  178.         // add value to array
  179.         $this->_fields[$key][] = $value;
  180.     }
  181.  
  182.     /**
  183.      * Handle the array manipulation for a multi-valued field
  184.      *
  185.      * @param string $key 
  186.      * @param string $value 
  187.      * @param mixed $boost Use false for default boost, else cast to float that should be > 0 or will be treated as false
  188.      *
  189.      * @deprecated Use addField(...) instead
  190.      */
  191.     public function setMultiValue($key, $value, $boost = false)
  192.     {
  193.         $this->addField($key, $value, $boost);
  194.     }
  195.  
  196.     /**
  197.      * Get field information
  198.      *
  199.      * @param string $key 
  200.      * @return mixed associative array of info if field exists, false otherwise
  201.      */
  202.     public function getField($key)
  203.     {
  204.         if (isset($this->_fields[$key]))
  205.         {
  206.             return array(
  207.                 'name' => $key,
  208.                 'value' => $this->_fields[$key],
  209.                 'boost' => $this->getFieldBoost($key)
  210.             );
  211.         }
  212.  
  213.         return false;
  214.     }
  215.  
  216.     /**
  217.      * Set a field value. Multi-valued fields should be set as arrays
  218.      * or instead use the addField(...) function which will automatically
  219.      * make sure the field is an array.
  220.      *
  221.      * @param string $key 
  222.      * @param mixed $value 
  223.      * @param mixed $boost Use false for default boost, else cast to float that should be > 0 or will be treated as false
  224.      */
  225.     public function setField($key, $value, $boost = false)
  226.     {
  227.         $this->_fields[$key] = $value;
  228.         $this->setFieldBoost($key, $boost);
  229.     }
  230.  
  231.     /**
  232.      * Get the currently set field boost for a document field
  233.      *
  234.      * @param string $key 
  235.      * @return float currently set field boost, false if one is not set
  236.      */
  237.     public function getFieldBoost($key)
  238.     {
  239.         return isset($this->_fieldBoosts[$key]) ? $this->_fieldBoosts[$key] : false;
  240.     }
  241.  
  242.     /**
  243.      * Set the field boost for a document field
  244.      *
  245.      * @param string $key field name for the boost
  246.      * @param mixed $boost Use false for default boost, else cast to float that should be > 0 or will be treated as false
  247.      */
  248.     public function setFieldBoost($key, $boost)
  249.     {
  250.         $boost = (float) $boost;
  251.  
  252.         if ($boost > 0.0)
  253.         {
  254.             $this->_fieldBoosts[$key] = $boost;
  255.         }
  256.         else
  257.         {
  258.             $this->_fieldBoosts[$key] = false;
  259.         }
  260.     }
  261.  
  262.     /**
  263.      * Return current field boosts, indexed by field name
  264.      *
  265.      * @return array 
  266.      */
  267.     public function getFieldBoosts()
  268.     {
  269.         return $this->_fieldBoosts;
  270.     }
  271.  
  272.     /**
  273.      * Get the names of all fields in this document
  274.      *
  275.      * @return array 
  276.      */
  277.     public function getFieldNames()
  278.     {
  279.         return array_keys($this->_fields);
  280.     }
  281.  
  282.     /**
  283.      * Get the values of all fields in this document
  284.      *
  285.      * @return array 
  286.      */
  287.     public function getFieldValues()
  288.     {
  289.         return array_values($this->_fields);
  290.     }
  291.  
  292.     /**
  293.      * IteratorAggregate implementation function. Allows usage:
  294.      *
  295.      * <code>
  296.      * foreach ($document as $key => $value)
  297.      * {
  298.      *     ...
  299.      * }
  300.      * </code>
  301.      */
  302.     public function getIterator()
  303.     {
  304.         $arrayObject = new ArrayObject($this->_fields);
  305.  
  306.         return $arrayObject->getIterator();
  307.     }
  308.  
  309.     /**
  310.      * Magic get for field values
  311.      *
  312.      * @param string $key 
  313.      * @return mixed 
  314.      */
  315.     public function __get($key)
  316.     {
  317.         if (isset($this->_fields[$key]))
  318.         {
  319.             return $this->_fields[$key];
  320.         }
  321.         
  322.         return null;
  323.     }
  324.  
  325.     /**
  326.      * Magic set for field values. Multi-valued fields should be set as arrays
  327.      * or instead use the addField(...) function which will automatically
  328.      * make sure the field is an array.
  329.      *
  330.      * @param string $key 
  331.      * @param mixed $value 
  332.      */
  333.     public function __set($key, $value)
  334.     {
  335.         $this->setField($key, $value);
  336.     }
  337.  
  338.     /**
  339.      * Magic isset for fields values.  Do not call directly. Allows usage:
  340.      *
  341.      * <code>
  342.      * isset($document->some_field);
  343.      * </code>
  344.      *
  345.      * @param string $key 
  346.      * @return boolean 
  347.      */
  348.     public function __isset($key)
  349.     {
  350.         return isset($this->_fields[$key]);
  351.     }
  352.  
  353.     /**
  354.      * Magic unset for field values. Do not call directly. Allows usage:
  355.      *
  356.      * <code>
  357.      * unset($document->some_field);
  358.      * </code>
  359.      *
  360.      * @param string $key 
  361.      */
  362.     public function __unset($key)
  363.     {
  364.         unset($this->_fields[$key]);
  365.         unset($this->_fieldBoosts[$key]);
  366.     }
  367. }

Documentation generated on Wed, 04 May 2011 11:01:13 -0400 by phpDocumentor 1.4.3