Class Text

Text handling methods.

Namespace: Cake\Utility

Property Summary

$_defaultHtmlNoCount protected static

array

Default html tags who must not be count for truncate text.
$_defaultTransliterator protected static

Transliterator|null

Default transliterator.
$_defaultTransliteratorId protected static

string

Default transliterator id string.

Method Summary

_removeLastWord() protected static

Removes the last word from the input text.
_strlen() protected static

Get string length.
_substr() protected static

Return part of a string.
_wordWrap() protected static

Unicode aware version of wordwrap as helper method.
ascii() public static

Converts the decimal value of a multibyte character string to a string
cleanInsert() public static

Cleans up a Text::insert() formatted string with given $options depending on the 'clean' key in $options. The default method used is text but html is also available. The goal of this function is to replace all whitespace and unneeded markup around placeholders that did not get replaced by Text::insert().
excerpt() public static

Extracts an excerpt from the text surrounding the phrase with a number of characters on each side determined by radius.
getTransliterator() public static

Get the default transliterator.
getTransliteratorId() public static

Get default transliterator identifier string.
highlight() public static

Highlights a given phrase in a text. You can specify any expression in highlighter that may include the \1 expression to include the $phrase found.
insert() public static
Replaces variable placeholders inside a $str with any given $data. Each key in the $data array corresponds to a variable placeholder name in $str. Example:
```
Text::insert(':name is :age years old.', ['name' => 'Bob', 'age' => '65']);
```
Returns: Bob is 65 years old.
isMultibyte() public static

Check if the string contain multibyte characters
parseFileSize() public static

Converts filesize from human readable string to bytes
setTransliterator() public static

Set the default transliterator.
setTransliteratorId() public static

Set default transliterator identifier string.
slug() public static

Returns a string with all spaces converted to dashes (by default), characters transliterated to ASCII characters, and non word characters removed.
tail() public static

Truncates text starting from the end.
toList() public static

Creates a comma separated list where the last two items are joined with 'and', forming natural language.
tokenize() public static

Tokenizes a string using $separator, ignoring any instance of $separator that appears between $leftBound and $rightBound.
transliterate() public static

Transliterate string.
truncate() public static

Truncates text.
truncateByWidth() public static

Truncate text with specified width.
utf8() public static

Converts a multibyte character string to the decimal value of the character
uuid() public static

Generate a random UUID version 4
wordWrap() public static

Unicode and newline aware version of wordwrap.
wrap() public static

Wraps text to a specific width, can optionally wrap at word breaks.
wrapBlock() public static

Wraps a complete block of text to a specific width, can optionally wrap at word breaks.

Method Detail

_removeLastWord() ¶ protected static

_removeLastWord(string $text): string

Removes the last word from the input text.

Parameters

string $text: The input text

Returns

string

_strlen() ¶ protected static

_strlen(string $text, array $options): int

Get string length.

Options:

html If true, HTML entities will be handled as decoded characters.
trimWidth If true, the width will return.

Parameters

string $text: The string being checked for length
array $options: An array of options.

Returns

int

_substr() ¶ protected static

_substr(string $text, int $start, int|null $length, array $options): string

Return part of a string.

Options:

html If true, HTML entities will be handled as decoded characters.
trimWidth If true, will be truncated with specified width.

Parameters

string $text: The input string.
int $start: The position to begin extracting.
int|null $length: The desired length.
array $options: An array of options.

Returns

string

_wordWrap() ¶ protected static

_wordWrap(string $text, int $width = 72, string $break = "\n", bool $cut = false): string

Unicode aware version of wordwrap as helper method.

Parameters

string $text: The text to format.
int $width optional: The width to wrap to. Defaults to 72.
string $break optional: The line is broken using the optional break parameter. Defaults to '\n'.
bool $cut optional: If the cut is set to true, the string is always wrapped at the specified width.

Returns

string

ascii() ¶ public static

ascii(array $array): string

Converts the decimal value of a multibyte character string to a string

Parameters

array $array: Array

Returns

string

cleanInsert() ¶ public static

cleanInsert(string $str, array $options): string

Cleans up a Text::insert() formatted string with given $options depending on the 'clean' key in $options. The default method used is text but html is also available. The goal of this function is to replace all whitespace and unneeded markup around placeholders that did not get replaced by Text::insert().

Parameters

string $str: String to clean.
array $options: Options list.

Returns

string

excerpt() ¶ public static

excerpt(string $text, string $phrase, int $radius = 100, string $ellipsis = '...'): string

Extracts an excerpt from the text surrounding the phrase with a number of characters on each side determined by radius.

Parameters

string $text: String to search the phrase in
string $phrase: Phrase that will be searched for
int $radius optional: The amount of characters that will be returned on each side of the founded phrase
string $ellipsis optional: Ending that will be appended

Returns

string

Links

https://book.cakephp.org/4/en/core-libraries/text.html#extracting-an-excerpt

getTransliterator() ¶ public static

getTransliterator(): Transliterator|null

Get the default transliterator.

Returns

Transliterator|null

getTransliteratorId() ¶ public static

getTransliteratorId(): string

Get default transliterator identifier string.

Returns

string

highlight() ¶ public static

highlight(string $text, string|array $phrase, array $options = []): string

Highlights a given phrase in a text. You can specify any expression in highlighter that may include the \1 expression to include the $phrase found.

Options:

format The piece of HTML with that the phrase will be highlighted
html If true, will ignore any HTML tags, ensuring that only the correct text is highlighted
regex A custom regex rule that is used to match words, default is '|$tag|iu'
limit A limit, optional, defaults to -1 (none)

Parameters

string $text: Text to search the phrase in.
string|array $phrase: The phrase or phrases that will be searched.
array $options optional: An array of HTML attributes and options.

Returns

string

Links

https://book.cakephp.org/4/en/core-libraries/text.html#highlighting-substrings

insert() ¶ public static

insert(string $str, array $data, array $options = []): string

Replaces variable placeholders inside a $str with any given $data. Each key in the $data array corresponds to a variable placeholder name in $str. Example:

Text::insert(':name is :age years old.', ['name' => 'Bob', 'age' => '65']);

Returns: Bob is 65 years old.

Available $options are:

before: The character or string in front of the name of the variable placeholder (Defaults to :)
after: The character or string after the name of the variable placeholder (Defaults to null)
escape: The character or string used to escape the before character / string (Defaults to \)
format: A regex to use for matching variable placeholders. Default is: /(?<!\\)\:%s/ (Overwrites before, after, breaks escape / clean)
clean: A boolean or array with instructions for Text::cleanInsert

Parameters

string $str: A string containing variable placeholders
array $data: A key => val array where each key stands for a placeholder variable name to be replaced with val
array $options optional: An array of options, see description above

Returns

string

isMultibyte() ¶ public static

isMultibyte(string $string): bool

Check if the string contain multibyte characters

Parameters

string $string: value to test

Returns

bool

parseFileSize() ¶ public static

parseFileSize(string $size, mixed $default = false): mixed

Converts filesize from human readable string to bytes

Parameters

string $size: Size in human readable string like '5MB', '5M', '500B', '50kb' etc.
mixed $default optional: Value to be returned when invalid size was used, for example 'Unknown type'

Returns

mixed

Throws

InvalidArgumentException
On invalid Unit type.

Links

https://book.cakephp.org/4/en/core-libraries/text.html#Cake\Utility\Text::parseFileSize

setTransliterator() ¶ public static

setTransliterator(Transliterator $transliterator): void

Set the default transliterator.

Parameters

Transliterator $transliterator: A Transliterator instance.

Returns

void

setTransliteratorId() ¶ public static

setTransliteratorId(string $transliteratorId): void

Set default transliterator identifier string.

Parameters

string $transliteratorId: Transliterator identifier.

Returns

void

slug() ¶ public static

slug(string $string, array|string $options = []): string

Returns a string with all spaces converted to dashes (by default), characters transliterated to ASCII characters, and non word characters removed.

Options:

replacement: Replacement string. Default '-'.
transliteratorId: A valid transliterator id string. If null (default) the transliterator (identifier) set via setTransliteratorId() or setTransliterator() will be used. If false no transliteration will be done, only non words will be removed.
preserve: Specific non-word character to preserve. Default null. For e.g. this option can be set to '.' to generate clean file names.

Parameters

string $string: the string you want to slug
array|string $options optional: If string it will be use as replacement character or an array of options.

Returns

string

tail() ¶ public static

tail(string $text, int $length = 100, array $options = []): string

Truncates text starting from the end.

Cuts a string to the length of $length and replaces the first characters with the ellipsis if the text is longer than length.

Options:

ellipsis Will be used as beginning and prepended to the trimmed string
exact If false, $text will not be cut mid-word

Parameters

string $text: String to truncate.
int $length optional: Length of returned string, including ellipsis.
array $options optional: An array of options.

Returns

string

toList() ¶ public static

toList(string[] $list, string|null $and = null, string $separator = ', '): string

Creates a comma separated list where the last two items are joined with 'and', forming natural language.

Parameters

string[] $list: The list to be joined.
string|null $and optional: The word used to join the last and second last items together with. Defaults to 'and'.
string $separator optional: The separator used to join all the other items together. Defaults to ', '.

Returns

string

Links

https://book.cakephp.org/4/en/core-libraries/text.html#converting-an-array-to-sentence-form

tokenize() ¶ public static

tokenize(string $data, string $separator = ',', string $leftBound = '(', string $rightBound = ')'): string[]

Tokenizes a string using $separator, ignoring any instance of $separator that appears between $leftBound and $rightBound.

Parameters

string $data: The data to tokenize.
string $separator optional: The token to split the data on.
string $leftBound optional: The left boundary to ignore separators in.
string $rightBound optional: The right boundary to ignore separators in.

Returns

string[]

transliterate() ¶ public static

transliterate(string $string, Transliterator|string|null $transliterator = null): string

Transliterate string.

Parameters

string $string: String to transliterate.
Transliterator|string|null $transliterator optional: Either a Transliterator instance, or a transliterator identifier string. If null, the default transliterator (identifier) set via setTransliteratorId() or setTransliterator() will be used.

Returns

string

truncate() ¶ public static

truncate(string $text, int $length = 100, array $options = []): string

Truncates text.

Cuts a string to the length of $length and replaces the last characters with the ellipsis if the text is longer than length.

Options:

ellipsis Will be used as ending and appended to the trimmed string
exact If false, $text will not be cut mid-word
html If true, HTML tags would be handled correctly
trimWidth If true, $text will be truncated with the width

Parameters

string $text: String to truncate.
int $length optional: Length of returned string, including ellipsis.
array $options optional: An array of HTML attributes and options.

Returns

string

Links

https://book.cakephp.org/4/en/core-libraries/text.html#truncating-text

truncateByWidth() ¶ public static

truncateByWidth(string $text, int $length = 100, array $options = []): string

Truncate text with specified width.

Parameters

string $text: String to truncate.
int $length optional: Length of returned string, including ellipsis.
array $options optional: An array of HTML attributes and options.

Returns

string

utf8() ¶ public static

utf8(string $string): array

Converts a multibyte character string to the decimal value of the character

Parameters

string $string: String to convert.

Returns

array

uuid() ¶ public static

uuid(): string

Generate a random UUID version 4

Warning: This method should not be used as a random seed for any cryptographic operations. Instead you should use the openssl or mcrypt extensions.

It should also not be used to create identifiers that have security implications, such as 'unguessable' URL identifiers. Instead you should use Security::randomBytes() for that.

Returns

string

wordWrap() ¶ public static

wordWrap(string $text, int $width = 72, string $break = "\n", bool $cut = false): string

Unicode and newline aware version of wordwrap.

Parameters

string $text: The text to format.
int $width optional: The width to wrap to. Defaults to 72.
string $break optional: The line is broken using the optional break parameter. Defaults to '\n'.
bool $cut optional: If the cut is set to true, the string is always wrapped at the specified width.

Returns

string

wrap() ¶ public static

wrap(string $text, array|int $options = []): string

Wraps text to a specific width, can optionally wrap at word breaks.

Options

width The width to wrap to. Defaults to 72.
wordWrap Only wrap on words breaks (spaces) Defaults to true.
indent String to indent with. Defaults to null.
indentAt 0 based index to start indenting at. Defaults to 0.

Parameters

string $text: The text to format.
array|int $options optional: Array of options to use, or an integer to wrap the text to.

Returns

string

wrapBlock() ¶ public static

wrapBlock(string $text, array|int $options = []): string

Wraps a complete block of text to a specific width, can optionally wrap at word breaks.

Options

width The width to wrap to. Defaults to 72.
wordWrap Only wrap on words breaks (spaces) Defaults to true.
indent String to indent with. Defaults to null.
indentAt 0 based index to start indenting at. Defaults to 0.

Parameters

string $text: The text to format.
array|int $options optional: Array of options to use, or an integer to wrap the text to.

Returns

string

Property Detail

`$_defaultHtmlNoCount` ¶ protected static

Default html tags who must not be count for truncate text.

Type

array

`$_defaultTransliterator` ¶ protected static

Default transliterator.

Type

Transliterator|null

`$_defaultTransliteratorId` ¶ protected static

Default transliterator id string.

Type

string

Namespaces

Class Text

Property Summary

Method Summary

_removeLastWord() protected static

_strlen() protected static

_substr() protected static

_wordWrap() protected static

ascii() public static

cleanInsert() public static

excerpt() public static

getTransliterator() public static

getTransliteratorId() public static

highlight() public static

insert() public static

isMultibyte() public static

parseFileSize() public static

setTransliterator() public static

setTransliteratorId() public static

slug() public static

tail() public static

toList() public static

tokenize() public static

transliterate() public static

truncate() public static

truncateByWidth() public static

utf8() public static

uuid() public static

wordWrap() public static

wrap() public static

wrapBlock() public static

Method Detail

_removeLastWord() ¶ protected static

Parameters

Returns

_strlen() ¶ protected static

Options:

Parameters

Returns

_substr() ¶ protected static

Options:

Parameters

Returns

_wordWrap() ¶ protected static

Parameters

Returns

ascii() ¶ public static

Parameters

Returns

cleanInsert() ¶ public static

Parameters

Returns

See Also

excerpt() ¶ public static

Parameters

Returns

Links

getTransliterator() ¶ public static

Returns

getTransliteratorId() ¶ public static

Returns

highlight() ¶ public static

Options:

Parameters

Returns

Links

insert() ¶ public static

Parameters

Returns

isMultibyte() ¶ public static

Parameters

Returns

parseFileSize() ¶ public static

Parameters

Returns

Throws

Links

setTransliterator() ¶ public static

Parameters

Returns

`$_defaultHtmlNoCount` ¶ protected static

`$_defaultTransliterator` ¶ protected static

`$_defaultTransliteratorId` ¶ protected static