StringHelper

String handling class for UTF-8 data wrapping the phputf8 library. All functions assume the validity of UTF-8 strings.

abstract
since

1.3.0

Methods

compliant

Tests whether a string complies as UTF-8.

compliant(string $str) : boolean
static

This will be much faster than StringHelper::valid() but will pass five and six octet UTF-8 sequences, which are not supported by Unicode and so cannot be displayed correctly in a browser. In other words it is not as strict as StringHelper::valid() but it's faster. If you use it to validate user input, you place yourself at the risk that attackers will be able to inject 5 and 6 byte sequences (which may or may not be a significant risk, depending on what you are are doing).

see \Joomla\String\StringHelper::valid

http://www.php.net/manual/en/reference.pcre.pattern.modifiers.php#54805

since

1.3.0

Arguments

$str

stringUTF-8 string to check

Response

booleanTRUE if string is valid UTF-8

increment

Increments a trailing number in a string.

increment(string $string, string $style = 'default', integer $n) : string
static

Used to easily create distinct labels when copying objects. The method has the following styles:

default: "Label" becomes "Label (2)" dash: "Label" becomes "Label-2"

since

1.3.0

Arguments

$string

stringThe source string.

$style

stringThe the style (default|dash).

$n

integerIf supplied, this number is used for the copy, otherwise it is the 'next' number.

Response

stringThe incremented string.

is_ascii

Tests whether a string contains only 7bit ASCII bytes.

is_ascii(string $str) : boolean
static

You might use this to conditionally check whether a string needs handling as UTF-8 or not, potentially offering performance benefits by using the native PHP equivalent if it's just ASCII e.g.;

if (StringHelper::is_ascii($someString)) { // It's just ASCII - use the native PHP version $someString = strtolower($someString); } else { $someString = StringHelper::strtolower($someString); }

since

1.3.0

Arguments

$str

stringThe string to test.

Response

booleanTrue if the string is all ASCII

ltrim

UTF-8 aware replacement for ltrim()

ltrim(string $str, string $charlist = false) : string
static

Strip whitespace (or other characters) from the beginning of a string. You only need to use this if you are supplying the charlist optional arg and it contains UTF-8 characters. Otherwise ltrim will work normally on a UTF-8 string.

see

http://www.php.net/ltrim

since

1.3.0

Arguments

$str

stringThe string to be trimmed

$charlist

stringThe optional charlist of additional characters to trim

Response

stringThe trimmed string

ord

UTF-8 aware alternative to ord()

ord(string $chr) : integer
static

Returns the unicode ordinal for a character.

see

http://www.php.net/ord

since

1.4.0

Arguments

$chr

stringUTF-8 encoded character

Response

integerUnicode ordinal for the character

rtrim

UTF-8 aware replacement for rtrim()

rtrim(string $str, string $charlist = false) : string
static

Strip whitespace (or other characters) from the end of a string. You only need to use this if you are supplying the charlist optional arg and it contains UTF-8 characters. Otherwise rtrim will work normally on a UTF-8 string.

see

http://www.php.net/rtrim

since

1.3.0

Arguments

$str

stringThe string to be trimmed

$charlist

stringThe optional charlist of additional characters to trim

Response

stringThe trimmed string

str_ireplace

UTF-8 aware alternative to str_ireplace()

str_ireplace(string $search, string $replace, string $str, integer $count = null) : string
static

Case-insensitive version of str_replace()

see

http://www.php.net/str_ireplace

since

1.3.0

Arguments

$search

stringString to search

$replace

stringExisting string to replace

$str

stringNew string to replace with

$count

integerOptional count value to be passed by referene

Response

stringUTF-8 String

str_pad

UTF-8 aware alternative to str_pad()

str_pad(string $input, integer $length, string $padStr = ' ', integer $type = STR_PAD_RIGHT) : string
static

Pad a string to a certain length with another string. $padStr may contain multi-byte characters.

see

http://www.php.net/str_pad

since

1.4.0

Arguments

$input

stringThe input string.

$length

integerIf the value is negative, less than, or equal to the length of the input string, no padding takes place.

$padStr

stringThe string may be truncated if the number of padding characters can't be evenly divided by the string's length.

$type

integerThe type of padding to apply

Response

string

str_split

UTF-8 aware alternative to str_split()

str_split(string $str, integer $split_len = 1) : array
static

Convert a string to an array.

see

http://www.php.net/str_split

since

1.3.0

Arguments

$str

stringUTF-8 encoded string to process

$split_len

integerNumber to characters to split string by

Response

array

strcasecmp

UTF-8/LOCALE aware alternative to strcasecmp()

strcasecmp(string $str1, string $str2, mixed $locale = false) : integer
static

A case insensitive string comparison.

see

http://www.php.net/strcasecmp

http://www.php.net/strcoll

http://www.php.net/setlocale

since

1.3.0

Arguments

$str1

stringstring 1 to compare

$str2

stringstring 2 to compare

$locale

mixedThe locale used by strcoll or false to use classical comparison

Response

integer< 0 if str1 is less than str2; > 0 if str1 is greater than str2, and 0 if they are equal.

strcmp

UTF-8/LOCALE aware alternative to strcmp()

strcmp(string $str1, string $str2, mixed $locale = false) : integer
static

A case sensitive string comparison.

see

http://www.php.net/strcmp

http://www.php.net/strcoll

http://www.php.net/setlocale

since

1.3.0

Arguments

$str1

stringstring 1 to compare

$str2

stringstring 2 to compare

$locale

mixedThe locale used by strcoll or false to use classical comparison

Response

integer< 0 if str1 is less than str2; > 0 if str1 is greater than str2, and 0 if they are equal.

strcspn

UTF-8 aware alternative to strcspn()

strcspn(string $str, string $mask, integer $start = null, integer $length = null) : integer
static

Find length of initial segment not matching mask.

see

http://www.php.net/strcspn

since

1.3.0

Arguments

$str

stringThe string to process

$mask

stringThe mask

$start

integerOptional starting character position (in characters)

$length

integerOptional length

Response

integerThe length of the initial segment of str1 which does not contain any of the characters in str2

stristr

UTF-8 aware alternative to stristr()

stristr(string $str, string $search) : string
static

Returns all of haystack from the first occurrence of needle to the end. Needle and haystack are examined in a case-insensitive manner to find the first occurrence of a string using case insensitive comparison.

see

http://www.php.net/stristr

since

1.3.0

Arguments

$str

stringThe haystack

$search

stringThe needle

Response

stringthe sub string

strlen

UTF-8 aware alternative to strlen()

strlen(string $str) : integer
static

Returns the number of characters in the string (NOT THE NUMBER OF BYTES).

see

http://www.php.net/strlen

since

1.3.0

Arguments

$str

stringUTF-8 string.

Response

integerNumber of UTF-8 characters in string.

strpos

UTF-8 aware alternative to strpos()

strpos(string $str, string $search, integer $offset = false) : mixed
static

Find position of first occurrence of a string.

see

http://www.php.net/strpos

since

1.3.0

Arguments

$str

stringString being examined

$search

stringString being searched for

$offset

integerOptional, specifies the position from which the search should be performed

Response

mixedNumber of characters before the first match or FALSE on failure

strrev

UTF-8 aware alternative to strrev()

strrev(string $str) : string
static

Reverse a string.

see

http://www.php.net/strrev

since

1.3.0

Arguments

$str

stringString to be reversed

Response

stringThe string in reverse character order

strrpos

UTF-8 aware alternative to strrpos()

strrpos(string $str, string $search, integer $offset) : mixed
static

Finds position of last occurrence of a string.

see

http://www.php.net/strrpos

since

1.3.0

Arguments

$str

stringString being examined.

$search

stringString being searched for.

$offset

integerOffset from the left of the string.

Response

mixedNumber of characters before the last match or false on failure

strspn

UTF-8 aware alternative to strspn()

strspn(string $str, string $mask, integer $start = null, integer $length = null) : integer
static

Find length of initial segment matching mask.

see

http://www.php.net/strspn

since

1.3.0

Arguments

$str

stringThe haystack

$mask

stringThe mask

$start

integerStart optional

$length

integerLength optional

Response

integer

strtolower

UTF-8 aware alternative to strtolower()

strtolower(string $str) : mixed
static

Make a string lowercase

Note: The concept of a characters "case" only exists is some alphabets such as Latin, Greek, Cyrillic, Armenian and archaic Georgian - it does not exist in the Chinese alphabet, for example. See Unicode Standard Annex #21: Case Mappings

see

http://www.php.net/strtolower

since

1.3.0

Arguments

$str

stringString being processed

Response

mixedEither string in lowercase or FALSE is UTF-8 invalid

strtoupper

UTF-8 aware alternative to strtoupper()

strtoupper(string $str) : mixed
static

Make a string uppercase

Note: The concept of a characters "case" only exists is some alphabets such as Latin, Greek, Cyrillic, Armenian and archaic Georgian - it does not exist in the Chinese alphabet, for example. See Unicode Standard Annex #21: Case Mappings

see

http://www.php.net/strtoupper

since

1.3.0

Arguments

$str

stringString being processed

Response

mixedEither string in uppercase or FALSE is UTF-8 invalid

substr

UTF-8 aware alternative to substr()

substr(string $str, integer $offset, integer $length = false) : mixed
static

Return part of a string given character offset (and optionally length).

see

http://www.php.net/substr

since

1.3.0

Arguments

$str

stringString being processed

$offset

integerNumber of UTF-8 characters offset (from left)

$length

integerOptional length in UTF-8 characters from offset

Response

mixedstring or FALSE if failure

substr_replace

UTF-8 aware alternative to substr_replace()

substr_replace(string $str, string $repl, integer $start, integer $length = null) : string
static

Replace text within a portion of a string.

see

http://www.php.net/substr_replace

since

1.3.0

Arguments

$str

stringThe haystack

$repl

stringThe replacement string

$start

integerStart

$length

integerLength (optional)

Response

string

transcode

Transcode a string.

transcode(string $source, string $from_encoding, string $to_encoding) : mixed
static
link

https://bugs.php.net/bug.php?id=48147

since

1.3.0

Arguments

$source

stringThe string to transcode.

$from_encoding

stringThe source encoding.

$to_encoding

stringThe target encoding.

Response

mixedThe transcoded string, or null if the source was not a string.

trim

UTF-8 aware replacement for trim()

trim(string $str, string $charlist = false) : string
static

Strip whitespace (or other characters) from the beginning and end of a string. You only need to use this if you are supplying the charlist optional arg and it contains UTF-8 characters. Otherwise trim will work normally on a UTF-8 string

see

http://www.php.net/trim

since

1.3.0

Arguments

$str

stringThe string to be trimmed

$charlist

stringThe optional charlist of additional characters to trim

Response

stringThe trimmed string

ucfirst

UTF-8 aware alternative to ucfirst()

ucfirst(string $str, string $delimiter = null, string $newDelimiter = null) : string
static

Make a string's first character uppercase or all words' first character uppercase.

see

http://www.php.net/ucfirst

since

1.3.0

Arguments

$str

stringString to be processed

$delimiter

stringThe words delimiter (null means do not split the string)

$newDelimiter

stringThe new words delimiter (null means equal to $delimiter)

Response

stringIf $delimiter is null, return the string with first character as upper case (if applicable) else consider the string of words separated by the delimiter, apply the ucfirst to each words and return the string with the new delimiter

ucwords

UTF-8 aware alternative to ucwords()

ucwords(string $str) : string
static

Uppercase the first character of each word in a string.

see

http://www.php.net/ucwords

since

1.3.0

Arguments

$str

stringString to be processed

Response

stringString with first char of each word uppercase

unicode_to_utf16

Converts Unicode sequences to UTF-16 string.

unicode_to_utf16(string $str) : string
static
since

1.3.0

Arguments

$str

stringUnicode string to convert

Response

stringUTF-16 string

unicode_to_utf8

Converts Unicode sequences to UTF-8 string.

unicode_to_utf8(string $str) : string
static
since

1.3.0

Arguments

$str

stringUnicode string to convert

Response

stringUTF-8 string

valid

Tests a string as to whether it's valid UTF-8 and supported by the Unicode standard.

valid(string $str) : boolean
static

Note: this function has been modified to simple return true or false.

author

hsivonen@iki.fi

see

http://hsivonen.iki.fi/php-utf8/

\Joomla\String\compliant
since

1.3.0

Arguments

$str

stringUTF-8 encoded string.

Response

booleantrue if valid

Properties

incrementStyles

Increment styles.

static
since

1.3.0

Type(s)

array