W3cubDocs

/CakePHP 4.1

Class Text

Text handling methods.

Namespace: Cake\Utility

Properties summary

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.

  • 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)

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

int

_substr() protected static

_substr(string $text, int $start, ?int $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.

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, string $break, bool $cut)

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

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 Also

\Cake\Utility\Text::insert()

excerpt() public static

excerpt(string $text, string $phrase, int $radius, 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

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

Modified string

Links

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.

getTransliteratorId() public static

getTransliteratorId()

Get default transliterator identifier string.

Returns

string

Transliterator identifier.

highlight() public static

highlight(string $text, mixed $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

Links

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

bool

parseFileSize() public static

parseFileSize(string $size, mixed $default)

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

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

Throws

InvalidArgumentException
On invalid Unit type.

Links

setTransliterator() public static

setTransliterator(\Transliterator $transliterator)

Set the default transliterator.

Parameters

\Transliterator $transliterator

A Transliterator instance.

setTransliteratorId() public static

setTransliteratorId(string $transliteratorId)

Set default transliterator identifier string.

Parameters

string $transliteratorId

Transliterator identifier.

slug() public static

slug(string $string, mixed $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|string $options optional

If string it will be use as replacement character or an array of options.

Returns

string

See Also

\Cake\Utility\setTransliterator()

\Cake\Utility\setTransliteratorId()

tail() public static

tail(string $text, int $length, 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.

int $length optional

Length of returned string, including ellipsis.

array $options optional

An array of options.

Returns

string

Trimmed string.

toList() public static

toList(array $list, ?string $and, string $separator)

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

The glued together string.

Links

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[]

Array of tokens in $data.

transliterate() public static

transliterate(string $string, mixed $transliterator)

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

See Also

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

truncate() public static

truncate(string $text, int $length, 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.

int $length optional

Length of returned string, including ellipsis.

array $options optional

An array of HTML attributes and options.

Returns

string

Trimmed string.

Links

truncateByWidth() public static

truncateByWidth(string $text, int $length, array $options)

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

Trimmed string.

See Also

\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 Also

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

wordWrap() public static

wordWrap(string $text, int $width, string $break, bool $cut)

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

Formatted text.

wrap() public static

wrap(string $text, mixed $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|int $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, mixed $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|int $options optional

Array of options to use, or an integer to wrap the text to.

Returns

string

Formatted text.

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

© 2005–present The Cake Software Foundation, Inc.
Licensed under the MIT License.
CakePHP is a registered trademark of Cake Software Foundation, Inc.
We are not endorsed by or affiliated with CakePHP.
https://api.cakephp.org/4.1/class-Cake.Utility.Text.html