3 +--------------------------------------------------------------------+
4 | Copyright CiviCRM LLC. All rights reserved. |
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 +--------------------------------------------------------------------+
15 * @copyright CiviCRM LLC https://civicrm.org/licensing
18 use function xKerman\Restricted\unserialize
;
19 use xKerman\Restricted\UnserializeFailedException
;
21 require_once 'HTML/QuickForm/Rule/Email.php';
24 * This class contains string functions.
26 class CRM_Utils_String
{
27 const COMMA
= ",", SEMICOLON
= ";", SPACE
= " ", TAB
= "\t", LINEFEED
= "\n", CARRIAGELINE
= "\r\n", LINECARRIAGE
= "\n\r", CARRIAGERETURN
= "\r";
30 * List of all letters and numbers
32 const ALPHANUMERIC
= 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890';
35 * Convert a display name into a potential variable name.
37 * @param string $title title of the string
38 * @param int $maxLength
41 * An equivalent variable name.
43 public static function titleToVar($title, $maxLength = 31) {
44 $variable = self
::munge($title, '_', $maxLength);
46 if (CRM_Utils_Rule
::title($variable, $maxLength)) {
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);
56 * Replace all non alpha numeric characters and spaces with the replacement character.
59 * The name to be worked on.
61 * The character to use for non-valid chars.
63 * Length of valid variables.
66 * returns the manipulated string
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
72 $name = preg_replace('/[^a-zA-Z0-9]+/', $char, trim($name));
74 //If there are no ascii characters present.
76 $name = self
::createRandom($len, self
::ALPHANUMERIC
);
80 // lets keep variable names short
81 return substr($name, 0, $len);
89 * Convert possibly underscore separated words to camel case.
92 * @param bool $ucFirst
93 * Should the first letter be capitalized like `CamelCase` or lower like `camelCase`
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);
103 * Inverse of above function, converts camelCase to snake_case
108 public static function convertStringToSnakeCase(string $str): string {
109 return strtolower(ltrim(preg_replace('/(?=[A-Z])/', '_$0', $str), '_'));
113 * Takes a variable name and munges it randomly into another variable name.
115 * @param string $name
116 * Initial Variable Name.
118 * Length of valid variables.
121 * Randomized Variable Name
123 public static function rename($name, $len = 4) {
124 $rand = substr(uniqid(), 0, $len);
125 return substr_replace($name, $rand, -$len, $len);
129 * Takes a string and returns the last tuple of the string.
131 * Useful while converting file names to class names etc
133 * @param string $string
135 * @param string $char
136 * Character used to demarcate the components
141 public static function getClassName($string, $char = '_') {
143 if (!is_array($string)) {
144 $names = explode($char, $string);
146 if (!empty($names)) {
147 return array_pop($names);
152 * Appends a name to a string and separated by delimiter.
154 * Does the right thing for an empty string
157 * The string to be appended to.
158 * @param string $delim
159 * The delimiter to use.
161 * The string (or array of strings) to append.
163 public static function append(&$str, $delim, $name) {
168 if (is_array($name)) {
169 foreach ($name as $n) {
186 $str .= $delim . $name;
192 * Determine if the string is composed only of ascii characters.
197 * Attempt utf8 match on failure (default yes).
200 * true if string is ascii
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.
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 ) ) {
214 // if we did match, try for utf-8, or iso8859-1
216 return self
::isUtf8($str);
229 $enc = mb_detect_encoding($str, $order, TRUE);
230 return ($enc == 'ASCII' ||
$enc == 'UTF-8');
235 * Encode string using URL-safe Base64.
240 * @see https://tools.ietf.org/html/rfc4648#section-5
242 public static function base64UrlEncode($v) {
243 return rtrim(str_replace(['+', '/'], ['-', '_'], base64_encode($v)), '=');
247 * Decode string using URL-safe Base64.
251 * @return false|string
252 * @see https://tools.ietf.org/html/rfc4648#section-5
254 public static function base64UrlDecode($v) {
255 // PHP base64_decode() is already forgiving about padding ("=").
256 return base64_decode(str_replace(['-', '_'], ['+', '/'], $v));
260 * Determine the string replacements for redaction.
261 * on the basis of the regular expressions
265 * @param array $regexRules
266 * Regular expression to be matched w/ replacements.
269 * array of strings w/ corresponding redacted outputs
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];
282 $totalMatches = array_merge($totalMatches, $matches[0]);
284 $match = array_flip($totalMatches);
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);
305 * @param $stringRules
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);
317 // return the redacted output
322 * Determine if a string is composed only of utf8 characters
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);
334 // pattern stolen from the php.net function documentation for
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);
339 // iconv('ISO-8859-1', 'UTF-8', $str);
342 $enc = mb_detect_encoding($str, ['UTF-8'], TRUE);
343 return ($enc !== FALSE);
348 * Determine if two hrefs are equivalent (fuzzy match)
350 * @param string $url1
351 * The first url to be matched.
352 * @param string $url2
353 * The second url to be matched against.
356 * true if the urls match, else false
358 public static function match($url1, $url2) {
359 $url1 = strtolower($url1);
360 $url2 = strtolower($url2);
362 $url1Str = parse_url($url1);
363 $url2Str = parse_url($url2);
365 if ($url1Str['path'] == $url2Str['path'] &&
366 self
::extractURLVarValue(CRM_Utils_Array
::value('query', $url1Str)) == self
::extractURLVarValue(CRM_Utils_Array
::value('query', $url2Str))
374 * Extract the civicrm path from the url.
376 * @param string $query
379 * @return string|null
380 * civicrm url (eg: civicrm/contact/search)
382 public static function extractURLVarValue($query) {
383 $config = CRM_Core_Config
::singleton();
384 $urlVar = $config->userFrameworkURLVar
;
386 $params = explode('&', $query);
387 foreach ($params as $p) {
388 if (strpos($p, '=')) {
389 list($k, $v) = explode('=', $p);
399 * Translate a true/false/yes/no string to a 0 or 1 value
402 * The string to be translated.
406 public static function strtobool($str) {
407 if (!is_scalar($str)) {
411 if (preg_match('/^(y(es)?|t(rue)?|1)$/i', $str)) {
418 * Returns string '1' for a true/yes/1 string, and '0' for no/false/0 else returns false
421 * The string to be translated.
425 public static function strtoboolstr($str) {
426 if (!is_scalar($str)) {
430 if (preg_match('/^(y(es)?|t(rue)?|1)$/i', $str)) {
433 elseif (preg_match('/^(n(o)?|f(alse)?|0)$/i', $str)) {
442 * Convert a HTML string into a text one using html2text
444 * @param string $html
445 * The string to be converted.
448 * the converted string
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);
461 * @param array $params
463 public static function extractName($string, &$params) {
464 $name = trim($string);
470 $name = str_replace('"', '', $name);
471 $name = str_replace('\'', '', $name);
473 // check for comma in name
474 if (strpos($name, ',') !== FALSE) {
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]);
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]);
488 $params['first_name'] = trim($fnames[0]);
492 $params['first_name'] = trim($names[0]);
496 // name has no comma - assume fname [mname] fname
497 $names = explode(' ', $name);
498 if (count($names) == 1) {
499 $params['first_name'] = $names[0];
501 elseif (count($names) == 2) {
502 $params['first_name'] = $names[0];
503 $params['last_name'] = $names[1];
506 $params['first_name'] = $names[0];
507 $params['middle_name'] = $names[1];
508 $params['last_name'] = $names[2];
518 public static function &makeArray($string) {
519 $string = trim($string);
521 $values = explode("\n", $string);
523 foreach ($values as $value) {
524 list($n, $v) = CRM_Utils_System
::explode('=', $value, 2);
526 $result[trim($n)] = trim($v);
533 * Given an ezComponents-parsed representation of
534 * a text with alternatives return only the first one
536 * @param string $full
537 * All alternatives as a long string (or some other text).
540 * only the first alternative found (or the text without alternatives)
542 public static function stripAlternatives($full) {
544 preg_match('/-ALTERNATIVE ITEM 0-(.*?)-ALTERNATIVE ITEM 1-.*-ALTERNATIVE END-/s', $full, $matches);
546 if (isset($matches[1]) &&
547 trim(strip_tags($matches[1])) != ''
557 * Strip leading, trailing, double spaces from string
558 * used for postal/greeting/addressee
560 * @param string $string
561 * Input string to be cleaned.
566 public static function stripSpaces($string) {
567 return (empty($string)) ?
$string : preg_replace("/\s{2,}/", " ", trim($string));
571 * clean the URL 'path' variable that we use
572 * to construct CiviCRM urls by removing characters from the path variable
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.
582 * the sanitized string
584 public static function stripPathChars(
589 static $_searchChars = NULL;
590 static $_replaceChar = NULL;
592 if (empty($string)) {
596 if ($_searchChars == NULL) {
619 if ($search == NULL) {
620 $search = $_searchChars;
623 if ($replace == NULL) {
624 $replace = $_replaceChar;
627 return str_replace($search, $replace, $string);
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
635 * @param string $string
639 * the cleaned up string
641 public static function purifyHTML($string) {
642 static $_filter = NULL;
644 $config = HTMLPurifier_Config
::createDefault();
645 $config->set('Core.Encoding', 'UTF-8');
646 $config->set('Attr.AllowedFrameTargets', ['_blank', '_self', '_parent', '_top']);
648 // Disable the cache entirely
649 $config->set('Cache.DefinitionImpl', NULL);
651 $_filter = new HTMLPurifier($config);
654 return $_filter->purify($string);
658 * Truncate $string; if $string exceeds $maxLen, place "..." at the end
660 * @param string $string
665 public static function ellipsify($string, $maxLen) {
666 if (mb_strlen($string, 'UTF-8') <= $maxLen) {
669 return mb_substr($string, 0, $maxLen - 3, 'UTF-8') . '...';
673 * Generate a random string.
679 public static function createRandom($len, $alphabet) {
680 $alphabetSize = strlen($alphabet);
682 for ($i = 0; $i < $len; $i++
) {
683 $result .= $alphabet[rand(1, $alphabetSize) - 1];
690 * "admin foo" => array(NULL,"admin foo")
691 * "cms:admin foo" => array("cms", "admin foo")
694 * @param string $string
695 * E.g. "view all contacts". Syntax: "[prefix:]name".
696 * @param null $defaultPrefix
699 * (0 => string|NULL $prefix, 1 => string $value)
701 public static function parsePrefix($delim, $string, $defaultPrefix = NULL) {
702 $pos = strpos($string, $delim);
703 if ($pos === FALSE) {
704 return [$defaultPrefix, $string];
707 return [substr($string, 0, $pos), substr($string, 1 +
$pos)];
712 * This function will mask part of the the user portion of an Email address (everything before the @)
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.
722 * returns the masked Email address
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);
730 $masked = substr($user, 0, $offset)
731 . str_repeat($maskChar, $maskCount)
732 . substr($user, $maskCount +
$offset);
734 return ($masked . '@' . $domain);
738 * This function compares two strings.
740 * @param string $strOne
742 * @param string $strTwo
745 * Boolean indicating whether you want the comparison to be case sensitive or not.
748 * TRUE (string are identical); FALSE (strings are not identical)
750 public static function compareStr($strOne, $strTwo, $case) {
752 // Convert to lowercase and trim white spaces
753 if (strtolower(trim($strOne)) == strtolower(trim($strTwo))) {
754 // yes - they are identical
762 if ($case == FALSE) {
764 if (trim($strOne) == trim($strTwo)) {
765 // yes - they are identical
776 * Many parts of the codebase have a convention of internally passing around
777 * HTML-encoded URLs. This effectively means that "&" is replaced by "&"
778 * (because most other odd characters are %-escaped in URLs; and %-escaped
779 * strings don't need any extra escaping in HTML).
781 * @param string $htmlUrl
782 * URL with HTML entities.
784 * URL without HTML entities
786 public static function unstupifyUrl($htmlUrl) {
787 return str_replace('&', '&', $htmlUrl);
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
794 * - Keep the domain name for remote URLs.
795 * - Optionally, force remote URLs to use https instead of http (which is
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
814 * The simplified URL. Examples:
815 * "/sites/default/files/coffee-mug.jpg"
816 * "https://i.stack.imgur.com/9jb2ial01b.png"
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);
823 // If the image is locally hosted, then only give the path to the image
825 = ($urlParts['host+port'] == '')
826 |
($urlParts['host+port'] == $siteURLParts['host+port']);
828 // and make sure it begins with one forward slash
829 return preg_replace('_^/*(?=.)_', '/', $urlParts['path+query']);
832 // If the URL is external, then keep the full URL as supplied
834 return $forceHttps ?
preg_replace('_^http://_', 'https://', $url) : $url;
839 * A simplified version of PHP's parse_url() function.
842 * e.g. "https://example.com:8000/foo/bar/?id=1#fragment"
845 * Will always contain keys 'host+port' and 'path+query', even if they're
846 * empty strings. Example:
848 * 'host+port' => "example.com:8000",
849 * 'path+query' => "/foo/bar/?id=1",
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'] : '';
859 'host+port' => "$host$port",
860 'path+query' => "$path$query",
865 * Formats a string of attributes for insertion in an html tag.
867 * @param array $attributes
871 public static function htmlAttributes($attributes) {
873 foreach ($attributes as $name => $vals) {
874 $output .= " $name=\"" . htmlspecialchars(implode(' ', (array) $vals)) . '"';
876 return ltrim($output);
880 * Determine if $string starts with $fragment.
882 * @param string $string
884 * @param string $fragment
885 * The fragment to look for.
888 public static function startsWith($string, $fragment) {
889 if ($fragment === '') {
892 $len = strlen($fragment);
893 return substr($string, 0, $len) === $fragment;
897 * Determine if $string ends with $fragment.
899 * @param string $string
901 * @param string $fragment
902 * The fragment to look for.
905 public static function endsWith($string, $fragment) {
906 if ($fragment === '') {
909 $len = strlen($fragment);
910 return substr($string, -1 * $len) === $fragment;
914 * @param string|array $patterns
915 * @param array $allStrings
916 * @param bool $allowNew
917 * Whether to return new, unrecognized names.
920 public static function filterByWildcards($patterns, $allStrings, $allowNew = FALSE) {
921 $patterns = (array) $patterns;
923 foreach ($patterns as $pattern) {
924 if (!\CRM_Utils_String
::endsWith($pattern, '*')) {
925 if ($allowNew ||
in_array($pattern, $allStrings)) {
926 $result[] = $pattern;
930 $prefix = rtrim($pattern, '*');
931 foreach ($allStrings as $key) {
932 if (\CRM_Utils_String
::startsWith($key, $prefix)) {
938 return array_values(array_unique($result));
942 * Safely unserialize a string of scalar or array values (but not objects!)
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}
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.
954 * @param string|NULL $string
958 public static function unserialize($string) {
959 if (!is_string($string)) {
963 return unserialize($string);
965 catch (UnserializeFailedException
$e) {
971 * Returns the plural form of an English word.
976 public static function pluralize($str) {
977 $lastLetter = substr($str, -1);
978 $lastTwo = substr($str, -2);
979 if ($lastLetter == 's' ||
$lastLetter == 'x' ||
$lastTwo == 'ch') {
982 if ($lastLetter == 'y' && !in_array($lastTwo, ['ay', 'ey', 'iy', 'oy', 'uy'])) {
983 return substr($str, 0, -1) . 'ies';
989 * Generic check as to whether any tokens are in the given string.
991 * It might be a smarty token OR a CiviCRM token. In both cases the
992 * absence of a '{' indicates no token is present.
994 * @param string $string
998 public static function stringContainsTokens(string $string) {
999 return strpos($string, '{') !== FALSE;
1003 * Parse a string through smarty without creating a smarty template file per string.
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.
1010 * Doing this is cleaning in Smarty3 which we are alas not using
1011 * https://www.smarty.net/docs/en/resources.string.tpl
1013 * However, it highlights that smarty-eval is not evil-eval and still have the security applied.
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
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.
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.
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.
1028 * @param string $templateString
1032 public static function parseOneOffStringThroughSmarty($templateString) {
1033 if (!CRM_Utils_String
::stringContainsTokens($templateString)) {
1034 // Skip expensive smarty processing.
1035 return $templateString;
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;