CRM/Utils/String.php

   1 <?php
   2 /*
   3  +--------------------------------------------------------------------+
   4  | CiviCRM version 4.4                                                |
   5  +--------------------------------------------------------------------+
   6  | Copyright CiviCRM LLC (c) 2004-2013                                |
   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  *
  30  * @package CRM
  31  * @copyright CiviCRM LLC (c) 2004-2013
  32  * $Id$
  33  *
  34  */
  35
  36 require_once 'HTML/QuickForm/Rule/Email.php';
  37
  38 /**
  39  * This class contains string functions
  40  *
  41  */
  42 class CRM_Utils_String {
  43   CONST COMMA = ",", SEMICOLON = ";", SPACE = " ", TAB = "\t", LINEFEED = "\n", CARRIAGELINE = "\r\n", LINECARRIAGE = "\n\r", CARRIAGERETURN = "\r";
  44
  45   /**
  46    * List of all letters and numbers
  47    */
  48   const ALPHANUMERIC = 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890';
  49
  50   /**
  51    * Convert a display name into a potential variable
  52    * name that we could use in forms/code
  53    *
  54    * @param  name    Name of the string
  55    *
  56    * @return string  An equivalent variable name
  57    *
  58    * @access public
  59    *
  60    * @return string (or null)
  61    * @static
  62    */
  63   static function titleToVar($title, $maxLength = 31) {
  64     $variable = self::munge($title, '_', $maxLength);
  65
  66     if (CRM_Utils_Rule::title($variable, $maxLength)) {
  67       return $variable;
  68     }
  69
  70     // if longer than the maxLength lets just return a substr of the
  71     // md5 to prevent errors downstream
  72     return substr(md5($title), 0, $maxLength);
  73   }
  74
  75   /**
  76    * given a string, replace all non alpha numeric characters and
  77    * spaces with the replacement character
  78    *
  79    * @param string $name the name to be worked on
  80    * @param string $char the character to use for non-valid chars
  81    * @param int    $len  length of valid variables
  82    *
  83    * @access public
  84    *
  85    * @return string returns the manipulated string
  86    * @static
  87    */
  88   static function munge($name, $char = '_', $len = 63) {
  89     // replace all white space and non-alpha numeric with $char
  90     // we only use the ascii character set since mysql does not create table names / field names otherwise
  91     // CRM-11744
  92     $name = preg_replace('/[^a-zA-Z0-9]+/', $char, trim($name));
  93
  94     if ($len) {
  95       // lets keep variable names short
  96       return substr($name, 0, $len);
  97     }
  98     else {
  99       return $name;
 100     }
 101   }
 102
 103   /**
 104    *
 105    * Takes a variable name and munges it randomly into another variable name
 106    *
 107    * @param  string $name    Initial Variable Name
 108    * @param int     $len  length of valid variables
 109    *
 110    * @return string  Randomized Variable Name
 111    * @access public
 112    * @static
 113    */
 114   static function rename($name, $len = 4) {
 115     $rand = substr(uniqid(), 0, $len);
 116     return substr_replace($name, $rand, -$len, $len);
 117   }
 118
 119   /**
 120    * takes a string and returns the last tuple of the string.
 121    * useful while converting file names to class names etc
 122    *
 123    * @param string $string the input string
 124    * @param char   $char   the character used to demarcate the componets
 125    *
 126    * @access public
 127    *
 128    * @return string the last component
 129    * @static
 130    */
 131   static function getClassName($string, $char = '_') {
 132     $names = array();
 133     if (!is_array($string)) {
 134       $names = explode($char, $string);
 135     }
 136     if (!empty($names)) {
 137       return array_pop($names);
 138     }
 139   }
 140
 141   /**
 142    * appends a name to a string and seperated by delimiter.
 143    * does the right thing for an empty string
 144    *
 145    * @param string $str   the string to be appended to
 146    * @param string $delim the delimiter to use
 147    * @param mixed  $name  the string (or array of strings) to append
 148    *
 149    * @return void
 150    * @access public
 151    * @static
 152    */
 153   static function append(&$str, $delim, $name) {
 154     if (empty($name)) {
 155       return;
 156     }
 157
 158     if (is_array($name)) {
 159       foreach ($name as $n) {
 160         if (empty($n)) {
 161           continue;
 162         }
 163         if (empty($str)) {
 164           $str = $n;
 165         }
 166         else {
 167           $str .= $delim . $n;
 168         }
 169       }
 170     }
 171     else {
 172       if (empty($str)) {
 173         $str = $name;
 174       }
 175       else {
 176         $str .= $delim . $name;
 177       }
 178     }
 179   }
 180
 181   /**
 182    * determine if the string is composed only of ascii characters
 183    *
 184    * @param string  $str input string
 185    * @param boolean $utf8 attempt utf8 match on failure (default yes)
 186    *
 187    * @return boolean    true if string is ascii
 188    * @access public
 189    * @static
 190    */
 191   static function isAscii($str, $utf8 = TRUE) {
 192     if (!function_exists('mb_detect_encoding')) {
 193       // eliminate all white space from the string
 194       $str = preg_replace('/\s+/', '', $str);
 195       // FIXME:  This is a pretty brutal hack to make utf8 and 8859-1 work.
 196
 197       /* match low- or high-ascii characters */
 198       if (preg_match('/[\x00-\x20]|[\x7F-\xFF]/', $str)) {
 199         // || // low ascii characters
 200         // high ascii characters
 201         //  preg_match( '/[\x7F-\xFF]/', $str ) ) {
 202         if ($utf8) {
 203           /* if we did match, try for utf-8, or iso8859-1 */
 204
 205           return self::isUtf8($str);
 206         }
 207         else {
 208           return FALSE;
 209         }
 210       }
 211       return TRUE;
 212     }
 213     else {
 214       $order = array('ASCII');
 215       if ($utf8) {
 216         $order[] = 'UTF-8';
 217       }
 218       $enc = mb_detect_encoding($str, $order, TRUE);
 219       return ($enc == 'ASCII' || $enc == 'UTF-8');
 220     }
 221   }
 222
 223   /**
 224    * determine the string replacements for redaction
 225    * on the basis of the regular expressions
 226    *
 227    * @param string $str        input string
 228    * @param array  $regexRules regular expression to be matched w/ replacements
 229    *
 230    * @return array $match      array of strings w/ corresponding redacted outputs
 231    * @access public
 232    * @static
 233    */
 234   static function regex($str, $regexRules) {
 235     //redact the regular expressions
 236     if (!empty($regexRules) && isset($str)) {
 237       static $matches, $totalMatches, $match = array();
 238       foreach ($regexRules as $pattern => $replacement) {
 239         preg_match_all($pattern, $str, $matches);
 240         if (!empty($matches[0])) {
 241           if (empty($totalMatches)) {
 242             $totalMatches = $matches[0];
 243           }
 244           else {
 245             $totalMatches = array_merge($totalMatches, $matches[0]);
 246           }
 247           $match = array_flip($totalMatches);
 248         }
 249       }
 250     }
 251
 252     if (!empty($match)) {
 253       foreach ($match as $matchKey => & $dontCare) {
 254         foreach ($regexRules as $pattern => $replacement) {
 255           if (preg_match($pattern, $matchKey)) {
 256             $dontCare = $replacement . substr(md5($matchKey), 0, 5);
 257             break;
 258           }
 259         }
 260       }
 261       return $match;
 262     }
 263     return CRM_Core_DAO::$_nullArray;
 264   }
 265
 266   static function redaction($str, $stringRules) {
 267     //redact the strings
 268     if (!empty($stringRules)) {
 269       foreach ($stringRules as $match => $replace) {
 270         $str = str_ireplace($match, $replace, $str);
 271       }
 272     }
 273
 274     //return the redacted output
 275     return $str;
 276   }
 277
 278   /**
 279    * Determine if a string is composed only of utf8 characters
 280    *
 281    * @param string $str  input string
 282    * @access public
 283    * @static
 284    *
 285    * @return boolean
 286    */
 287   static function isUtf8($str) {
 288     if (!function_exists(mb_detect_encoding)) {
 289       // eliminate all white space from the string
 290       $str = preg_replace('/\s+/', '', $str);
 291
 292       /* pattern stolen from the php.net function documentation for
 293              * utf8decode();
 294              * comment by JF Sebastian, 30-Mar-2005
 295              */
 296
 297       return preg_match('/^([\x00-\x7f]|[\xc2-\xdf][\x80-\xbf]|\xe0[\xa0-\xbf][\x80-\xbf]|[\xe1-\xec][\x80-\xbf]{2}|\xed[\x80-\x9f][\x80-\xbf]|[\xee-\xef][\x80-\xbf]{2}|f0[\x90-\xbf][\x80-\xbf]{2}|[\xf1-\xf3][\x80-\xbf]{3}|\xf4[\x80-\x8f][\x80-\xbf]{2})*$/', $str);
 298       // ||
 299       // iconv('ISO-8859-1', 'UTF-8', $str);
 300     }
 301     else {
 302       $enc = mb_detect_encoding($str, array('UTF-8'), TRUE);
 303       return ($enc !== FALSE);
 304     }
 305   }
 306
 307   /**
 308    * determine if two href's are equivalent (fuzzy match)
 309    *
 310    * @param string $url1 the first url to be matched
 311    * @param string $url2 the second url to be matched against
 312    *
 313    * @return boolean true if the urls match, else false
 314    * @access public
 315    * @static
 316    */
 317   static function match($url1, $url2) {
 318     $url1 = strtolower($url1);
 319     $url2 = strtolower($url2);
 320
 321     $url1Str = parse_url($url1);
 322     $url2Str = parse_url($url2);
 323
 324     if ($url1Str['path'] == $url2Str['path'] &&
 325       self::extractURLVarValue(CRM_Utils_Array::value('query', $url1Str)) == self::extractURLVarValue(CRM_Utils_Array::value('query', $url2Str))
 326     ) {
 327       return TRUE;
 328     }
 329     return FALSE;
 330   }
 331
 332   /**
 333    * Function to extract variable values
 334    *
 335    * @param  mix $query this is basically url
 336    *
 337    * @return mix $v  returns civicrm url (eg: civicrm/contact/search/...)
 338    * @access public
 339    * @static
 340    */
 341   static function extractURLVarValue($query) {
 342     $config = CRM_Core_Config::singleton();
 343     $urlVar = $config->userFrameworkURLVar;
 344
 345     $params = explode('&', $query);
 346     foreach ($params as $p) {
 347       if (strpos($p, '=')) {
 348         list($k, $v) = explode('=', $p);
 349         if ($k == $urlVar) {
 350           return $v;
 351         }
 352       }
 353     }
 354     return NULL;
 355   }
 356
 357   /**
 358    * translate a true/false/yes/no string to a 0 or 1 value
 359    *
 360    * @param string $str  the string to be translated
 361    *
 362    * @return boolean
 363    * @access public
 364    * @static
 365    */
 366   static function strtobool($str) {
 367     if (!is_scalar($str)) {
 368       return FALSE;
 369     }
 370
 371     if (preg_match('/^(y(es)?|t(rue)?|1)$/i', $str)) {
 372       return TRUE;
 373     }
 374     return FALSE;
 375   }
 376
 377   /**
 378    * returns string '1' for a true/yes/1 string, and '0' for no/false/0 else returns false
 379    *
 380    * @param string $str  the string to be translated
 381    *
 382    * @return boolean
 383    * @access public
 384    * @static
 385    */
 386   static function strtoboolstr($str) {
 387     if (!is_scalar($str)) {
 388       return FALSE;
 389     }
 390
 391     if (preg_match('/^(y(es)?|t(rue)?|1)$/i', $str)) {
 392       return '1';
 393     }
 394     elseif (preg_match('/^(n(o)?|f(alse)?|0)$/i', $str)) {
 395       return '0';
 396     }
 397     else {
 398       return FALSE;
 399     }
 400   }
 401
 402   /**
 403    * Convert a HTML string into a text one using html2text
 404    *
 405    * @param string $html  the string to be converted
 406    *
 407    * @return string       the converted string
 408    * @access public
 409    * @static
 410    */
 411   static function htmlToText($html) {
 412     require_once 'packages/html2text/rcube_html2text.php';
 413     $token_html = preg_replace('!\{([a-z_.]+)\}!i', 'token:{$1}', $html);
 414     $converter = new rcube_html2text($token_html);
 415     $token_text = $converter->get_text();
 416     $text = preg_replace('!token\:\{([a-z_.]+)\}!i', '{$1}', $token_text);
 417     return $text;
 418   }
 419
 420   static function extractName($string, &$params) {
 421     $name = trim($string);
 422     if (empty($name)) {
 423       return;
 424     }
 425
 426     // strip out quotes
 427     $name = str_replace('"', '', $name);
 428     $name = str_replace('\'', '', $name);
 429
 430     // check for comma in name
 431     if (strpos($name, ',') !== FALSE) {
 432
 433       // name has a comma - assume lname, fname [mname]
 434       $names = explode(',', $name);
 435       if (count($names) > 1) {
 436         $params['last_name'] = trim($names[0]);
 437
 438         // check for space delim
 439         $fnames = explode(' ', trim($names[1]));
 440         if (count($fnames) > 1) {
 441           $params['first_name'] = trim($fnames[0]);
 442           $params['middle_name'] = trim($fnames[1]);
 443         }
 444         else {
 445           $params['first_name'] = trim($fnames[0]);
 446         }
 447       }
 448       else {
 449         $params['first_name'] = trim($names[0]);
 450       }
 451     }
 452     else {
 453       // name has no comma - assume fname [mname] fname
 454       $names = explode(' ', $name);
 455       if (count($names) == 1) {
 456         $params['first_name'] = $names[0];
 457       }
 458       elseif (count($names) == 2) {
 459         $params['first_name'] = $names[0];
 460         $params['last_name'] = $names[1];
 461       }
 462       else {
 463         $params['first_name'] = $names[0];
 464         $params['middle_name'] = $names[1];
 465         $params['last_name'] = $names[2];
 466       }
 467     }
 468   }
 469
 470   static function &makeArray($string) {
 471     $string = trim($string);
 472
 473     $values = explode("\n", $string);
 474     $result = array();
 475     foreach ($values as $value) {
 476       list($n, $v) = CRM_Utils_System::explode('=', $value, 2);
 477       if (!empty($v)) {
 478         $result[trim($n)] = trim($v);
 479       }
 480     }
 481     return $result;
 482   }
 483
 484   /**
 485    * Function to add include files needed for jquery
 486    *
 487    * This appears to be used in cases where the normal html-header
 488    * provided by CRM_Core_Resources can't be used (e.g. when outputting in
 489    * "print" mode, the execution will short-circuit without allowing the
 490    * CMS to output JS/CSS tags).
 491    */
 492   static function addJqueryFiles(&$html) {
 493     CRM_Core_Resources::singleton()->addCoreResources('html-header');
 494     return CRM_Core_Region::instance('html-header')->render('', FALSE) . $html;
 495   }
 496
 497   /**
 498    * Given an ezComponents-parsed representation of
 499    * a text with alternatives return only the first one
 500    *
 501    * @param string $full  all alternatives as a long string (or some other text)
 502    *
 503    * @return string       only the first alternative found (or the text without alternatives)
 504    */
 505   static function stripAlternatives($full) {
 506     $matches = array();
 507     preg_match('/-ALTERNATIVE ITEM 0-(.*?)-ALTERNATIVE ITEM 1-.*-ALTERNATIVE END-/s', $full, $matches);
 508
 509     if (isset($matches[1]) &&
 510       trim(strip_tags($matches[1])) != ''
 511     ) {
 512       return $matches[1];
 513     }
 514     else {
 515       return $full;
 516     }
 517   }
 518
 519   /**
 520    * strip leading, trailing, double spaces from string
 521    * used for postal/greeting/addressee
 522    *
 523    * @param string  $string input string to be cleaned
 524    *
 525    * @return string the cleaned string
 526    * @access public
 527    * @static
 528    */
 529   static function stripSpaces($string) {
 530     return (empty($string)) ? $string : preg_replace("/\s{2,}/", " ", trim($string));
 531   }
 532
 533   /**
 534    * This function is used to clean the URL 'path' variable that we use
 535    * to construct CiviCRM urls by removing characters from the path variable
 536    *
 537    * @param string $string  the input string to be sanitized
 538    * @param array  $search  the characters to be sanitized
 539    * @param string $replace the character to replace it with
 540    *
 541    * @return string the sanitized string
 542    * @access public
 543    * @static
 544    */
 545   static function stripPathChars($string,
 546     $search = NULL,
 547     $replace = NULL
 548   ) {
 549     static $_searchChars = NULL;
 550     static $_replaceChar = NULL;
 551
 552     if (empty($string)) {
 553       return $string;
 554     }
 555
 556     if ($_searchChars == NULL) {
 557       $_searchChars = array(
 558         '&', ';', ',', '=', '$',
 559         '"', "'", '\\',
 560         '<', '>', '(', ')',
 561         ' ', "\r", "\r\n", "\n", "\t",
 562       );
 563       $_replaceChar = '_';
 564     }
 565
 566
 567     if ($search == NULL) {
 568       $search = $_searchChars;
 569     }
 570
 571     if ($replace == NULL) {
 572       $replace = $_replaceChar;
 573     }
 574
 575     return str_replace($search, $replace, $string);
 576   }
 577
 578
 579   /**
 580    * Use HTMLPurifier to clean up a text string and remove any potential
 581    * xss attacks. This is primarily used in public facing pages which
 582    * accept html as the input string
 583    *
 584    * @param string $string the input string
 585    *
 586    * @return string the cleaned up string
 587    * @public
 588    * @static
 589    */
 590   static function purifyHTML($string) {
 591     static $_filter = null;
 592     if (!$_filter) {
 593       $config = HTMLPurifier_Config::createDefault();
 594       $config->set('Core.Encoding', 'UTF-8');
 595
 596       // Disable the cache entirely
 597       $config->set('Cache.DefinitionImpl', null);
 598
 599       $_filter = new HTMLPurifier($config);
 600     }
 601
 602     return $_filter->purify($string);
 603   }
 604
 605   /**
 606    * Truncate $string; if $string exceeds $maxLen, place "..." at the end
 607    *
 608    * @param string $string
 609    * @param int $maxLen
 610    */
 611   static function ellipsify($string, $maxLen) {
 612     $len = strlen($string);
 613     if ($len <= $maxLen) {
 614       return $string;
 615     }
 616     else {
 617       return substr($string, 0, $maxLen-3) . '...';
 618     }
 619   }
 620
 621   /**
 622    * Generate a random string
 623    *
 624    * @param $len
 625    * @param $alphabet
 626    * @return string
 627    */
 628   public static function createRandom($len, $alphabet) {
 629     $alphabetSize = strlen($alphabet);
 630     $result = '';
 631     for ($i = 0; $i < $len; $i++) {
 632       $result .= $alphabet{rand(1, $alphabetSize) - 1};
 633     }
 634     return $result;
 635   }
 636
 637   /**
 638    * Examples:
 639    * "admin foo" => array(NULL,"admin foo")
 640    * "cms:admin foo" => array("cms", "admin foo")
 641    *
 642    * @param string $string e.g. "view all contacts". Syntax: "[prefix:]name"
 643    * @return array (0 => string|NULL $prefix, 1 => string $value)
 644    */
 645   public static function parsePrefix($delim, $string, $defaultPrefix = NULL) {
 646     $pos = strpos($string, $delim);
 647     if ($pos === FALSE) {
 648       return array($defaultPrefix, $string);
 649     }
 650     else {
 651       return array(substr($string, 0, $pos), substr($string, 1+$pos));
 652     }
 653   }
 654
 655   /**
 656    * Many parts of the codebase have a convention of internally passing around
 657    * HTML-encoded URLs. This effectively means that "&" is replaced by "&amp;"
 658    * (because most other odd characters are %-escaped in URLs; and %-escaped
 659    * strings don't need any extra escaping in HTML).
 660    *
 661    * @param string $url URL with HTML entities
 662    * @return string URL without HTML entities
 663    */
 664   public static function unstupifyUrl($htmlUrl) {
 665     return str_replace('&amp;', '&', $htmlUrl);
 666   }
 667 }
 668