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