Source for file Document.php

Documentation is available at Document.php

  1. <?php
  2. /**
  3.  * Copyright (c) 2007-2009, Conduit Internet Technologies, 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 Conduit Internet Technologies, 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-2009 Conduit Internet Technologies, Inc. (http://conduit-it.com)
  31.  * @license New BSD (http://solr-php-client.googlecode.com/svn/trunk/COPYING)
  32.  *
  33.  * @package Apache
  34.  * @subpackage Solr
  35.  * @author Donovan Jimenez <djimenez@conduit-it.com>
  36.  */
  37.  
  38. /**
  39.  * Holds Key / Value pairs that represent a Solr Document along with any associated boost
  40.  * values. Field values can be accessed by direct dereferencing such as:
  41.  * <code>
  42.  * ...
  43.  * $document->title = 'Something';
  44.  * echo $document->title;
  45.  * ...
  46.  * </code>
  47.  *
  48.  * Additionally, the field values can be iterated with foreach
  49.  *
  50.  * <code>
  51.  * foreach ($document as $fieldName => $fieldValue)
  52.  * {
  53.  * ...
  54.  * }
  55.  * </code>
  56.  */
  57. class Apache_Solr_Document implements IteratorAggregate
  58. {
  59.     /**
  60.      * Document boost value
  61.      *
  62.      * @var float 
  63.      */
  64.     protected $_documentBoost = false;
  65.  
  66.     /**
  67.      * Document field values, indexed by name
  68.      *
  69.      * @var array 
  70.      */
  71.     protected $_fields = array();
  72.  
  73.     /**
  74.      * Document field boost values, indexed by name
  75.      *
  76.      * @var array array of floats
  77.      */
  78.     protected $_fieldBoosts = array();
  79.  
  80.     /**
  81.      * Clear all boosts and fields from this document
  82.      */
  83.     public function clear()
  84.     {
  85.         $this->_documentBoost = false;
  86.  
  87.         $this->_fields = array();
  88.         $this->_fieldBoosts = array();
  89.     }
  90.  
  91.     /**
  92.      * Get current document boost
  93.      *
  94.      * @return mixed will be false for default, or else a float
  95.      */
  96.     public function getBoost()
  97.     {
  98.         return $this->_documentBoost;
  99.     }
  100.  
  101.     /**
  102.      * Set document boost factor
  103.      *
  104.      * @param mixed $boost Use false for default boost, else cast to float that should be > 0 or will be treated as false
  105.      */
  106.     public function setBoost($boost)
  107.     {
  108.         $boost = (float) $boost;
  109.  
  110.         if ($boost 0.0)
  111.         {
  112.             $this->_documentBoost = $boost;
  113.         }
  114.         else
  115.         {
  116.             $this->_documentBoost = false;
  117.         }
  118.     }
  119.  
  120.     /**
  121.      * Add a value to a multi-valued field
  122.      *
  123.      * NOTE: the solr XML format allows you to specify boosts
  124.      * PER value even though the underlying Lucene implementation
  125.      * only allows a boost per field. To remedy this, the final
  126.      * field boost value will be the product of all specified boosts
  127.      * on field values - this is similar to SolrJ's functionality.
  128.      *
  129.      * <code>
  130.      * $doc = new Apache_Solr_Document();
  131.      *
  132.      * $doc->addField('foo', 'bar', 2.0);
  133.      * $doc->addField('foo', 'baz', 3.0);
  134.      *
  135.      * // resultant field boost will be 6!
  136.      * echo $doc->getFieldBoost('foo');
  137.      * </code>
  138.      *
  139.      * @param string $key 
  140.      * @param mixed $value 
  141.      * @param mixed $boost Use false for default boost, else cast to float that should be > 0 or will be treated as false
  142.      */
  143.     public function addField($key$value$boost false)
  144.     {
  145.         if (!isset($this->_fields[$key]))
  146.         {
  147.             // create holding array if this is the first value
  148.             $this->_fields[$keyarray();
  149.         }
  150.         else if (!is_array($this->_fields[$key]))
  151.         {
  152.             // move existing value into array if it is not already an array
  153.             $this->_fields[$keyarray($this->_fields[$key]);
  154.         }
  155.  
  156.         if ($this->getFieldBoost($key=== false)
  157.         {
  158.             // boost not already set, set it now
  159.             $this->setFieldBoost($key$boost);
  160.         }
  161.         else if ((float) $boost 0.0)
  162.         {
  163.             // multiply passed boost with current field boost - similar to SolrJ implementation
  164.             $this->_fieldBoosts[$key*= (float) $boost;
  165.         }
  166.  
  167.         // add value to array
  168.         $this->_fields[$key][$value;
  169.     }
  170.  
  171.     /**
  172.      * Handle the array manipulation for a multi-valued field
  173.      *
  174.      * @param string $key 
  175.      * @param string $value 
  176.      * @param mixed $boost Use false for default boost, else cast to float that should be > 0 or will be treated as false
  177.      *
  178.      * @deprecated Use addField(...) instead
  179.      */
  180.     public function setMultiValue($key$value$boost false)
  181.     {
  182.         $this->addField($key$value$boost);
  183.     }
  184.  
  185.     /**
  186.      * Get field information
  187.      *
  188.      * @param string $key 
  189.      * @return mixed associative array of info if field exists, false otherwise
  190.      */
  191.     public function getField($key)
  192.     {
  193.         if (isset($this->_fields[$key]))
  194.         {
  195.             return array(
  196.                 'name' => $key,
  197.                 'value' => $this->_fields[$key],
  198.                 'boost' => $this->getFieldBoost($key)
  199.             );
  200.         }
  201.  
  202.         return false;
  203.     }
  204.  
  205.     /**
  206.      * Set a field value. Multi-valued fields should be set as arrays
  207.      * or instead use the addField(...) function which will automatically
  208.      * make sure the field is an array.
  209.      *
  210.      * @param string $key 
  211.      * @param mixed $value 
  212.      * @param mixed $boost Use false for default boost, else cast to float that should be > 0 or will be treated as false
  213.      */
  214.     public function setField($key$value$boost false)
  215.     {
  216.         $this->_fields[$key$value;
  217.         $this->setFieldBoost($key$boost);
  218.     }
  219.  
  220.     /**
  221.      * Get the currently set field boost for a document field
  222.      *
  223.      * @param string $key 
  224.      * @return float currently set field boost, false if one is not set
  225.      */
  226.     public function getFieldBoost($key)
  227.     {
  228.         return isset($this->_fieldBoosts[$key]$this->_fieldBoosts[$keyfalse;
  229.     }
  230.  
  231.     /**
  232.      * Set the field boost for a document field
  233.      *
  234.      * @param string $key field name for the boost
  235.      * @param mixed $boost Use false for default boost, else cast to float that should be > 0 or will be treated as false
  236.      */
  237.     public function setFieldBoost($key$boost)
  238.     {
  239.         $boost = (float) $boost;
  240.  
  241.         if ($boost 0.0)
  242.         {
  243.             $this->_fieldBoosts[$key$boost;
  244.         }
  245.         else
  246.         {
  247.             $this->_fieldBoosts[$keyfalse;
  248.         }
  249.     }
  250.  
  251.     /**
  252.      * Return current field boosts, indexed by field name
  253.      *
  254.      * @return array 
  255.      */
  256.     public function getFieldBoosts()
  257.     {
  258.         return $this->_fieldBoosts;
  259.     }
  260.  
  261.     /**
  262.      * Get the names of all fields in this document
  263.      *
  264.      * @return array 
  265.      */
  266.     public function getFieldNames()
  267.     {
  268.         return array_keys($this->_fields);
  269.     }
  270.  
  271.     /**
  272.      * Get the values of all fields in this document
  273.      *
  274.      * @return array 
  275.      */
  276.     public function getFieldValues()
  277.     {
  278.         return array_values($this->_fields);
  279.     }
  280.  
  281.     /**
  282.      * IteratorAggregate implementation function. Allows usage:
  283.      *
  284.      * <code>
  285.      * foreach ($document as $key => $value)
  286.      * {
  287.      *     ...
  288.      * }
  289.      * </code>
  290.      */
  291.     public function getIterator()
  292.     {
  293.         $arrayObject new ArrayObject($this->_fields);
  294.  
  295.         return $arrayObject->getIterator();
  296.     }
  297.  
  298.     /**
  299.      * Magic get for field values
  300.      *
  301.      * @param string $key 
  302.      * @return mixed 
  303.      */
  304.     public function __get($key)
  305.     {
  306.         return $this->_fields[$key];
  307.     }
  308.  
  309.     /**
  310.      * Magic set for field values. Multi-valued fields should be set as arrays
  311.      * or instead use the addField(...) function which will automatically
  312.      * make sure the field is an array.
  313.      *
  314.      * @param string $key 
  315.      * @param mixed $value 
  316.      */
  317.     public function __set($key$value)
  318.     {
  319.         $this->setField($key$value);
  320.     }
  321.  
  322.     /**
  323.      * Magic isset for fields values.  Do not call directly. Allows usage:
  324.      *
  325.      * <code>
  326.      * isset($document->some_field);
  327.      * </code>
  328.      *
  329.      * @param string $key 
  330.      * @return boolean 
  331.      */
  332.     public function __isset($key)
  333.     {
  334.         return isset($this->_fields[$key]);
  335.     }
  336.  
  337.     /**
  338.      * Magic unset for field values. Do not call directly. Allows usage:
  339.      *
  340.      * <code>
  341.      * unset($document->some_field);
  342.      * </code>
  343.      *
  344.      * @param string $key 
  345.      */
  346.     public function __unset($key)
  347.     {
  348.         unset($this->_fields[$key]);
  349.         unset($this->_fieldBoosts[$key]);
  350.     }
  351. }

Documentation generated on Wed, 11 Mar 2009 17:34:14 -0400 by phpDocumentor 1.4.2