CRM/Utils/String.php

   1 <?php
   2 /*
   3  +--------------------------------------------------------------------+
   4  | Copyright CiviCRM LLC. All rights reserved.                        |
   5  |                                                                    |
   6  | This work is published under the GNU AGPLv3 license with some      |
   7  | permitted exceptions and without any warranty. For full license    |
   8  | and copyright information, see https://civicrm.org/licensing       |
   9  +--------------------------------------------------------------------+
  10  */
  11
  12 /**
  13  *
  14  * @package CRM
  15  * @copyright CiviCRM LLC https://civicrm.org/licensing
  16  */
  17
  18 use function xKerman\Restricted\unserialize;
  19 use xKerman\Restricted\UnserializeFailedException;
  20
  21 require_once 'HTML/QuickForm/Rule/Email.php';
  22
  23 /**
  24  * This class contains string functions.
  25  */
  26 class CRM_Utils_String {
  27   const COMMA = ",", SEMICOLON = ";", SPACE = " ", TAB = "\t", LINEFEED = "\n", CARRIAGELINE = "\r\n", LINECARRIAGE = "\n\r", CARRIAGERETURN = "\r";
  28
  29   /**
  30    * List of all letters and numbers
  31    */
  32   const ALPHANUMERIC = 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890';
  33
  34   /**
  35    * Convert a display name into a potential variable name.
  36    *
  37    * @param string $title title of the string
  38    * @param int $maxLength
  39    *
  40    * @return string
  41    *   An equivalent variable name.
  42    */
  43   public static function titleToVar($title, $maxLength = 31) {
  44     $variable = self::munge($title, '_', $maxLength);
  45
  46     // FIXME: nothing below this line makes sense. The above call to self::munge will always
  47     // return a safe string of the correct length, so why are we now checking if it's a safe
  48     // string of the correct length?
  49     if (CRM_Utils_Rule::title($variable, $maxLength)) {
  50       return $variable;
  51     }
  52
  53     // FIXME: When would this ever be reachable?
  54     return substr(md5($title), 0, $maxLength);
  55   }
  56
  57   /**
  58    * Replace all non alpha numeric characters and spaces with the replacement character.
  59    *
  60    * @param string $name
  61    *   The name to be worked on.
  62    * @param string $char
  63    *   The character to use for non-valid chars.
  64    * @param int $len
  65    *   Length of valid variables.
  66    *
  67    * @return string
  68    *   returns the manipulated string
  69    */
  70   public static function munge($name, $char = '_', $len = 63) {
  71     // Replace all white space and non-alpha numeric with $char
  72     // we only use the ascii character set since mysql does not create table names / field names otherwise
  73     // CRM-11744
  74     $name = preg_replace('/[^a-zA-Z0-9]+/', $char, trim($name));
  75
  76     //If there are no ascii characters present.
  77     if ($name == $char) {
  78       $name = self::createRandom($len, self::ALPHANUMERIC);
  79     }
  80
  81     if ($len) {
  82       // lets keep variable names short
  83       return substr($name, 0, $len);
  84     }
  85     else {
  86       return $name;
  87     }
  88   }
  89
  90   /**
  91    * Convert possibly underscore separated words to camel case.
  92    *
  93    * @param string $str
  94    * @param bool $ucFirst
  95    *   Should the first letter be capitalized like `CamelCase` or lower like `camelCase`
  96    * @return string
  97    */
  98   public static function convertStringToCamel($str, $ucFirst = TRUE) {
  99     $fragments = explode('_', $str);
 100     $camel = implode('', array_map('ucfirst', $fragments));
 101     return $ucFirst ? $camel : lcfirst($camel);
 102   }
 103
 104   /**
 105    * Inverse of above function, converts camelCase to snake_case
 106    *
 107    * @param string $str
 108    * @return string
 109    */
 110   public static function convertStringToSnakeCase(string $str): string {
 111     return strtolower(ltrim(preg_replace('/(?=[A-Z])/', '_$0', $str), '_'));
 112   }
 113
 114   /**
 115    * Takes a variable name and munges it randomly into another variable name.
 116    *
 117    * @param string $name
 118    *   Initial Variable Name.
 119    * @param int $len
 120    *   Length of valid variables.
 121    *
 122    * @return string
 123    *   Randomized Variable Name
 124    */
 125   public static function rename($name, $len = 4) {
 126     $rand = substr(uniqid(), 0, $len);
 127     return substr_replace($name, $rand, -$len, $len);
 128   }
 129
 130   /**
 131    * Takes a string and returns the last tuple of the string.
 132    *
 133    * Useful while converting file names to class names etc
 134    *
 135    * @param string $string
 136    *   The input string.
 137    * @param string $char
 138    *   Character used to demarcate the components
 139    *
 140    * @return string
 141    *   The last component
 142    */
 143   public static function getClassName($string, $char = '_') {
 144     $names = [];
 145     if (!is_array($string)) {
 146       $names = explode($char, $string);
 147     }
 148     if (!empty($names)) {
 149       return array_pop($names);
 150     }
 151   }
 152
 153   /**
 154    * Appends a name to a string and separated by delimiter.
 155    *
 156    * Does the right thing for an empty string
 157    *
 158    * @param string $str
 159    *   The string to be appended to.
 160    * @param string $delim
 161    *   The delimiter to use.
 162    * @param mixed $name
 163    *   The string (or array of strings) to append.
 164    */
 165   public static function append(&$str, $delim, $name) {
 166     if (empty($name)) {
 167       return;
 168     }
 169
 170     if (is_array($name)) {
 171       foreach ($name as $n) {
 172         if (empty($n)) {
 173           continue;
 174         }
 175         if (empty($str)) {
 176           $str = $n;
 177         }
 178         else {
 179           $str .= $delim . $n;
 180         }
 181       }
 182     }
 183     else {
 184       if (empty($str)) {
 185         $str = $name;
 186       }
 187       else {
 188         $str .= $delim . $name;
 189       }
 190     }
 191   }
 192
 193   /**
 194    * Determine if the string is composed only of ascii characters.
 195    *
 196    * @param string $str
 197    *   Input string.
 198    * @param bool $utf8
 199    *   Attempt utf8 match on failure (default yes).
 200    *
 201    * @return bool
 202    *   true if string is ascii
 203    */
 204   public static function isAscii($str, $utf8 = TRUE) {
 205     if (!function_exists('mb_detect_encoding')) {
 206       // eliminate all white space from the string
 207       $str = preg_replace('/\s+/', '', $str);
 208       // FIXME:  This is a pretty brutal hack to make utf8 and 8859-1 work.
 209
 210       // match low- or high-ascii characters
 211       if (preg_match('/[\x00-\x20]|[\x7F-\xFF]/', $str)) {
 212         // || // low ascii characters
 213         // high ascii characters
 214         //  preg_match( '/[\x7F-\xFF]/', $str ) ) {
 215         if ($utf8) {
 216           // if we did match, try for utf-8, or iso8859-1
 217
 218           return self::isUtf8($str);
 219         }
 220         else {
 221           return FALSE;
 222         }
 223       }
 224       return TRUE;
 225     }
 226     else {
 227       $order = ['ASCII'];
 228       if ($utf8) {
 229         $order[] = 'UTF-8';
 230       }
 231       $enc = mb_detect_encoding($str, $order, TRUE);
 232       return ($enc == 'ASCII' || $enc == 'UTF-8');
 233     }
 234   }
 235
 236   /**
 237    * Encode string using URL-safe Base64.
 238    *
 239    * @param string $v
 240    *
 241    * @return string
 242    * @see https://tools.ietf.org/html/rfc4648#section-5
 243    */
 244   public static function base64UrlEncode($v) {
 245     return rtrim(str_replace(['+', '/'], ['-', '_'], base64_encode($v)), '=');
 246   }
 247
 248   /**
 249    * Decode string using URL-safe Base64.
 250    *
 251    * @param string $v
 252    *
 253    * @return false|string
 254    * @see https://tools.ietf.org/html/rfc4648#section-5
 255    */
 256   public static function base64UrlDecode($v) {
 257     // PHP base64_decode() is already forgiving about padding ("=").
 258     return base64_decode(str_replace(['-', '_'], ['+', '/'], $v));
 259   }
 260
 261   /**
 262    * Determine the string replacements for redaction.
 263    * on the basis of the regular expressions
 264    *
 265    * @param string $str
 266    *   Input string.
 267    * @param array $regexRules
 268    *   Regular expression to be matched w/ replacements.
 269    *
 270    * @return array
 271    *   array of strings w/ corresponding redacted outputs
 272    */
 273   public static function regex($str, $regexRules) {
 274     // redact the regular expressions
 275     if (!empty($regexRules) && isset($str)) {
 276       static $matches, $totalMatches, $match = [];
 277       foreach ($regexRules as $pattern => $replacement) {
 278         preg_match_all($pattern, $str, $matches);
 279         if (!empty($matches[0])) {
 280           if (empty($totalMatches)) {
 281             $totalMatches = $matches[0];
 282           }
 283           else {
 284             $totalMatches = array_merge($totalMatches, $matches[0]);
 285           }
 286           $match = array_flip($totalMatches);
 287         }
 288       }
 289     }
 290
 291     if (!empty($match)) {
 292       foreach ($match as $matchKey => & $dontCare) {
 293         foreach ($regexRules as $pattern => $replacement) {
 294           if (preg_match($pattern, $matchKey)) {
 295             $dontCare = $replacement . substr(md5($matchKey), 0, 5);
 296             break;
 297           }
 298         }
 299       }
 300       return $match;
 301     }
 302     return [];
 303   }
 304
 305   /**
 306    * @param $str
 307    * @param $stringRules
 308    *
 309    * @return mixed
 310    */
 311   public static function redaction($str, $stringRules) {
 312     // redact the strings
 313     if (!empty($stringRules)) {
 314       foreach ($stringRules as $match => $replace) {
 315         $str = str_ireplace($match, $replace, $str);
 316       }
 317     }
 318
 319     // return the redacted output
 320     return $str;
 321   }
 322
 323   /**
 324    * Determine if a string is composed only of utf8 characters
 325    *
 326    * @param string $str
 327    *   Input string.
 328    *
 329    * @return bool
 330    */
 331   public static function isUtf8($str) {
 332     if (!function_exists(mb_detect_encoding)) {
 333       // eliminate all white space from the string
 334       $str = preg_replace('/\s+/', '', $str);
 335
 336       // pattern stolen from the php.net function documentation for
 337       // utf8decode();
 338       // comment by JF Sebastian, 30-Mar-2005
 339       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);
 340       // ||
 341       // iconv('ISO-8859-1', 'UTF-8', $str);
 342     }
 343     else {
 344       $enc = mb_detect_encoding($str, ['UTF-8'], TRUE);
 345       return ($enc !== FALSE);
 346     }
 347   }
 348
 349   /**
 350    * Determine if two hrefs are equivalent (fuzzy match)
 351    *
 352    * @param string $url1
 353    *   The first url to be matched.
 354    * @param string $url2
 355    *   The second url to be matched against.
 356    *
 357    * @return bool
 358    *   true if the urls match, else false
 359    */
 360   public static function match($url1, $url2) {
 361     $url1 = strtolower($url1);
 362     $url2 = strtolower($url2);
 363
 364     $url1Str = parse_url($url1);
 365     $url2Str = parse_url($url2);
 366
 367     if ($url1Str['path'] == $url2Str['path'] &&
 368       self::extractURLVarValue(CRM_Utils_Array::value('query', $url1Str)) == self::extractURLVarValue(CRM_Utils_Array::value('query', $url2Str))
 369     ) {
 370       return TRUE;
 371     }
 372     return FALSE;
 373   }
 374
 375   /**
 376    * Extract the civicrm path from the url.
 377    *
 378    * @param string $query
 379    *   A url string.
 380    *
 381    * @return string|null
 382    *   civicrm url (eg: civicrm/contact/search)
 383    */
 384   public static function extractURLVarValue($query) {
 385     $config = CRM_Core_Config::singleton();
 386     $urlVar = $config->userFrameworkURLVar;
 387
 388     $params = explode('&', $query);
 389     foreach ($params as $p) {
 390       if (strpos($p, '=')) {
 391         list($k, $v) = explode('=', $p);
 392         if ($k == $urlVar) {
 393           return $v;
 394         }
 395       }
 396     }
 397     return NULL;
 398   }
 399
 400   /**
 401    * Translate a true/false/yes/no string to a 0 or 1 value
 402    *
 403    * @param string $str
 404    *   The string to be translated.
 405    *
 406    * @return bool
 407    */
 408   public static function strtobool($str) {
 409     if (!is_scalar($str)) {
 410       return FALSE;
 411     }
 412
 413     if (preg_match('/^(y(es)?|t(rue)?|1)$/i', $str)) {
 414       return TRUE;
 415     }
 416     return FALSE;
 417   }
 418
 419   /**
 420    * Returns string '1' for a true/yes/1 string, and '0' for no/false/0 else returns false
 421    *
 422    * @param string $str
 423    *   The string to be translated.
 424    *
 425    * @return string|false
 426    */
 427   public static function strtoboolstr($str) {
 428     if (!is_scalar($str)) {
 429       return FALSE;
 430     }
 431
 432     if (preg_match('/^(y(es)?|t(rue)?|1)$/i', $str)) {
 433       return '1';
 434     }
 435     elseif (preg_match('/^(n(o)?|f(alse)?|0)$/i', $str)) {
 436       return '0';
 437     }
 438     else {
 439       return FALSE;
 440     }
 441   }
 442
 443   /**
 444    * Convert a HTML string into a text one using html2text
 445    *
 446    * @param string $html
 447    *   The string to be converted.
 448    *
 449    * @return string
 450    *   the converted string
 451    */
 452   public static function htmlToText($html) {
 453     require_once 'html2text/rcube_html2text.php';
 454     $token_html = preg_replace('!\{([a-z_.]+)\}!i', 'token:{$1}', $html);
 455     $converter = new rcube_html2text($token_html);
 456     $token_text = $converter->get_text();
 457     $text = preg_replace('!token\:\{([a-z_.]+)\}!i', '{$1}', $token_text);
 458     return $text;
 459   }
 460
 461   /**
 462    * @param $string
 463    * @param array $params
 464    */
 465   public static function extractName($string, &$params) {
 466     $name = trim($string);
 467     if (empty($name)) {
 468       return;
 469     }
 470
 471     // strip out quotes
 472     $name = str_replace('"', '', $name);
 473     $name = str_replace('\'', '', $name);
 474
 475     // check for comma in name
 476     if (strpos($name, ',') !== FALSE) {
 477
 478       // name has a comma - assume lname, fname [mname]
 479       $names = explode(',', $name);
 480       if (count($names) > 1) {
 481         $params['last_name'] = trim($names[0]);
 482
 483         // check for space delim
 484         $fnames = explode(' ', trim($names[1]));
 485         if (count($fnames) > 1) {
 486           $params['first_name'] = trim($fnames[0]);
 487           $params['middle_name'] = trim($fnames[1]);
 488         }
 489         else {
 490           $params['first_name'] = trim($fnames[0]);
 491         }
 492       }
 493       else {
 494         $params['first_name'] = trim($names[0]);
 495       }
 496     }
 497     else {
 498       // name has no comma - assume fname [mname] fname
 499       $names = explode(' ', $name);
 500       if (count($names) == 1) {
 501         $params['first_name'] = $names[0];
 502       }
 503       elseif (count($names) == 2) {
 504         $params['first_name'] = $names[0];
 505         $params['last_name'] = $names[1];
 506       }
 507       else {
 508         $params['first_name'] = $names[0];
 509         $params['middle_name'] = $names[1];
 510         $params['last_name'] = $names[2];
 511       }
 512     }
 513   }
 514
 515   /**
 516    * @param $string
 517    *
 518    * @return array
 519    */
 520   public static function &makeArray($string) {
 521     $string = trim($string);
 522
 523     $values = explode("\n", $string);
 524     $result = [];
 525     foreach ($values as $value) {
 526       list($n, $v) = CRM_Utils_System::explode('=', $value, 2);
 527       if (!empty($v)) {
 528         $result[trim($n)] = trim($v);
 529       }
 530     }
 531     return $result;
 532   }
 533
 534   /**
 535    * Given an ezComponents-parsed representation of
 536    * a text with alternatives return only the first one
 537    *
 538    * @param string $full
 539    *   All alternatives as a long string (or some other text).
 540    *
 541    * @return string
 542    *   only the first alternative found (or the text without alternatives)
 543    */
 544   public static function stripAlternatives($full) {
 545     $matches = [];
 546     preg_match('/-ALTERNATIVE ITEM 0-(.*?)-ALTERNATIVE ITEM 1-.*-ALTERNATIVE END-/s', $full, $matches);
 547
 548     if (isset($matches[1]) &&
 549       trim(strip_tags($matches[1])) != ''
 550     ) {
 551       return $matches[1];
 552     }
 553     else {
 554       return $full;
 555     }
 556   }
 557
 558   /**
 559    * Strip leading, trailing, double spaces from string
 560    * used for postal/greeting/addressee
 561    *
 562    * @param string $string
 563    *   Input string to be cleaned.
 564    *
 565    * @return string
 566    *   the cleaned string
 567    */
 568   public static function stripSpaces($string) {
 569     return (empty($string)) ? $string : preg_replace("/\s{2,}/", " ", trim($string));
 570   }
 571
 572   /**
 573    * clean the URL 'path' variable that we use
 574    * to construct CiviCRM urls by removing characters from the path variable
 575    *
 576    * @param string $string
 577    *   The input string to be sanitized.
 578    * @param array $search
 579    *   The characters to be sanitized.
 580    * @param string $replace
 581    *   The character to replace it with.
 582    *
 583    * @return string
 584    *   the sanitized string
 585    */
 586   public static function stripPathChars(
 587     $string,
 588     $search = NULL,
 589     $replace = NULL
 590   ) {
 591     static $_searchChars = NULL;
 592     static $_replaceChar = NULL;
 593
 594     if (empty($string)) {
 595       return $string;
 596     }
 597
 598     if ($_searchChars == NULL) {
 599       $_searchChars = [
 600         '&',
 601         ';',
 602         ',',
 603         '=',
 604         '$',
 605         '"',
 606         "'",
 607         '\\',
 608         '<',
 609         '>',
 610         '(',
 611         ')',
 612         ' ',
 613         "\r",
 614         "\r\n",
 615         "\n",
 616         "\t",
 617       ];
 618       $_replaceChar = '_';
 619     }
 620
 621     if ($search == NULL) {
 622       $search = $_searchChars;
 623     }
 624
 625     if ($replace == NULL) {
 626       $replace = $_replaceChar;
 627     }
 628
 629     return str_replace($search, $replace, $string);
 630   }
 631
 632   /**
 633    * Use HTMLPurifier to clean up a text string and remove any potential
 634    * xss attacks. This is primarily used in public facing pages which
 635    * accept html as the input string
 636    *
 637    * @param string $string
 638    *   The input string.
 639    *
 640    * @return string
 641    *   the cleaned up string
 642    */
 643   public static function purifyHTML($string) {
 644     static $_filter = NULL;
 645     if (!$_filter) {
 646       $config = HTMLPurifier_Config::createDefault();
 647       $config->set('Core.Encoding', 'UTF-8');
 648       $config->set('Attr.AllowedFrameTargets', ['_blank', '_self', '_parent', '_top']);
 649
 650       // Disable the cache entirely
 651       $config->set('Cache.DefinitionImpl', NULL);
 652
 653       $_filter = new HTMLPurifier($config);
 654     }
 655
 656     return $_filter->purify($string);
 657   }
 658
 659   /**
 660    * Truncate $string; if $string exceeds $maxLen, place "..." at the end
 661    *
 662    * @param string $string
 663    * @param int $maxLen
 664    *
 665    * @return string
 666    */
 667   public static function ellipsify($string, $maxLen) {
 668     if (mb_strlen($string, 'UTF-8') <= $maxLen) {
 669       return $string;
 670     }
 671     return mb_substr($string, 0, $maxLen - 3, 'UTF-8') . '...';
 672   }
 673
 674   /**
 675    * Generate a random string.
 676    *
 677    * @param $len
 678    * @param $alphabet
 679    * @return string
 680    */
 681   public static function createRandom($len, $alphabet) {
 682     $alphabetSize = strlen($alphabet);
 683     $result = '';
 684     for ($i = 0; $i < $len; $i++) {
 685       $result .= $alphabet[rand(1, $alphabetSize) - 1];
 686     }
 687     return $result;
 688   }
 689
 690   /**
 691    * Examples:
 692    * "admin foo" => array(NULL,"admin foo")
 693    * "cms:admin foo" => array("cms", "admin foo")
 694    *
 695    * @param string $delim
 696    * @param string $string
 697    *   E.g. "view all contacts". Syntax: "[prefix:]name".
 698    * @param string|null $defaultPrefix
 699    *
 700    * @return array
 701    *   (0 => string|NULL $prefix, 1 => string $value)
 702    */
 703   public static function parsePrefix($delim, $string, $defaultPrefix = NULL) {
 704     $pos = strpos($string, $delim);
 705     if ($pos === FALSE) {
 706       return [$defaultPrefix, $string];
 707     }
 708     else {
 709       return [substr($string, 0, $pos), substr($string, 1 + $pos)];
 710     }
 711   }
 712
 713   /**
 714    * This function will mask part of the the user portion of an Email address (everything before the @)
 715    *
 716    * @param string $email
 717    *   The email address to be masked.
 718    * @param string $maskChar
 719    *   The character used for masking.
 720    * @param int $percent
 721    *   The percentage of the user portion to be masked.
 722    *
 723    * @return string
 724    *   returns the masked Email address
 725    */
 726   public static function maskEmail($email, $maskChar = '*', $percent = 50) {
 727     list($user, $domain) = preg_split("/@/", $email);
 728     $len = strlen($user);
 729     $maskCount = floor($len * $percent / 100);
 730     $offset = floor(($len - $maskCount) / 2);
 731
 732     $masked = substr($user, 0, $offset)
 733       . str_repeat($maskChar, $maskCount)
 734       . substr($user, $maskCount + $offset);
 735
 736     return ($masked . '@' . $domain);
 737   }
 738
 739   /**
 740    * This function compares two strings.
 741    *
 742    * @param string $strOne
 743    *   String one.
 744    * @param string $strTwo
 745    *   String two.
 746    * @param bool $case
 747    *   Boolean indicating whether you want the comparison to be case sensitive or not.
 748    *
 749    * @return bool
 750    *   TRUE (string are identical); FALSE (strings are not identical)
 751    */
 752   public static function compareStr($strOne, $strTwo, $case) {
 753     if ($case == TRUE) {
 754       // Convert to lowercase and trim white spaces
 755       if (strtolower(trim($strOne)) == strtolower(trim($strTwo))) {
 756         // yes - they are identical
 757         return TRUE;
 758       }
 759       else {
 760         // not identical
 761         return FALSE;
 762       }
 763     }
 764     if ($case == FALSE) {
 765       // Trim white spaces
 766       if (trim($strOne) == trim($strTwo)) {
 767         // yes - they are identical
 768         return TRUE;
 769       }
 770       else {
 771         // not identical
 772         return FALSE;
 773       }
 774     }
 775   }
 776
 777   /**
 778    * Many parts of the codebase have a convention of internally passing around
 779    * HTML-encoded URLs. This effectively means that "&" is replaced by "&amp;"
 780    * (because most other odd characters are %-escaped in URLs; and %-escaped
 781    * strings don't need any extra escaping in HTML).
 782    *
 783    * @param string $htmlUrl
 784    *   URL with HTML entities.
 785    * @return string
 786    *   URL without HTML entities
 787    */
 788   public static function unstupifyUrl($htmlUrl) {
 789     return str_replace('&amp;', '&', $htmlUrl);
 790   }
 791
 792   /**
 793    * When a user supplies a URL (e.g. to an image), we'd like to:
 794    *  - Remove the protocol and domain name if the URL points to the current
 795    *    site.
 796    *  - Keep the domain name for remote URLs.
 797    *  - Optionally, force remote URLs to use https instead of http (which is
 798    *    useful for images)
 799    *
 800    * @param string $url
 801    *   The URL to simplify. Examples:
 802    *     "https://example.org/sites/default/files/coffee-mug.jpg"
 803    *     "sites/default/files/coffee-mug.jpg"
 804    *     "http://i.stack.imgur.com/9jb2ial01b.png"
 805    * @param bool $forceHttps = FALSE
 806    *   If TRUE, ensure that remote URLs use https. If a URL with
 807    *   http is supplied, then we'll change it to https.
 808    *   This is useful for situations like showing a premium product on a
 809    *   contribution, because (as reported in CRM-14283) if the user gets a
 810    *   browser warning like "page contains insecure elements" on a contribution
 811    *   page, that's a very bad thing. Thus, even if changing http to https
 812    *   breaks the image, that's better than leaving http content in a
 813    *   contribution page.
 814    *
 815    * @return string
 816    *   The simplified URL. Examples:
 817    *     "/sites/default/files/coffee-mug.jpg"
 818    *     "https://i.stack.imgur.com/9jb2ial01b.png"
 819    */
 820   public static function simplifyURL($url, $forceHttps = FALSE) {
 821     $config = CRM_Core_Config::singleton();
 822     $siteURLParts = self::simpleParseUrl($config->userFrameworkBaseURL);
 823     $urlParts = self::simpleParseUrl($url);
 824
 825     // If the image is locally hosted, then only give the path to the image
 826     $urlIsLocal
 827       = ($urlParts['host+port'] == '')
 828       | ($urlParts['host+port'] == $siteURLParts['host+port']);
 829     if ($urlIsLocal) {
 830       // and make sure it begins with one forward slash
 831       return preg_replace('_^/*(?=.)_', '/', $urlParts['path+query']);
 832     }
 833
 834     // If the URL is external, then keep the full URL as supplied
 835     else {
 836       return $forceHttps ? preg_replace('_^http://_', 'https://', $url) : $url;
 837     }
 838   }
 839
 840   /**
 841    * A simplified version of PHP's parse_url() function.
 842    *
 843    * @param string $url
 844    *   e.g. "https://example.com:8000/foo/bar/?id=1#fragment"
 845    *
 846    * @return array
 847    *   Will always contain keys 'host+port' and 'path+query', even if they're
 848    *   empty strings. Example:
 849    *   [
 850    *     'host+port' => "example.com:8000",
 851    *     'path+query' => "/foo/bar/?id=1",
 852    *   ]
 853    */
 854   public static function simpleParseUrl($url) {
 855     $parts = parse_url($url);
 856     $host = $parts['host'] ?? '';
 857     $port = isset($parts['port']) ? ':' . $parts['port'] : '';
 858     $path = $parts['path'] ?? '';
 859     $query = isset($parts['query']) ? '?' . $parts['query'] : '';
 860     return [
 861       'host+port' => "$host$port",
 862       'path+query' => "$path$query",
 863     ];
 864   }
 865
 866   /**
 867    * Formats a string of attributes for insertion in an html tag.
 868    *
 869    * @param array $attributes
 870    *
 871    * @return string
 872    */
 873   public static function htmlAttributes($attributes) {
 874     $output = '';
 875     foreach ($attributes as $name => $vals) {
 876       $output .= " $name=\"" . htmlspecialchars(implode(' ', (array) $vals)) . '"';
 877     }
 878     return ltrim($output);
 879   }
 880
 881   /**
 882    * Determine if $string starts with $fragment.
 883    *
 884    * @param string $string
 885    *   The long string.
 886    * @param string $fragment
 887    *   The fragment to look for.
 888    * @return bool
 889    */
 890   public static function startsWith($string, $fragment) {
 891     if ($fragment === '') {
 892       return TRUE;
 893     }
 894     $len = strlen($fragment);
 895     return substr($string, 0, $len) === $fragment;
 896   }
 897
 898   /**
 899    * Determine if $string ends with $fragment.
 900    *
 901    * @param string $string
 902    *   The long string.
 903    * @param string $fragment
 904    *   The fragment to look for.
 905    * @return bool
 906    */
 907   public static function endsWith($string, $fragment) {
 908     if ($fragment === '') {
 909       return TRUE;
 910     }
 911     $len = strlen($fragment);
 912     return substr($string, -1 * $len) === $fragment;
 913   }
 914
 915   /**
 916    * @param string|array $patterns
 917    * @param array $allStrings
 918    * @param bool $allowNew
 919    *   Whether to return new, unrecognized names.
 920    * @return array
 921    */
 922   public static function filterByWildcards($patterns, $allStrings, $allowNew = FALSE) {
 923     $patterns = (array) $patterns;
 924     $result = [];
 925     foreach ($patterns as $pattern) {
 926       if (!\CRM_Utils_String::endsWith($pattern, '*')) {
 927         if ($allowNew || in_array($pattern, $allStrings)) {
 928           $result[] = $pattern;
 929         }
 930       }
 931       else {
 932         $prefix = rtrim($pattern, '*');
 933         foreach ($allStrings as $key) {
 934           if (\CRM_Utils_String::startsWith($key, $prefix)) {
 935             $result[] = $key;
 936           }
 937         }
 938       }
 939     }
 940     return array_values(array_unique($result));
 941   }
 942
 943   /**
 944    * Safely unserialize a string of scalar or array values (but not objects!)
 945    *
 946    * Use `xkerman/restricted-unserialize` to unserialize strings using PHP's
 947    * serialization format. `restricted-unserialize` works like PHP's built-in
 948    * `unserialize` function except that it does not deserialize object instances,
 949    * making it immune to PHP Object Injection {@see https://www.owasp.org/index.php/PHP_Object_Injection}
 950    * vulnerabilities.
 951    *
 952    * Note: When dealing with user inputs, it is generally recommended to use
 953    * safe, standard data interchange formats such as JSON rather than PHP's
 954    * serialization format when dealing with user input.
 955    *
 956    * @param string|null $string
 957    *
 958    * @return mixed
 959    */
 960   public static function unserialize($string) {
 961     if (!is_string($string)) {
 962       return FALSE;
 963     }
 964     try {
 965       return unserialize($string);
 966     }
 967     catch (UnserializeFailedException $e) {
 968       return FALSE;
 969     }
 970   }
 971
 972   /**
 973    * Returns the plural form of an English word.
 974    *
 975    * @param string $str
 976    * @return string
 977    */
 978   public static function pluralize($str) {
 979     $lastLetter = substr($str, -1);
 980     $lastTwo = substr($str, -2);
 981     if ($lastLetter == 's' || $lastLetter == 'x' || $lastTwo == 'ch') {
 982       return $str . 'es';
 983     }
 984     if ($lastLetter == 'y' && !in_array($lastTwo, ['ay', 'ey', 'iy', 'oy', 'uy'])) {
 985       return substr($str, 0, -1) . 'ies';
 986     }
 987     return $str . 's';
 988   }
 989
 990   /**
 991    * Generic check as to whether any tokens are in the given string.
 992    *
 993    * It might be a smarty token OR a CiviCRM token. In both cases the
 994    * absence of a '{' indicates no token is present.
 995    *
 996    * @param string $string
 997    *
 998    * @return bool
 999    */
1000   public static function stringContainsTokens(string $string) {
1001     return strpos($string, '{') !== FALSE;
1002   }
1003
1004   /**
1005    * Parse a string through smarty without creating a smarty template file per string.
1006    *
1007    * This function is for swapping out any smarty tokens that appear in a string
1008    * and are not re-used much if at all. For example parsing a contact's greeting
1009    * does not need to be cached are there are some minor security / data privacy benefits
1010    * to not caching them per file. We also save disk space, reduce I/O and disk clearing time.
1011    *
1012    * Doing this is cleaning in Smarty3 which we are alas not using
1013    * https://www.smarty.net/docs/en/resources.string.tpl
1014    *
1015    * However, it highlights that smarty-eval is not evil-eval and still have the security applied.
1016    *
1017    * In order to replicate that in Smarty2 I'm using {eval} per
1018    * https://www.smarty.net/docsv2/en/language.function.eval.tpl#id2820446
1019    * From the above:
1020    * - Evaluated variables are treated the same as templates. They follow the same escapement and security features just as if they were templates.
1021    * - Evaluated variables are compiled on every invocation, the compiled versions are not saved! However if you have caching enabled, the output
1022    *   will be cached with the rest of the template.
1023    *
1024    * Our set up does not have caching enabled and my testing suggests this still works fine with it
1025    * enabled so turning it off before running this is out of caution based on the above.
1026    *
1027    * When this function is run only one template file is created (for the eval) tag no matter how
1028    * many times it is run. This compares to it otherwise creating one file for every parsed string.
1029    *
1030    * @param string $templateString
1031    *
1032    * @return string
1033    */
1034   public static function parseOneOffStringThroughSmarty($templateString) {
1035     if (!CRM_Utils_String::stringContainsTokens($templateString)) {
1036       // Skip expensive smarty processing.
1037       return $templateString;
1038     }
1039     $smarty = CRM_Core_Smarty::singleton();
1040     $cachingValue = $smarty->caching;
1041     $smarty->caching = 0;
1042     $smarty->assign('smartySingleUseString', $templateString);
1043     // Do not escape the smartySingleUseString as that is our smarty template
1044     // and is likely to contain html.
1045     $templateString = (string) $smarty->fetch('string:{eval var=$smartySingleUseString|smarty:nodefaults}');
1046     $smarty->caching = $cachingValue;
1047     $smarty->assign('smartySingleUseString', NULL);
1048     return $templateString;
1049   }
1050
1051 }