CRM/Utils/QueryFormatter.php

   1 <?php
   2 /*
   3  +--------------------------------------------------------------------+
   4  | CiviCRM version 4.6                                                |
   5  +--------------------------------------------------------------------+
   6  | Copyright CiviCRM LLC (c) 2004-2014                                |
   7  +--------------------------------------------------------------------+
   8  | This file is a part of CiviCRM.                                    |
   9  |                                                                    |
  10  | CiviCRM is free software; you can copy, modify, and distribute it  |
  11  | under the terms of the GNU Affero General Public License           |
  12  | Version 3, 19 November 2007 and the CiviCRM Licensing Exception.   |
  13  |                                                                    |
  14  | CiviCRM is distributed in the hope that it will be useful, but     |
  15  | WITHOUT ANY WARRANTY; without even the implied warranty of         |
  16  | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.               |
  17  | See the GNU Affero General Public License for more details.        |
  18  |                                                                    |
  19  | You should have received a copy of the GNU Affero General Public   |
  20  | License and the CiviCRM Licensing Exception along                  |
  21  | with this program; if not, contact CiviCRM LLC                     |
  22  | at info[AT]civicrm[DOT]org. If you have questions about the        |
  23  | GNU Affero General Public License or the licensing of CiviCRM,     |
  24  | see the CiviCRM license FAQ at http://civicrm.org/licensing        |
  25  +--------------------------------------------------------------------+
  26 */
  27
  28 /**
  29  * Class CRM_Utils_QueryFormatter
  30  *
  31  * This class is a bad idea. It exists for the unholy reason that a single installation
  32  * may have up to three query engines (MySQL LIKE, MySQL FTS, Solr) processing the same
  33  * query-text. It labors* to take the user's search expression and provide similar search
  34  * semantics in different contexts. It is unknown whether this labor will be fruitful
  35  * or in vain.
  36  */
  37 class CRM_Utils_QueryFormatter {
  38   const LANG_SQL_LIKE = 'like';
  39   const LANG_SQL_FTS = 'fts';
  40   const LANG_SQL_FTSBOOL = 'ftsbool';
  41   const LANG_SOLR = 'solr';
  42
  43   /**
  44    * Attempt to leave the text as-is.
  45    */
  46   const MODE_NONE = 'simple';
  47
  48   /**
  49    * Attempt to treat the input text as a phrase
  50    */
  51   const MODE_PHRASE = 'phrase';
  52
  53   /**
  54    * Attempt to treat the input text as a phrase with
  55    * wildcards on each end.
  56    */
  57   const MODE_WILDPHRASE = 'wildphrase';
  58
  59   /**
  60    * Attempt to treat individual word as if it
  61    * had wildcards at the start and end.
  62    */
  63   const MODE_WILDWORDS = 'wildwords';
  64
  65   /**
  66    * Attempt to treat individual word as if it
  67    * had a wildcard at the end.
  68    */
  69   const MODE_WILDWORDS_SUFFIX = 'wildwords-suffix';
  70
  71   static protected $singleton;
  72
  73   /**
  74    * @param bool $fresh
  75    * @return CRM_Utils_QueryFormatter
  76    */
  77   public static function singleton($fresh = FALSE) {
  78     if ($fresh || self::$singleton === NULL) {
  79       $mode = CRM_Core_BAO_Setting::getItem(CRM_Core_BAO_Setting::SEARCH_PREFERENCES_NAME, 'fts_query_mode', NULL, self::MODE_NONE);
  80       self::$singleton = new CRM_Utils_QueryFormatter($mode);
  81     }
  82     return self::$singleton;
  83   }
  84
  85   /**
  86    * @var string eg MODE_NONE
  87    */
  88   protected $mode;
  89
  90   /**
  91    * @param string $mode
  92    *   Eg MODE_NONE.
  93    */
  94   public function __construct($mode) {
  95     $this->mode = $mode;
  96   }
  97
  98   /**
  99    * @param mixed $mode
 100    */
 101   public function setMode($mode) {
 102     $this->mode = $mode;
 103   }
 104
 105   /**
 106    * @return mixed
 107    */
 108   public function getMode() {
 109     return $this->mode;
 110   }
 111
 112   /**
 113    * @param string $text
 114    * @param string $language
 115    *   Eg LANG_SQL_LIKE, LANG_SQL_FTS, LANG_SOLR.
 116    * @throws CRM_Core_Exception
 117    * @return string
 118    */
 119   public function format($text, $language) {
 120     $text = trim($text);
 121
 122     switch ($language) {
 123       case self::LANG_SOLR:
 124       case self::LANG_SQL_FTS:
 125         $text = $this->_formatFts($text, $this->mode);
 126         break;
 127
 128       case self::LANG_SQL_FTSBOOL:
 129         $text = $this->_formatFtsBool($text, $this->mode);
 130         break;
 131
 132       case self::LANG_SQL_LIKE:
 133         $text = $this->_formatLike($text, $this->mode);
 134         break;
 135
 136       default:
 137         $text = NULL;
 138     }
 139
 140     if ($text === NULL) {
 141       throw new CRM_Core_Exception("Unrecognized combination: language=[{$language}] mode=[{$this->mode}]");
 142     }
 143
 144     return $text;
 145   }
 146
 147   protected function _formatFts($text, $mode) {
 148     $result = NULL;
 149
 150     // normalize user-inputted wildcards
 151     $text = str_replace('%', '*', $text);
 152
 153     if (empty($text)) {
 154       $result = '*';
 155     }
 156     elseif (strpos($text, '*') !== FALSE) {
 157       // if user supplies their own wildcards, then don't do any sophisticated changes
 158       $result = $text;
 159     }
 160     else {
 161       switch ($mode) {
 162         case self::MODE_NONE:
 163           $result = $text;
 164           break;
 165
 166         case self::MODE_PHRASE:
 167           $result = '"' . $text . '"';
 168           break;
 169
 170         case self::MODE_WILDPHRASE:
 171           $result = '"*' . $text . '*"';
 172           break;
 173
 174         case self::MODE_WILDWORDS:
 175           $result = $this->mapWords($text, '*word*');
 176           break;
 177
 178         case self::MODE_WILDWORDS_SUFFIX:
 179           $result = $this->mapWords($text, 'word*');
 180           break;
 181
 182         default:
 183           $result = NULL;
 184       }
 185     }
 186
 187     return $this->dedupeWildcards($result, '%');
 188   }
 189
 190   protected function _formatFtsBool($text, $mode) {
 191     $result = NULL;
 192
 193     // normalize user-inputted wildcards
 194     $text = str_replace('%', '*', $text);
 195
 196     if (empty($text)) {
 197       $result = '*';
 198     }
 199     elseif (strpos($text, '+') !== FALSE || strpos($text, '-') !== FALSE) {
 200       // if user supplies their own include/exclude operators, use text as is (with trailing wildcard)
 201       $result = $this->mapWords($text, 'word*');
 202     }
 203     elseif (strpos($text, '*') !== FALSE) {
 204       // if user supplies their own wildcards, then don't do any sophisticated changes
 205       $result = $this->mapWords($text, '+word');
 206     }
 207     elseif (preg_match('/^(["\']).*\1$/m', $text)) {
 208       // if surrounded by quotes, use term as is
 209       $result = $text;
 210     }
 211     else {
 212       switch ($mode) {
 213         case self::MODE_NONE:
 214           $result = $this->mapWords($text, '+word');
 215           break;
 216
 217         case self::MODE_PHRASE:
 218           $result = '+"' . $text . '"';
 219           break;
 220
 221         case self::MODE_WILDPHRASE:
 222           $result = '+"*' . $text . '*"';
 223           break;
 224
 225         case self::MODE_WILDWORDS:
 226           $result = $this->mapWords($text, '+*word*');
 227           break;
 228
 229         case self::MODE_WILDWORDS_SUFFIX:
 230           $result = $this->mapWords($text, '+word*');
 231           break;
 232
 233         default:
 234           $result = NULL;
 235       }
 236     }
 237
 238     return $this->dedupeWildcards($result, '%');
 239   }
 240
 241   protected function _formatLike($text, $mode) {
 242     $result = NULL;
 243
 244     if (empty($text)) {
 245       $result = '%';
 246     }
 247     elseif (strpos($text, '%') !== FALSE) {
 248       // if user supplies their own wildcards, then don't do any sophisticated changes
 249       $result = $text;
 250     }
 251     else {
 252       switch ($mode) {
 253         case self::MODE_NONE:
 254         case self::MODE_PHRASE:
 255         case self::MODE_WILDPHRASE:
 256           $result = "%" . $text . "%";
 257           break;
 258
 259         case self::MODE_WILDWORDS:
 260         case self::MODE_WILDWORDS_SUFFIX:
 261           $result = "%" . preg_replace('/[ \r\n]+/', '%', $text) . '%';
 262           break;
 263
 264         default:
 265           $result = NULL;
 266       }
 267     }
 268
 269     return $this->dedupeWildcards($result, '%');
 270   }
 271
 272   /**
 273    * @param string $text
 274    *   User-supplied query string.
 275    * @param string $template
 276    *   A prototypical description of each word, eg "word%" or "word*" or "*word*".
 277    * @return string
 278    */
 279   protected function mapWords($text, $template) {
 280     $result = array();
 281     foreach ($this->parseWords($text) as $word) {
 282       $result[] = str_replace('word', $word, $template);
 283     }
 284     return implode(' ', $result);
 285   }
 286
 287   /**
 288    * @param $text
 289    * @return array
 290    */
 291   protected function parseWords($text) {
 292     return explode(' ', preg_replace('/[ \r\n\t]+/', ' ', trim($text)));
 293   }
 294
 295   /**
 296    * @param $text
 297    * @param $wildcard
 298    * @return mixed
 299    */
 300   protected function dedupeWildcards($text, $wildcard) {
 301     if ($text === NULL) {
 302       return NULL;
 303     }
 304
 305     // don't use preg_replace because $wildcard might be special char
 306     while (strpos($text, "{$wildcard}{$wildcard}") !== FALSE) {
 307       $text = str_replace("{$wildcard}{$wildcard}", "{$wildcard}", $text);
 308     }
 309     return $text;
 310   }
 311
 312   public static function getModes() {
 313     return array(
 314       self::MODE_NONE,
 315       self::MODE_PHRASE,
 316       self::MODE_WILDPHRASE,
 317       self::MODE_WILDWORDS,
 318       self::MODE_WILDWORDS_SUFFIX,
 319     );
 320   }
 321
 322   public static function getLanguages() {
 323     return array(
 324       self::LANG_SOLR,
 325       self::LANG_SQL_FTS,
 326       self::LANG_SQL_FTSBOOL,
 327       self::LANG_SQL_LIKE,
 328     );
 329   }
 330
 331   /**
 332    * @param $text
 333    *
 334    * Ex: drush eval 'civicrm_initialize(); CRM_Utils_QueryFormatter::dumpExampleTable("firstword secondword");'
 335    */
 336   public static function dumpExampleTable($text) {
 337     $width = strlen($text) + 8;
 338     $buf = '';
 339
 340     $buf .= sprintf("%-{$width}s", 'mode');
 341     foreach (self::getLanguages() as $lang) {
 342       $buf .= sprintf("%-{$width}s", $lang);
 343     }
 344     $buf .= "\n";
 345
 346     foreach (self::getModes() as $mode) {
 347       $formatter = new CRM_Utils_QueryFormatter($mode);
 348       $buf .= sprintf("%-{$width}s", $mode);
 349       foreach (self::getLanguages() as $lang) {
 350         $buf .= sprintf("%-{$width}s", $formatter->format($text, $lang));
 351       }
 352       $buf .= "\n";
 353     }
 354
 355     echo $buf;
 356   }
 357
 358 }