Source for file search-query-defs.php

Documentation is available at search-query-defs.php

  1. <?php
  2. /* ******************************************************************** */
  3. /* CATALYST PHP Source Code */
  4. /* -------------------------------------------------------------------- */
  5. /* This program is free software; you can redistribute it and/or modify */
  6. /* it under the terms of the GNU General Public License as published by */
  7. /* the Free Software Foundation; either version 2 of the License, or */
  8. /* (at your option) any later version. */
  9. /* */
  10. /* This program is distributed in the hope that it will be useful, */
  11. /* but WITHOUT ANY WARRANTY; without even the implied warranty of */
  12. /* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the */
  13. /* GNU General Public License for more details. */
  14. /* */
  15. /* You should have received a copy of the GNU General Public License */
  16. /* along with this program; if not, write to: */
  17. /* The Free Software Foundation, Inc., 59 Temple Place, Suite 330, */
  18. /* Boston, MA 02111-1307 USA */
  19. /* -------------------------------------------------------------------- */
  20. /* */
  21. /* Filename: search-query-defs.php */
  22. /* Author: Paul Waite */
  23. /* Description: Definitions for interfacing to a search engine to */
  24. /* perform search queries. */
  25. /* The parent module which includes this module must also */
  26. /* include the underlying defs module for the search */
  27. /* engine itself, eg: lucene, solr etc. */
  28. /* */
  29. /* ******************************************************************** */
  30. /** @package search */
  31. include_once("search-defs.php");
  32.  
  33. // ----------------------------------------------------------------------
  34. /**
  35. * The SearchEngine search class
  36. * This class inherits the functionality of the generic 'search' class. It
  37. * extends it to implement a SearchEngine search. Use the methods in this class
  38. * as the mainstay in implementing queries of content from SearchEngine. Most
  39. * methods, such as match(), matchfield(), matchrange() etc. store the
  40. * requirement in the class for subsequent building using the set_*()
  41. * methods of the SearchEngine classes to set the relevant fields. This is only
  42. * done when you call execute(), and the query is built from all the
  43. * composite terms you have added via match() et al.
  44. * @package search
  45. */
  46. class searchengine_search extends searchengine_querymsg {
  47. // .....................................................................
  48. /**
  49. * Constructor
  50. * Create a new SearchEngine search
  51. * @param string $application Application name/domain name for searching in
  52. * @param string $host Hostname or IP of SearchEngine server
  53. * @param string $port Port of SearchEngine server
  54. */
  55. function searchengine_search($application="?", $host="", $port="") {
  56. global $RESPONSE;
  57. $this->search();
  58. $this->searchengine_querymsg($application, $host, $port);
  59. $this->initialise();
  60. } // searchengine_search
  61. // .....................................................................
  62. /**
  63. * Add a new search term to match. Search terms can be a single word or
  64. * compound patterns, Each time one of these is added, it has an operator
  65. * associated with it - whether this term is a "may have" (OR), or a
  66. * "must have" (AND) term.
  67. * NB: This method overrides the parent method in order to ensure that all
  68. * boolean logic terms are in upper case as SearchEngine requires.
  69. * @param string $term Search term text to match.
  70. * @param integer $op Joining operator: 'AND', 'OR', 'NOT, 'AND NOT'.
  71. * @param string $id An optional ID to associate with this search term.
  72. * @param numeric $boost Boost factor. Can be a fraction eg. 0.2, or integer 1,2,3..
  73. */
  74. function match($term, $op="OR", $id="", $boost="") {
  75. $LCops = array("/ and /","/ or /","/ not /");
  76. $UCops = array(" AND "," OR "," NOT ");
  77. $term = preg_replace($LCops, $UCops, $term);
  78. if ($boost != "") $term .= "^$boost";
  79. search::match($term, strtoupper($op), $id);
  80. } // match
  81. // .....................................................................
  82. /**
  83. * Add search term to match a field value.
  84. * This is used to add a search term which defines the value that a given
  85. * field may or may not contain for the search to succeed.
  86. * For adding terms which are 'free' (as a user might type into a search
  87. * box for example) then you can use the match() method which this class
  88. * inherits from the search class.
  89. * @param string $fieldname Name of field to reference in the index
  90. * @param mixed $fieldvalue Value or array of values, for field to match
  91. * @param string $op Operator to join this term to others in the query
  92. * @param string $id Optional identity tag for this term
  93. * @param numeric $boost Boost factor. Can be a fraction eg. 0.2, or integer 1,2,3..
  94. */
  95. function matchfield($fieldname, $fieldvalue, $op="OR", $id="", $boost="") {
  96. debug_trace($this);
  97. if (!isset($fieldvalue)) return;
  98. if (!is_array ($fieldvalue)) {
  99. $fieldvalue = array($fieldvalue);
  100. }
  101. $term = "";
  102. foreach ($fieldvalue as $value) {
  103. $value = trim($value);
  104. if ($value != "") {
  105. $term .= " OR " . $this->fieldterm($fieldname, $value);
  106. }
  107. }
  108. if ($term != "") {
  109. $term = substr($term, 4); // Get rid of initial OR
  110. // Call parent function to register the search term..
  111. $this->match($term, strtoupper($op), $id, $boost);
  112. }
  113. debug_trace();
  114. } // matchfield
  115. // .....................................................................
  116. /**
  117. * Helper function to build field search term
  118. * @param string $fieldname Name of field to reference in the index
  119. * @param string $fieldvalue Value of field to match
  120. * @access private
  121. */
  122. function fieldterm($fieldname, $fieldvalue) {
  123. if ($fieldname != DEFAULT_FIELD) {
  124. $term = "$fieldname:$fieldvalue";
  125. }
  126. else {
  127. $term = $fieldvalue;
  128. }
  129. return $term;
  130. } // fieldterm
  131. // .....................................................................
  132. /**
  133. * Add search term to match a field value range.
  134. * This is used to add a search term which defines the range of values that
  135. * a given field may or may not contain for the search to succeed.
  136. * NB: This method is always a must match (implied AND) search term. In
  137. * other words the search is always restricted/refined by it.
  138. * @param string $fromvalue Lower range value of field to match
  139. * @param string $tovalue Upper range value of field to match
  140. * @param string $fieldname Name of field, defaulted to 'Text'
  141. */
  142. function matchrange($fromvalue, $tovalue, $fieldname) {
  143. debug_trace($this);
  144. $this->set_range($fromvalue, $tovalue, $fieldname);
  145. debug_trace();
  146. } // matchrange
  147. // .....................................................................
  148. /**
  149. * Add search term: must match a field value.
  150. * This is used to add a search term which defines the value that a given
  151. * field must contain for the search to succeed.
  152. * @param string $fieldname Name of field
  153. * @param string $fieldvalue Value of field to match
  154. * @param string $id Optional identity tag for this term
  155. * @param numeric $boost Boost factor. Can be a fraction eg. 0.2, or integer 1,2,3..
  156. */
  157. function must_matchfield($fieldname, $fieldvalue, $id="", $boost="") {
  158. $this->matchfield($fieldname, $fieldvalue, "AND", $id, $boost);
  159. } // must_matchfield
  160. // .....................................................................
  161. /**
  162. * Add search term: may match a field value.
  163. * This is used to add a search term which defines the value that a given
  164. * field may contain for the search to succeed.
  165. * @param string $fieldname Name of field
  166. * @param string $fieldvalue Value of field to match
  167. * @param string $id Optional identity tag for this term
  168. * @param numeric $boost Boost factor. Can be a fraction eg. 0.2, or integer 1,2,3..
  169. */
  170. function may_matchfield($fieldname, $fieldvalue, $id="", $boost="") {
  171. $this->matchfield($fieldname, $fieldvalue, "OR", $id, $boost);
  172. } // may_matchfield
  173. // .....................................................................
  174. /**
  175. * Add search term: must not match a field value.
  176. * This is used to add a search term which defines the value that a given
  177. * field must not contain for the search to succeed.
  178. * @param string $fieldname Name of field
  179. * @param string $fieldvalue Value of field to match
  180. * @param string $id Optional identity tag for this term
  181. * @param numeric $boost Boost factor. Can be a fraction eg. 0.2, or integer 1,2,3..
  182. */
  183. function does_not_matchfield($fieldname, $fieldvalue, $id="", $boost="") {
  184. $this->matchfield($fieldname, $fieldvalue, "NOT", $id, $boost);
  185. } // does_not_matchfield
  186. // .....................................................................
  187. /**
  188. * Define the query text directly, without recourse to any of this class's
  189. * high-level query-building methods. This method simply assigns the class
  190. * variable 'query' to what is passed, assuming that this string is a
  191. * ready-built query string that the underlying SearchEngine will be
  192. * able to understand and execute.
  193. * @param string $raw_query_text The ready-built query string to use
  194. */
  195. function rawquery($raw_query_text) {
  196. $this->query = $raw_query_text;
  197. } // rawquery
  198. // .....................................................................
  199. /**
  200. * Execute the search
  201. * Here we execute a SearchEngine search, overriding the method in the parent
  202. * class. This involves building the query string, sending it to the
  203. * SearchEngine server, and receiving the search results back.
  204. * @param integer $timeoutsecs Override for timeout in seconds
  205. */
  206. function execute($timeoutsecs="") {
  207. debug_trace($this);
  208.  
  209. // The queryvalid() method is in the parent class 'search', and
  210. // calls the build() method in the same class. The build() method is
  211. // a raw routine to join together the search terms with ANDs and
  212. // ORs. You may have to override it for SearchEngine. If so, just create
  213. // a new build() method in this class.
  214.  
  215. if ($this->queryvalid()) {
  216.  
  217. // This method must be defined in the underlying SearchEngine. It
  218. // should set up the query as it should be for that interface - eg.
  219. // it might enclose the query text in XML <query> tags.
  220. $this->set_query($this->query);
  221.  
  222. // Set limit, offset..
  223. if ($this->max_results > 0) {
  224. $this->set_limit($this->max_results);
  225. if ($this->skip_results > 0) {
  226. $this->set_first($this->skip_results);
  227. }
  228. }
  229.  
  230. // Set any daterange..
  231. if ($this->has_daterange()) {
  232. $this->set_range($this->date_start, $this->date_end, $this->date_fieldname);
  233. }
  234.  
  235. // Send to SearchEngine..
  236. $this->send($timeoutsecs);
  237.  
  238. // Flag that we did it..
  239. $this->executed = true;
  240. debugbr("SearchEngine search: exec ok: returning " . $this->hitcount() . " hits", DBG_DEBUG);
  241. }
  242. else {
  243. debugbr("SearchEngine search: invalid query: '$this->query'", DBG_DEBUG);
  244. }
  245. debug_trace();
  246. } // execute
  247.  
  248. } // searchengine_search class
  249.  
  250. ?>

Documentation generated by phpDocumentor 1.3.0RC3