Multi Byte Wrappers

This class contains various multi-byte versions of native PHP functions. In order to benefit from these, the mbstring extension must be installed.

Use:
\blobfolio\common\mb (by value)
\blobfolio\common\ref\mb (by reference)

parse_str()

Parse a query string, e.g. "foo=bar&apples=oranges".

Arguments

Type	Description	Notes
string	String.
mixed	Result.	Variable to store output by reference.

Returns

N/A

parse_url()

Break a URL down into its constituent parts. Aside from adding Unicode support, this wrapper will:

• Fix scheme-agnostic URLs like "//domain.com";
• Treat a schemeless host as a host rather than a path;
• Compact IPv6 hosts;
• Punycode conversion of Unicode hosts;

This function requires intl for international/Unicode domain support, and either bcmath or gmp for proper IP address handling.

Note: as with the native parse_url, this function does not fully validate URL hosts.

Arguments

Type	Description	Notes	Default
string	URL.
int	Component.	If provided, a single component is returned. See parse_url() for options.	-1

Returns

Returns an array of the URL parts if $component is omitted, otherwise the component or NULL is returned.

Example

$foo = \blobfolio\common\mb::parse_url('http://☺.com', PHP_URL_HOST); // xn--74h.com

$foo = \blobfolio\common\mb::parse_url('http://☺.com/party-time/');
/*
array(
    scheme => http
    host => xn--74h.com
    path => /party-time/
)
*/

str_split()

Split the characters in a string by the desired length.

Versions

• By Value
• By Reference

Arguments

Type	Description	Default
string	String.
int	Chunk length.	1

Returns

Returns an array of characters by value, TRUE/FALSE by reference.

Example

$foo = 'quEen BjöRk Ⅷ loVes aPplEs.';
\blobfolio\common\mb::str_split($foo, 5);
/*
array(
    0 => quEen
    1 =>  BjöR
    ...
)
*/

strlen()

Count the number of characters in a string.

Arguments

Type	Description
string	String.

Returns

Returns the size of the string as an integer. If mbstring is not installed, the byte size will be returned instead.

str_pad()

Pad a string so it meets a required length.

Versions

• By Value
• By Reference

Arguments

Type	Description	Notes	Default
string	String.
int	Width.
string	Pad string.		" "
int	Pad type.	Either STR_PAD_LEFT, STR_PAD_BOTH, or STR_PAD_RIGHT.	STR_PAD_RIGHT

Returns

Returns the padded string by value or TRUE/FALSE by reference. If the desired width is less than the string or negative, the string will be returned as-was. If the pad string doesn't divide evenly into the pad width, it may be truncated.

Example

$foo = 'quEen BjöRk Ⅷ loVes aPplEs.';
echo \blobfolio\common\mb::str_pad($foo, 50, '<>', STR_PAD_LEFT));
echo \blobfolio\common\mb::str_pad($foo, 50, '<>', STR_PAD_BOTH));
echo \blobfolio\common\mb::str_pad($foo, 50, '<>', STR_PAD_RIGHT));
/*
><><><><><><><><><><><>quEen BjöRk Ⅷ loVes aPplEs.
<><><><><><>quEen BjöRk Ⅷ loVes aPplEs.<><><><><><
quEen BjöRk Ⅷ loVes aPplEs.<><><><><><><><><><><><
*/

strpos()

Find the first occurrence of the needle in the haystack.

Arguments

Type	Description	Default
string	Haystack.
string	Needle.
int	Offset.	0

Returns

Returns the starting position of the needle of FALSE if not found.

strrev()

Reverse a string, e.g. "abc" to "cba".

Versions

• By Value
• By Reference

Arguments

Type	Description
string	String.

Returns

Returns the reversed string by value, otherwise TRUE/FALSE.

strrpos()

Find the last occurrence of the needle in the haystack.

Arguments

Type	Description	Default
string	Haystack.
string	Needle.
int	Offset.	0

Returns

Returns the last starting position of the needle of FALSE if not found.

strtolower()

Lowercase a string. This function additionally catches various Unicode characters with upper/lower variants that mbstring doesn't bother checking for.

Versions

• By Value
• By Reference

Arguments

Type	Description	Notes	Default
string, array	String.	If an array is passed, each value will be processed recursively.
bool	Strict.	If TRUE, non-string types will be ignored, otherwise they'll be typecast to strings.	FALSE

Returns

If passing by value, the lowercased string is returned, otherwise TRUE.

Example

$foo = 'quEen BjöRk Ⅷ loVes aPplEs.';
echo \blobfolio\common\mb::strtolower($foo); // queen björk ⅷ loves apples.

strtoupper()

Uppercase a string. This function additionally catches various Unicode characters with upper/lower variants that mbstring doesn't bother checking for.

Versions

• By Value
• By Reference

Arguments

Type	Description	Notes	Default
string, array	String.	If an array is passed, each value will be processed recursively.
bool	Strict.	If TRUE, non-string types will be ignored, otherwise they'll be typecast to strings.	FALSE

Returns

If passing by value, the uppercased string is returned, otherwise TRUE.

Example

$foo = 'quEen BjöRk Ⅷ loVes aPplEs.';
echo \blobfolio\common\mb::strtoupper($foo); // QUEEN BJÖRK Ⅷ LOVES APPLES.

substr()

Retrieve a portion of the string.

Arguments

Type	Description	Default
string	String.
int	Start.	0
int	Length.	NULL

Returns

Returns the matching substring.

substr_count()

Count the number of occurrences of the needle in the haystack.

Arguments

Type	Description
string	Haystack.
string	Needle.

Returns

Returns the number of matches.

trim()

Actually trim all leading and trailing whitespace from a string.

Versions

• By Value
• By Reference

Arguments

Type	Description	Notes
string, array	String.	If an array is passed, each value will be processed recursively.

Returns

Returns the trimmed string if by value, TRUE otherwise.

ucfirst()

Sentence-case a string. This function additionally catches various Unicode characters with upper/lower variants that mbstring doesn't bother checking for.

Versions

• By Value
• By Reference

Arguments

Type	Description	Notes	Default
string, array	String.	If an array is passed, each value will be processed recursively.
bool	Strict.	If TRUE, non-string types will be ignored, otherwise they'll be typecast to strings.	FALSE

Returns

If passing by value, the sentence-cased string is returned, otherwise TRUE.

Example

$foo = 'quEen BjöRk Ⅷ loVes aPplEs.';
echo \blobfolio\common\mb::ucfirst($foo); // QuEen BjöRk Ⅷ loVes aPplEs.

ucwords()

Title-case a string. This function additionally catches various Unicode characters with upper/lower variants that mbstring doesn't bother checking for, and will also adjust letters following dashes and forward slashes.

Versions

• By Value
• By Reference

Arguments

Type	Description	Notes	Default
string, array	String.	If an array is passed, each value will be processed recursively.
bool	Strict.	If TRUE, non-string types will be ignored, otherwise they'll be typecast to strings.	FALSE

Returns

If passing by value, the title-cased string is returned, otherwise TRUE.

Example

$foo = 'quEen BjöRk Ⅷ loVes aPplEs.';
echo \blobfolio\common\mb::ucwords($foo); // Queen Björk Ⅷ Loves Apples.

wordwrap()

Wrap long lines. Unlike PHP's version, this takes hyphenation and dashes into account when deciding whether to wrap or split a word.

Versions

• By Value
• By Reference

Arguments

Type	Description	Notes	Default
string	String.
int	Line Width.		75
string	EOL.		"\n"
bool	Break words.	If TRUE, words exceeding the line width will be cut, otherwise they'll be inserted as-is, making for an extra long line.	FALSE

Returns

Returns the wrapped string by value, TRUE/FALSE by reference.

Example

$foo = "Björk's dress is attention-getting.";
\blobfolio\common\mb::wordwrap($foo, 15);
/*
Björk's dress
is attention-
getting.
*/

// By comparison, the PHP's native function does not try to split on hyphens.
wordwrap($foo, 15);
/*
Björk's dress
is
attention-getting.
*/