Documentation

CRM_Utils_String
in package

CRM

This class contains string functions.

Constants

ALPHANUMERIC = 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890': List of all letters and numbers
CARRIAGELINE = "\r\n"
CARRIAGERETURN = "\r"
COMMA = ","
LINECARRIAGE = "\n\r"
LINEFEED = "\n"
SEMICOLON = ";"
SPACE = " "
TAB = "\t"

Methods

append() : mixed: Appends a name to a string and separated by delimiter.
base64UrlDecode() : false|string: Decode string using URL-safe Base64.
base64UrlEncode() : string: Encode string using URL-safe Base64.
compareStr() : bool: This function compares two strings.
convertStringToCamel() : string: Convert possibly underscore, space or dash separated words to CamelCase.
convertStringToDash() : string: Converts `CamelCase` or `snake_case` to `dash-format`
convertStringToSnakeCase() : string: Inverse of above function, converts camelCase to snake_case
createRandom() : string: Generate a random string.
ellipsify() : string: Truncate $string; if $string exceeds $maxLen, place "..." at the end
endsWith() : bool
extractName() : mixed
extractURLVarValue() : string|null: Extract the civicrm path from the url.
filterByWildcards() : array<string|int, mixed>
getClassName() : string: Takes a string and returns the last tuple of the string.
htmlAttributes() : string: Formats a string of attributes for insertion in an html tag.
htmlToText() : string: Convert a HTML string into a text one using html2text
isAscii() : bool: Determine if the string is composed only of ascii characters.
isUtf8() : bool: Determine if a string is composed only of utf8 characters
makeArray() : array<string|int, mixed>
maskEmail() : string: This function will mask part of the the user portion of an Email address (everything before the @)
match() : bool: Determine if two hrefs are equivalent (fuzzy match)
munge() : string: Replace all non alpha numeric characters and spaces with the replacement character.
parseOneOffStringThroughSmarty() : string: Parse a string through smarty without creating a smarty template file per string.
parsePrefix() : array<string|int, mixed>: Examples: "admin foo" => array(NULL,"admin foo") "cms:admin foo" => array("cms", "admin foo")
pluralize() : string: Returns the plural form of an English word.
purifyHTML() : string: Use HTMLPurifier to clean up a text string and remove any potential xss attacks. This is primarily used in public facing pages which accept html as the input string
redaction() : mixed
regex() : array<string|int, mixed>: Determine the string replacements for redaction.
rename() : string: Takes a variable name and munges it randomly into another variable name.
simpleParseUrl() : array<string|int, mixed>: A simplified version of PHP's parse_url() function.
simplifyURL() : string: When a user supplies a URL (e.g. to an image), we'd like to: - Remove the protocol and domain name if the URL points to the current site.
startsWith() : bool
stringContainsTokens() : bool: Generic check as to whether any tokens are in the given string.
stripAlternatives() : string: Given an ezComponents-parsed representation of a text with alternatives return only the first one
stripPathChars() : string: clean the URL 'path' variable that we use to construct CiviCRM urls by removing characters from the path variable
stripSpaces() : string: Strip leading, trailing, double spaces from string used for postal/greeting/addressee
strtobool() : bool: Translate a true/false/yes/no string to a 0 or 1 value
strtoboolstr() : string|false: Returns string '1' for a true/yes/1 string, and '0' for no/false/0 else returns false
titleToVar() : string: Convert a display name into a potential variable name.
unserialize() : mixed: Safely unserialize a string of scalar or array values (but not objects!)
unstupifyUrl() : string: Many parts of the codebase have a convention of internally passing around HTML-encoded URLs. This effectively means that "&" is replaced by "&" (because most other odd characters are %-escaped in URLs; and %-escaped strings don't need any extra escaping in HTML).

ALPHANUMERIC

List of all letters and numbers


    public
        mixed
    ALPHANUMERIC
    = 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890'

CARRIAGELINE


    public
        mixed
    CARRIAGELINE
    = "\r\n"

CARRIAGERETURN


    public
        mixed
    CARRIAGERETURN
    = "\r"

COMMA


    public
        mixed
    COMMA
    = ","

LINECARRIAGE


    public
        mixed
    LINECARRIAGE
    = "\n\r"

LINEFEED


    public
        mixed
    LINEFEED
    = "\n"

SEMICOLON


    public
        mixed
    SEMICOLON
    = ";"

SPACE


    public
        mixed
    SPACE
    = " "

TAB


    public
        mixed
    TAB
    = "\t"

append()

Appends a name to a string and separated by delimiter.


    public
            static        append(string &$str, string $delim, mixed $name) : mixed

Does the right thing for an empty string

Parameters

$str : string: The string to be appended to.
$delim : string: The delimiter to use.
$name : mixed: The string (or array of strings) to append.

base64UrlDecode()

Decode string using URL-safe Base64.


    public
            static        base64UrlDecode(string $v) : false|string

Parameters

$v : string

Return values

false|string

base64UrlEncode()

Encode string using URL-safe Base64.


    public
            static        base64UrlEncode(string $v) : string

Parameters

$v : string

Return values

string

compareStr()

This function compares two strings.


    public
            static        compareStr(string $strOne, string $strTwo, bool $case) : bool

Parameters

$strOne : string: String one.
$strTwo : string: String two.
$case : bool: Boolean indicating whether you want the comparison to be case sensitive or not.

Return values

bool —

TRUE (string are identical); FALSE (strings are not identical)

convertStringToCamel()

Convert possibly underscore, space or dash separated words to CamelCase.


    public
            static        convertStringToCamel(string $str[, bool $ucFirst = TRUE ]) : string

Parameters

$str : string
$ucFirst : bool = TRUE: Should the first letter be capitalized like CamelCase or lower like camelCase

Return values

string

convertStringToDash()

Converts `CamelCase` or `snake_case` to `dash-format`


    public
            static        convertStringToDash(string $str) : string

Parameters

$str : string

Return values

string

convertStringToSnakeCase()

Inverse of above function, converts camelCase to snake_case


    public
            static        convertStringToSnakeCase(string $str) : string

Parameters

$str : string

Return values

string

createRandom()

Generate a random string.


    public
            static        createRandom(int $len, string $alphabet) : string

Parameters

$len : int
$alphabet : string

Return values

string

ellipsify()

Truncate $string; if $string exceeds $maxLen, place "..." at the end


    public
            static        ellipsify(string $string, int $maxLen) : string

Parameters

$string : string
$maxLen : int

Return values

string

endsWith()


    public
            static        endsWith(string $string, string $fragment) : bool

Parameters

$string : string: The long string.
$fragment : string: The fragment to look for.

Return values

bool

extractName()


    public
            static        extractName(mixed $string, array<string|int, mixed> &$params) : mixed

Parameters

$string : mixed
$params : array<string|int, mixed>

extractURLVarValue()

Extract the civicrm path from the url.


    public
            static        extractURLVarValue(string $query) : string|null

Parameters

$query : string: A url string.

Return values

string|null —

civicrm url (eg: civicrm/contact/search)

filterByWildcards()


    public
            static        filterByWildcards(string|array<string|int, mixed> $patterns, array<string|int, mixed> $allStrings[, bool $allowNew = FALSE ]) : array<string|int, mixed>

Parameters

$patterns : string|array<string|int, mixed>
$allStrings : array<string|int, mixed>
$allowNew : bool = FALSE: Whether to return new, unrecognized names.

Return values

array<string|int, mixed>

getClassName()

Takes a string and returns the last tuple of the string.


    public
            static        getClassName(string $string[, string $char = '_' ]) : string

Useful while converting file names to class names etc

Parameters

$string : string: The input string.
$char : string = '_': Character used to demarcate the components

Return values

string —

The last component

htmlAttributes()

Formats a string of attributes for insertion in an html tag.


    public
            static        htmlAttributes(array<string|int, mixed> $attributes) : string

Parameters

$attributes : array<string|int, mixed>

Return values

string

htmlToText()

Convert a HTML string into a text one using html2text


    public
            static        htmlToText(string $html) : string

Parameters

$html : string: The string to be converted.

Return values

string —

the converted string

isAscii()

Determine if the string is composed only of ascii characters.


    public
            static        isAscii(string $str[, bool $utf8 = TRUE ]) : bool

Parameters

$str : string: Input string.
$utf8 : bool = TRUE: Attempt utf8 match on failure (default yes).

Return values

bool —

true if string is ascii

isUtf8()

Determine if a string is composed only of utf8 characters


    public
            static        isUtf8(string $str) : bool

Parameters

$str : string: Input string.

Return values

bool

makeArray()


    public
            static    &    makeArray(mixed $string) : array<string|int, mixed>

Parameters

$string : mixed

Return values

array<string|int, mixed>

maskEmail()

This function will mask part of the the user portion of an Email address (everything before the @)


    public
            static        maskEmail(string $email[, string $maskChar = '*' ][, int $percent = 50 ]) : string

Parameters

$email : string: The email address to be masked.
$maskChar : string = '*': The character used for masking.
$percent : int = 50: The percentage of the user portion to be masked.

Return values

string —

returns the masked Email address

match()

Determine if two hrefs are equivalent (fuzzy match)


    public
            static        match(string $url1, string $url2) : bool

Parameters

$url1 : string: The first url to be matched.
$url2 : string: The second url to be matched against.

Return values

bool —

true if the urls match, else false

munge()

Replace all non alpha numeric characters and spaces with the replacement character.


    public
            static        munge(string $name[, string $char = '_' ][, int $len = 63 ]) : string

Parameters

$name : string: The name to be worked on.
$char : string = '_': The character to use for non-valid chars.
$len : int = 63: Length of valid variables.

Return values

string —

returns the manipulated string

parseOneOffStringThroughSmarty()

Parse a string through smarty without creating a smarty template file per string.


    public
            static        parseOneOffStringThroughSmarty(string $templateString[, array<string|int, mixed> $templateVars = [] ]) : string

This function is for swapping out any smarty tokens that appear in a string and are not re-used much if at all. For example parsing a contact's greeting does not need to be cached are there are some minor security / data privacy benefits to not caching them per file. We also save disk space, reduce I/O and disk clearing time.

Doing this is cleaning in Smarty3 which we are alas not using https://www.smarty.net/docs/en/resources.string.tpl

However, it highlights that smarty-eval is not evil-eval and still have the security applied.

In order to replicate that in Smarty2 I'm using {eval} per https://www.smarty.net/docsv2/en/language.function.eval.tpl#id2820446 From the above:

Evaluated variables are treated the same as templates. They follow the same escapement and security features just as if they were templates.
Evaluated variables are compiled on every invocation, the compiled versions are not saved! However if you have caching enabled, the output will be cached with the rest of the template.

Our set up does not have caching enabled and my testing suggests this still works fine with it enabled so turning it off before running this is out of caution based on the above.

When this function is run only one template file is created (for the eval) tag no matter how many times it is run. This compares to it otherwise creating one file for every parsed string.

Parameters

$templateString : string
$templateVars : array<string|int, mixed> = []

Return values

string

parsePrefix()

Examples: "admin foo" => array(NULL,"admin foo") "cms:admin foo" => array("cms", "admin foo")


    public
            static        parsePrefix(string $delim, string $string[, string|null $defaultPrefix = NULL ][, string $validPrefixPattern = '/^[A-Za-z0-9]+$/' ]) : array<string|int, mixed>

Parameters

$delim : string
$string : string: E.g. "view all contacts". Syntax: "[prefix:]name".
$defaultPrefix : string|null = NULL
$validPrefixPattern : string = '/^[A-Za-z0-9]+$/': A regular expression used to determine if a prefix is valid. To wit: Prefixes MUST be strictly alphanumeric.

Return values

array<string|int, mixed> —

(0 => string|NULL $prefix, 1 => string $value)

pluralize()

Returns the plural form of an English word.


    public
            static        pluralize(string $str) : string

Parameters

$str : string

Return values

string

purifyHTML()

Use HTMLPurifier to clean up a text string and remove any potential xss attacks. This is primarily used in public facing pages which accept html as the input string


    public
            static        purifyHTML(string $string) : string

Parameters

$string : string: The input string.

Return values

string —

the cleaned up string

redaction()


    public
            static        redaction(mixed $str, mixed $stringRules) : mixed

Parameters

$str : mixed
$stringRules : mixed

regex()

Determine the string replacements for redaction.


    public
            static        regex(string $str, array<string|int, mixed> $regexRules) : array<string|int, mixed>

on the basis of the regular expressions

Parameters

$str : string: Input string.
$regexRules : array<string|int, mixed>: Regular expression to be matched w/ replacements.

Return values

array<string|int, mixed> —

array of strings w/ corresponding redacted outputs

rename()

Takes a variable name and munges it randomly into another variable name.


    public
            static        rename(string $name[, int $len = 4 ]) : string

Parameters

$name : string: Initial Variable Name.
$len : int = 4: Length of valid variables.

Return values

string —

Randomized Variable Name

simpleParseUrl()

A simplified version of PHP's parse_url() function.


    public
            static        simpleParseUrl(string $url) : array<string|int, mixed>

Parameters

$url : string: e.g. "https://example.com:8000/foo/bar/?id=1#fragment"

Return values

array<string|int, mixed> —

Will always contain keys 'host+port' and 'path+query', even if they're empty strings. Example: [ 'host+port' => "example.com:8000", 'path+query' => "/foo/bar/?id=1", ]

simplifyURL()

When a user supplies a URL (e.g. to an image), we'd like to: - Remove the protocol and domain name if the URL points to the current site.


    public
            static        simplifyURL(string $url[, bool $forceHttps = FALSE ]) : string

Keep the domain name for remote URLs.
Optionally, force remote URLs to use https instead of http (which is useful for images)

Parameters

$url : string: The URL to simplify. Examples: "https://example.org/sites/default/files/coffee-mug.jpg" "sites/default/files/coffee-mug.jpg" "http://i.stack.imgur.com/9jb2ial01b.png"
$forceHttps : bool = FALSE: = FALSE If TRUE, ensure that remote URLs use https. If a URL with http is supplied, then we'll change it to https. This is useful for situations like showing a premium product on a contribution, because (as reported in CRM-14283) if the user gets a browser warning like "page contains insecure elements" on a contribution page, that's a very bad thing. Thus, even if changing http to https breaks the image, that's better than leaving http content in a contribution page.

Return values

string —

The simplified URL. Examples: "/sites/default/files/coffee-mug.jpg" "https://i.stack.imgur.com/9jb2ial01b.png"

startsWith()


    public
            static        startsWith(string $string, string $fragment) : bool

Parameters

$string : string: The long string.
$fragment : string: The fragment to look for.

Return values

bool

stringContainsTokens()

Generic check as to whether any tokens are in the given string.


    public
            static        stringContainsTokens(string $string) : bool

It might be a smarty token OR a CiviCRM token. In both cases the absence of a '{' indicates no token is present.

Parameters

$string : string

Return values

bool

stripAlternatives()

Given an ezComponents-parsed representation of a text with alternatives return only the first one


    public
            static        stripAlternatives(string $full) : string

Parameters

$full : string: All alternatives as a long string (or some other text).

Return values

string —

only the first alternative found (or the text without alternatives)

stripPathChars()

clean the URL 'path' variable that we use to construct CiviCRM urls by removing characters from the path variable


    public
            static        stripPathChars(string $string[, array<string|int, mixed> $search = NULL ][, string $replace = NULL ]) : string

Parameters

$string : string: The input string to be sanitized.
$search : array<string|int, mixed> = NULL: The characters to be sanitized.
$replace : string = NULL: The character to replace it with.

Return values

string —

the sanitized string

stripSpaces()

Strip leading, trailing, double spaces from string used for postal/greeting/addressee


    public
            static        stripSpaces(string $string) : string

Parameters

$string : string: Input string to be cleaned.

Return values

string —

the cleaned string

strtobool()

Translate a true/false/yes/no string to a 0 or 1 value


    public
            static        strtobool(string $str) : bool

Parameters

$str : string: The string to be translated.

Return values

bool

strtoboolstr()

Returns string '1' for a true/yes/1 string, and '0' for no/false/0 else returns false


    public
            static        strtoboolstr(string $str) : string|false

Parameters

$str : string: The string to be translated.

Return values

string|false

titleToVar()

Convert a display name into a potential variable name.


    public
            static        titleToVar(string $title[, int $maxLength = 31 ]) : string

Parameters

$title : string: title of the string
$maxLength : int = 31

Return values

string —

An equivalent variable name.

unserialize()

Safely unserialize a string of scalar or array values (but not objects!)


    public
            static        unserialize(string|null $string) : mixed

Use xkerman/restricted-unserialize to unserialize strings using PHP's serialization format. restricted-unserialize works like PHP's built-in unserialize function except that it does not deserialize object instances, making it immune to PHP Object Injection https://www.owasp.org/index.php/PHP_Object_Injection vulnerabilities.

Note: When dealing with user inputs, it is generally recommended to use safe, standard data interchange formats such as JSON rather than PHP's serialization format when dealing with user input.

Parameters

$string : string|null

unstupifyUrl()

Many parts of the codebase have a convention of internally passing around HTML-encoded URLs. This effectively means that "&" is replaced by "&" (because most other odd characters are %-escaped in URLs; and %-escaped strings don't need any extra escaping in HTML).


    public
            static        unstupifyUrl(string $htmlUrl) : string

Parameters

$htmlUrl : string: URL with HTML entities.

Return values

string —

URL without HTML entities

CRM_Utils_String in package CRM

Table of Contents

Constants

Methods

Constants

ALPHANUMERIC

CARRIAGELINE

CARRIAGERETURN

COMMA

LINECARRIAGE

LINEFEED

SEMICOLON

SPACE

TAB

Methods

append()

Parameters

base64UrlDecode()

Parameters

Tags

Return values

base64UrlEncode()

Parameters

Tags

Return values

compareStr()

Parameters

Return values

convertStringToCamel()

Parameters

Return values

convertStringToDash()

Parameters

Return values

convertStringToSnakeCase()

Parameters

Return values

createRandom()

Parameters

Return values

ellipsify()

Parameters

Return values

endsWith()

Parameters

Return values

extractName()

Parameters

extractURLVarValue()

Parameters

Return values

filterByWildcards()

Parameters

Return values

getClassName()

Parameters

Return values

htmlAttributes()

Parameters

Return values

htmlToText()

Parameters

Return values

isAscii()

Parameters

Return values

isUtf8()

Parameters

Return values

makeArray()

Parameters

Return values

maskEmail()

Parameters

Return values

match()

Parameters

Return values

munge()

Parameters

CRM_Utils_String
in package

CRM