Source for file search-defs.php

Documentation is available at search-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-defs.php */
  22. /* Author: Paul Waite */
  23. /* Description: Definitions for handling searches for objects in a */
  24. /* generic way. This class contains functionality which */
  25. /* handles search parameters, and hits etc. but has no */
  26. /* search-engine-specific code to actually do the search. */
  27. /* */
  28. /* As such, the 'search' class is therefore a virtual */
  29. /* class which is intended to be inherited by a more */
  30. /* specific class to implement particular modes of */
  31. /* searching. */
  32. /* */
  33. /* ******************************************************************** */
  34. /** @package search *//**
  35. * The search hit class
  36. * Something to contain a search hit which is defined as an array
  37. * of information. The format of this array is entirely up to the
  38. * search being performed, and is not enforced here.
  39. * @package search
  40. */
  41. class hit {
  42. /** Array of fieldname/value pairs - info returned by the search */
  43.  
  44. var $fields;
  45. // .....................................................................
  46. /**
  47. * Constructor
  48. * Create a new search hit.
  49. * @param array $fields Assoc. array (fieldname/value) of fields returned
  50. */
  51. function hit($fields=false) {
  52. // The fields are an optional array of fields which were returned
  53. // by a search. If not passed, then we assign an empty array..
  54. if (!is_array($fields)) $this->fields = array();
  55. else $this->fields = $fields;
  56. }
  57. } // hit class
  58. //-----------------------------------------------------------------------
  59.  
  60. /**
  61. * The search term class
  62. * Something to contain a search term. A search term is
  63. * basically a string of one or more words to match, together
  64. * with the operator to apply with the match.
  65. * @package search
  66. */
  67. class term {
  68. /** The text of this search term */
  69.  
  70. var $text;
  71. /** Join operator, one of: 'AND', 'OR', 'NOT', 'AND NOT' */
  72.  
  73. var $operator;
  74. /** ID field provided for optional application use */
  75.  
  76. var $id;
  77. /** True if this term is deemed valid */
  78.  
  79. var $valid;
  80. // .....................................................................
  81. /**
  82. * Constructor
  83. * Create a new search term.
  84. * @param string $text Search term text.
  85. * @param integer $op Search operator 'and', 'or', 'and not'.
  86. * @param string $id A unique ID to associate with this search term
  87. */
  88. function term($text="", $op="", $id="") {
  89. $this->valid = false;
  90. $this->id = $id;
  91. $this->text = trim($text);
  92. $op = trim($op);
  93. if ($op == ""
  94. || !strcasecmp($op, "OR")
  95. || !strcasecmp($op, "AND")
  96. || !strcasecmp($op, "NOT")
  97. || !strcasecmp($op, "AND NOT")) {
  98. $this->operator = $op;
  99. $this->valid = true;
  100. }
  101. debugbr("term: new search term: '$this->text' '$this->operator' '$this->id'", DBG_DEBUG);
  102. } // term
  103.  
  104. } // term class
  105. //-----------------------------------------------------------------------
  106.  
  107. /**
  108. * The search class is an object which can be assigned search terms, can
  109. * execute a search, and can contain search hits having executed a seach.
  110. * NOTE: This is a virtual class which is expected to be used by a child
  111. * class which implements a particular search mechanism eg: swish++
  112. * or database query searching. As such the execute() method does nothing
  113. * and must be over-ridden in the child classes implementing searching.
  114. * @package search
  115. */
  116. class search {
  117. /** Title for heading of output */
  118.  
  119. var $title = "";
  120. /** Query string container */
  121.  
  122. var $query = "";
  123. /** Array of hits returned. Each element of this array is
  124. normally an array of fields returned by the search. */
  125. var $hit = array();
  126. /** Array of search terms to match */
  127.  
  128. var $searchterm = array();
  129. /** Maximum results to return in query */
  130.  
  131. var $max_results = 25;
  132. /** No. of results to skip in query (for paging) */
  133.  
  134. var $skip_results = 0;
  135. /** Start date range for search (false means undefined). This
  136. variable can be in any application-specific format */
  137. var $date_start = false;
  138. /** End date range for search (false means undefined). This
  139. variable can be in any application-specific format */
  140. var $date_end = false;
  141. /** Name of the field to which daterange should be applied */
  142.  
  143. var $date_fieldname = "";
  144. /** Whether we have run a query */
  145.  
  146. var $executed = false;
  147. // .....................................................................
  148. /**
  149. * Constructor
  150. * Create a new search.
  151. * @param string $title Title/description for this search
  152. */
  153. function search($title="Search Results") {
  154. $this->title = $title;
  155. $this->initialise();
  156. } // search
  157. // .....................................................................
  158. /**
  159. * Set date range
  160. * Set the date range for the search. This is just recording the given
  161. * date information for use by child classes of this one. We do not
  162. * even care what the format of the dates is. They are just stored.
  163. * @param string $start Start date for search
  164. * @param string $end End date for search
  165. */
  166. function set_daterange($start=false, $end=false, $date_fieldname="") {
  167. if ($start != false && $start != "")
  168. $this->date_start = $start;
  169. else $this->date_start = false;
  170. if ($end != false && $end != "")
  171. $this->date_end = $end;
  172. else $this->date_end = false;
  173. $this->date_fieldname = $date_fieldname;
  174. } // set_daterange
  175. // .....................................................................
  176. /**
  177. * Clear the date range for the search. Makes sure that the search
  178. * will not be filtered by a date restriction.
  179. */
  180. function clear_daterange() {
  181. $this->date_start = false;
  182. $this->date_end = false;
  183. $this->date_fieldname = "";
  184. } // clear_daterange
  185. // .............................................................................................
  186. /** Return count of searchterms present in this search.
  187. * @return integer Number of search terms we have currently.
  188. */
  189. function termcount() {
  190. return count($this->searchterm);
  191. } // termcount
  192. // .............................................................................................
  193. /** Return count of hits present in this search.
  194. * @return integer Number of hits we got.
  195. */
  196. function hitcount() {
  197. return count($this->hit);
  198. } // hitcount
  199. // .............................................................................................
  200. /** Return true if at least one of our dates is set.
  201. * @return boolean True if a date range is in effect.
  202. */
  203. function has_daterange() {
  204. return ($this->date_start || $this->date_end);
  205. } // has_daterange
  206. // .....................................................................
  207. /**
  208. * Set maximum results
  209. * Sets the maximum results to return from the search.
  210. * @param integer $max Maximum hits to return
  211. */
  212. function set_maxresults($max=0) {
  213. $this->max_results = $max;
  214. return $this;
  215. } // set_maxresults
  216. // .....................................................................
  217. /**
  218. * Set skip results
  219. * Sets the number of results to skip in the query. Eg. If
  220. * this is set to 15, then the first 15 results of the
  221. * query will be skipped before returning results. This can
  222. * be used as a method of paging a query which returns a
  223. * large number of results..
  224. * @param integer $skip Number of initial hits to skip
  225. */
  226. function set_skipresults($skip=0) {
  227. $this->skip_results = $skip;
  228. return $this;
  229. } // set_skipresults
  230. // .....................................................................
  231. /**
  232. * Add a new search term to match. Search terms can be a single word or
  233. * compound patterns, Each time one of these is added, it has an operator
  234. * associated with it - whether this term is a "may have" (OR), or a
  235. * "must have" (AND) term.
  236. * Visualize these terms as self-contained statements, with brackets
  237. * around each end, and which are joined to others by the given
  238. * operator to make the whole query.
  239. * @param string $term Search term text to match.
  240. * @param integer $op Joining operator: 'AND', 'OR', 'NOT, 'AND NOT'.
  241. * @param string $id An optional ID to associate with this search term.
  242. */
  243. function match($term="", $op="OR", $id="") {
  244. debug_trace($this);
  245. $this->searchterm[] = new term($term, $op, $id);
  246. $this->reset_search();
  247. debug_trace();
  248. } // match
  249. // .....................................................................
  250. /**
  251. * Define a search term which the search must match to succeed.
  252. * @param string $term Search term text to match.
  253. * @param string $id An optional ID to associate with this search term.
  254. */
  255. function must_match($term, $id="") {
  256. $this->match($term, "AND", $id);
  257. } // must_match
  258. // .....................................................................
  259. /**
  260. * Define a search term which the search may or may not match.
  261. * @param string $term Search term text to match.
  262. * @param string $id An optional ID to associate with this search term.
  263. */
  264. function may_match($term, $id="") {
  265. $this->match($term, "OR", $id);
  266. } // may_match
  267. // .....................................................................
  268. /**
  269. * Define a search term which the search must not match to succeed.
  270. * @param string $term Search term text to match.
  271. * @param string $id An optional ID to associate with this search term.
  272. */
  273. function does_not_match($term, $id="") {
  274. $this->match($term, "NOT", $id);
  275. } // does_not_match
  276. // .....................................................................
  277. /**
  278. * Execute search
  279. * This is the key functionality of a real search class
  280. * which is derived from this virtual class.
  281. * @access private
  282. */
  283. function execute() { }
  284. // .....................................................................
  285. /**
  286. * Query valid status
  287. * Simple assumption: the query string must contain
  288. * something to be valid. Feel free to override this!
  289. * @access private
  290. */
  291. function queryvalid() {
  292. if ($this->query == "") {
  293. $this->buildquery();
  294. }
  295. return ($this->query != "");
  296. } // queryvalid
  297. // .....................................................................
  298. /**
  299. * Build query syntax
  300. * Construct the query string. This is a generic simple method which
  301. * might have to be overridden in the child classes which implement
  302. * specific search mechanisms, eg. swish++ searching.
  303. * @access private
  304. */
  305. function buildquery() {
  306. $q = "";
  307. if (isset($this->searchterm)) {
  308. foreach ($this->searchterm as $term) {
  309. if ($term->valid && $term->text != "") {
  310. // Prefix the join operator..
  311. if ($q == "") {
  312. // Initial phrase, can only be 'not'..
  313. if (!strcasecmp($term->operator, "AND NOT")
  314. || !strcasecmp($term->operator, "NOT")) {
  315. $q .= "NOT ";
  316. }
  317. }
  318. else {
  319. // Just prefix the operator on..
  320. $q .= "$term->operator ";
  321. }
  322. $q .= "$term->text ";
  323. }
  324. }
  325. }
  326. $this->query = trim($q);
  327. } // buildquery
  328. // .....................................................................
  329. /**
  330. * Initialise everything about the search.
  331. * Initialise to a state which is the same as when the object is
  332. * instantiated.
  333. */
  334. function initialise() {
  335. $this->clear_search();
  336. $this->reset_search();
  337. } // initialise
  338. // .....................................................................
  339. /**
  340. * Clear the search terms and any stored hits.
  341. */
  342. function clear_search() {
  343. if ($this->termcount() > 0) {
  344. $this->searchterm = array();
  345. }
  346. if ($this->hitcount() > 0) {
  347. $this->hit = array();
  348. }
  349. } // clear_search
  350. // .....................................................................
  351. /**
  352. * Reset search to null query and not executed status.
  353. */
  354. function reset_search() {
  355. $this->query = "";
  356. $this->executed = false;
  357. } // reset_search
  358.  
  359. } // search class
  360. // ----------------------------------------------------------------------
  361.  
  362. ?>

Documentation generated by phpDocumentor 1.3.0RC3