Class Text

Text handling methods.

Namespace: Cake\Utility
Location: Utility/Text.php

Properties summary

$_defaultHtmlNoCount protected static

array

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

Transliterator

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.
stripLinks() public static deprecated

Strips given text of all links (<a href=....).
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 )

Removes the last word from the input text.

Parameters

string $text: The input text

Returns

string

_strlen() protected static ¶

_strlen( string $text , array $options )

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

integer

_substr() protected static ¶

_substr( string $text , integer $start , integer $length , array $options )

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.
integer $start: The position to begin extracting.
integer $length: The desired length.
array $options: An array of options.

Returns

string

_wordWrap() protected static ¶

_wordWrap( string $text , integer $width = 72 , string $break = "\n" , boolean $cut = false )

Unicode aware version of wordwrap as helper method.

Parameters

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

Returns

string
Formatted text.

ascii() public static ¶

ascii( array $array )

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 )

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

See

\Cake\Utility\Text::insert()

excerpt() public static ¶

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

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
integer $radius optional 100: 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
Modified string

Link

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

getTransliterator() public static ¶

getTransliterator( )

Get the default transliterator.

Returns

Transliterator|null

Either a Transliterator instance, or null in case no transliterator has been set yet.

Since

3.7.0

getTransliteratorId() public static ¶

getTransliteratorId( )

Get default transliterator identifier string.

Returns

string
Transliterator identifier.

highlight() public static ¶

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

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
The highlighted text

Link

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

insert() public static ¶

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

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 )

Check if the string contain multibyte characters

Parameters

string $string: value to test

Returns

boolean

parseFileSize() public static ¶

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

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 false: Value to be returned when invalid size was used, for example 'Unknown type'

Returns

mixed
Number of bytes as integer on success, $default on failure if not false

Throws

InvalidArgumentException
On invalid Unit type.

Link

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

setTransliterator() public static ¶

setTransliterator( Transliterator $transliterator )

Set the default transliterator.

Parameters

Transliterator $transliterator: A Transliterator instance.

Since

3.7.0

setTransliteratorId() public static ¶

setTransliteratorId( string $transliteratorId )

Set default transliterator identifier string.

Parameters

string $transliteratorId: Transliterator identifier.

slug() public static ¶

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

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 $options optional []: If string it will be use as replacement character or an array of options.

Returns

string

See

Cake\Utility\Text::setTransliterator()
Cake\Utility\Text::setTransliteratorId()

stripLinks() public static deprecated ¶

stripLinks( string $text )

Strips given text of all links (<a href=....).

Warning This method is not an robust solution in preventing XSS or malicious HTML.

Deprecated

3.2.12 This method will be removed in 4.0.0

Parameters

string $text: Text

Returns

string
The text without links

tail() public static ¶

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

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.
integer $length optional 100: Length of returned string, including ellipsis.
array $options optional []: An array of options.

Returns

string
Trimmed string.

toList() public static ¶

toList( array $list , string|null $and = null , string $separator = ', ' )

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

Parameters

array $list: The list to be joined.
string|null $and optional null: 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
The glued together string.

Link

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

tokenize() public static ¶

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

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|string[]
Array of tokens in $data or original input if empty.

transliterate() public static ¶

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

Transliterate string.

Parameters

string $string: String to transliterate.
Transliterator|string|null $transliterator optional null: 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

See

https://secure.php.net/manual/en/transliterator.transliterate.php

truncate() public static ¶

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

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.
integer $length optional 100: Length of returned string, including ellipsis.
array $options optional []: An array of HTML attributes and options.

Returns

string
Trimmed string.

Link

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

truncateByWidth() public static ¶

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

Truncate text with specified width.

Parameters

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

Returns

string
Trimmed string.

See

\Cake\Utility\Text::truncate()

utf8() public static ¶

utf8( string $string )

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

Parameters

string $string: String to convert.

Returns

array

uuid() public static ¶

uuid( )

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
RFC 4122 UUID

See

https://www.ietf.org/rfc/rfc4122.txt

Copyright

Matt Farina MIT License https://github.com/lootils/uuid/blob/master/LICENSE

wordWrap() public static ¶

wordWrap( string $text , integer $width = 72 , string $break = "\n" , boolean $cut = false )

Unicode and newline aware version of wordwrap.

Parameters

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

Returns

string
Formatted text.

wrap() public static ¶

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

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|integer $options optional []: Array of options to use, or an integer to wrap the text to.

Returns

string
Formatted text.

wrapBlock() public static ¶

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

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|integer $options optional []: Array of options to use, or an integer to wrap the text to.

Returns

string
Formatted text.

Properties detail

`$_defaultHtmlNoCount` ¶

protected static array

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

[
    'style',
    'script'
]

`$_defaultTransliterator` ¶

protected static Transliterator

Default transliterator.

`$_defaultTransliteratorId` ¶

protected static string

Default transliterator id string.

'Any-Latin; Latin-ASCII; [\u0080-\u7fff] remove'

Namespaces

Classes

Traits

Class Text

Properties 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

stripLinks() public static deprecated

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

excerpt() public static ¶

Parameters

Returns

Link

getTransliterator() public static ¶

Returns

Since

getTransliteratorId() public static ¶

Returns

highlight() public static ¶

Options:

Parameters

Returns

Link

insert() public static ¶

Parameters

Returns

isMultibyte() public static ¶

Parameters

Returns

parseFileSize() public static ¶

Parameters

Returns

Throws

`$_defaultHtmlNoCount` ¶

`$_defaultTransliterator` ¶

`$_defaultTransliteratorId` ¶