Fr3nch13/CakePHP Utilities

Text
in package

Application

Text handling methods.

Properties

$_defaultHtmlNoCount : array<string|int, string>: Default HTML tags which must not be counted for truncating text.
$_defaultTransliterator : Transliterator|null: Default transliterator.
$_defaultTransliteratorId : string: Default transliterator id string.

Methods

ascii() : string: Converts the decimal value of a multibyte character string to a string
cleanInsert() : 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().
excerpt() : string: Extracts an excerpt from the text surrounding the phrase with a number of characters on each side determined by radius.
getTransliterator() : Transliterator|null: Get the default transliterator.
getTransliteratorId() : string: Get default transliterator identifier string.
highlight() : 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.
insert() : 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.
isMultibyte() : bool: Check if the string contain multibyte characters
parseFileSize() : mixed: Converts filesize from human readable string to bytes
setTransliterator() : void: Set the default transliterator.
setTransliteratorId() : void: Set default transliterator identifier string.
slug() : string: Returns a string with all spaces converted to dashes (by default), characters transliterated to ASCII characters, and non word characters removed.
tail() : string: Truncates text starting from the end.
tokenize() : array<string|int, string>: Tokenizes a string using $separator, ignoring any instance of $separator that appears between $leftBound and $rightBound.
toList() : string: Creates a comma separated list where the last two items are joined with 'and', forming natural language.
transliterate() : string: Transliterate string.
truncate() : string: Truncates text.
truncateByWidth() : string: Truncate text with specified width.
utf8() : array<string|int, int>: Converts a multibyte character string to the decimal value of the character
uuid() : string: Generate a random UUID version 4
wordWrap() : string: Unicode and newline aware version of wordwrap.
wrap() : string: Wraps text to a specific width, can optionally wrap at word breaks.
wrapBlock() : string: Wraps a complete block of text to a specific width, can optionally wrap at word breaks.
_removeLastWord() : string: Removes the last word from the input text.
_strlen() : int: Get string length.
_substr() : string: Return part of a string.
_wordWrap() : string: Unicode aware version of wordwrap as helper method.

$_defaultHtmlNoCount

Default HTML tags which must not be counted for truncating text.


    protected
    static    array<string|int, string>
    $_defaultHtmlNoCount
     = ['style', 'script']

$_defaultTransliterator

Default transliterator.


    protected
    static    Transliterator|null
    $_defaultTransliterator

Transliterator instance.

$_defaultTransliteratorId

Default transliterator id string.


    protected
    static    string
    $_defaultTransliteratorId
     = 'Any-Latin; Latin-ASCII; [\u0080-\u7fff] remove'

Transliterator identifier string.

ascii()

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


    public
            static        ascii(array<string|int, mixed> $array) : string

Parameters

$array : array<string|int, mixed>: Array

Return values

string

cleanInsert()

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().


    public
            static        cleanInsert(string $str, array<string, mixed> $options) : string

Parameters

$str : string: String to clean.
$options : array<string, mixed>: Options list.

Return values

string

excerpt()

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


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

Parameters

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

Return values

string —

Modified string

getTransliterator()

Get the default transliterator.


    public
            static        getTransliterator() : Transliterator|null

Return values

Transliterator|null —

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

getTransliteratorId()

Get default transliterator identifier string.


    public
            static        getTransliteratorId() : string

Return values

string —

Transliterator identifier.

highlight()

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.


    public
            static        highlight(string $text, array<string|int, string>|string $phrase[, array<string, mixed> $options = [] ]) : string

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

$text : string: Text to search the phrase in.
$phrase : array<string|int, string>|string: The phrase or phrases that will be searched.
$options : array<string, mixed> = []: An array of HTML attributes and options.

Return values

string —

The highlighted text

insert()

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


    public
            static        insert(string $str, array<string|int, mixed> $data[, array<string, mixed> $options = [] ]) : string

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

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

Return values

string

isMultibyte()

Check if the string contain multibyte characters


    public
            static        isMultibyte(string $string) : bool

Parameters

$string : string: value to test

Return values

bool

parseFileSize()

Converts filesize from human readable string to bytes


    public
            static        parseFileSize(string $size[, mixed $default = false ]) : mixed

Parameters

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

Return values

mixed —

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

setTransliterator()

Set the default transliterator.


    public
            static        setTransliterator(Transliterator $transliterator) : void

Parameters

$transliterator : Transliterator: A Transliterator instance.

setTransliteratorId()

Set default transliterator identifier string.


    public
            static        setTransliteratorId(string $transliteratorId) : void

Parameters

$transliteratorId : string: Transliterator identifier.

slug()

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


    public
            static        slug(string $string[, array<string, mixed>|string $options = [] ]) : string

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

Return values

string

tail()

Truncates text starting from the end.


    public
            static        tail(string $text[, int $length = 100 ][, array<string, mixed> $options = [] ]) : string

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

$text : string: String to truncate.
$length : int = 100: Length of returned string, including ellipsis.
$options : array<string, mixed> = []: An array of options.

Return values

string —

Trimmed string.

tokenize()

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


    public
            static        tokenize(string $data[, string $separator = ',' ][, string $leftBound = '(' ][, string $rightBound = ')' ]) : array<string|int, string>

Parameters

$data : string: The data to tokenize.
$separator : string = ',': The token to split the data on.
$leftBound : string = '(': The left boundary to ignore separators in.
$rightBound : string = ')': The right boundary to ignore separators in.

Return values

array<string|int, string> —

Array of tokens in $data.

toList()

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


    public
            static        toList(array<string|int, string> $list[, string|null $and = null ][, string $separator = ', ' ]) : string

Parameters

$list : array<string|int, string>: The list to be joined.
$and : string|null = null: The word used to join the last and second last items together with. Defaults to 'and'.
$separator : string = ', ': The separator used to join all the other items together. Defaults to ', '.

Return values

string —

The glued together string.

transliterate()

Transliterate string.


    public
            static        transliterate(string $string[, Transliterator|string|null $transliterator = null ]) : string

Parameters

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

Return values

string

truncate()

Truncates text.


    public
            static        truncate(string $text[, int $length = 100 ][, array<string, mixed> $options = [] ]) : string

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

$text : string: String to truncate.
$length : int = 100: Length of returned string, including ellipsis.
$options : array<string, mixed> = []: An array of HTML attributes and options.

Return values

string —

Trimmed string.

truncateByWidth()

Truncate text with specified width.


    public
            static        truncateByWidth(string $text[, int $length = 100 ][, array<string, mixed> $options = [] ]) : string

Parameters

$text : string: String to truncate.
$length : int = 100: Length of returned string, including ellipsis.
$options : array<string, mixed> = []: An array of HTML attributes and options.

Return values

string —

Trimmed string.

utf8()

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


    public
            static        utf8(string $string) : array<string|int, int>

Parameters

$string : string: String to convert.

Return values

array<string|int, int>

uuid()

Generate a random UUID version 4


    public
            static        uuid() : string

Warning: This method should not be used as a random seed for any cryptographic operations. Instead, you should use Security::randomBytes() or Security::randomString() instead.

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

Return values

string —

RFC 4122 UUID

wordWrap()

Unicode and newline aware version of wordwrap.


    public
            static        wordWrap(string $text[, int $width = 72 ][, string $break = "
" ][, bool $cut = false ]) : string

Parameters

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

Return values

string —

Formatted text.

wrap()

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


    public
            static        wrap(string $text[, array<string, mixed>|int $options = [] ]) : string

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

$text : string: The text to format.
$options : array<string, mixed>|int = []: Array of options to use, or an integer to wrap the text to.

Return values

string —

Formatted text.

wrapBlock()

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


    public
            static        wrapBlock(string $text[, array<string, mixed>|int $options = [] ]) : string

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

$text : string: The text to format.
$options : array<string, mixed>|int = []: Array of options to use, or an integer to wrap the text to.

Return values

string —

Formatted text.

_removeLastWord()

Removes the last word from the input text.


    protected
            static        _removeLastWord(string $text) : string

Parameters

$text : string: The input text

Return values

string

_strlen()

Get string length.


    protected
            static        _strlen(string $text, array<string, mixed> $options) : int

Options:

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

Parameters

$text : string: The string being checked for length
$options : array<string, mixed>: An array of options.

Return values

int

_substr()

Return part of a string.


    protected
            static        _substr(string $text, int $start, int|null $length, array<string, mixed> $options) : string

Options:

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

Parameters

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

Return values

string

_wordWrap()

Unicode aware version of wordwrap as helper method.


    protected
            static        _wordWrap(string $text[, int $width = 72 ][, string $break = "
" ][, bool $cut = false ]) : string

Parameters

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

Return values

string —

Formatted text.

Text in package Application

Table of Contents

Properties

Methods

Properties

$_defaultHtmlNoCount

$_defaultTransliterator

$_defaultTransliteratorId

Methods

ascii()

Parameters

Return values

cleanInsert()

Parameters

Tags

Return values

excerpt()

Parameters

Tags

Return values

getTransliterator()

Return values

getTransliteratorId()

Return values

highlight()

Options:

Parameters

Tags

Return values

insert()

Parameters

Return values

isMultibyte()

Parameters

Return values

parseFileSize()

Parameters

Tags

Return values

setTransliterator()

Parameters

setTransliteratorId()

Parameters

slug()

Options:

Parameters

Tags

Return values

tail()

Options:

Parameters

Return values

tokenize()

Parameters

Return values

toList()

Parameters

Tags

Return values

transliterate()

Parameters

Tags

Return values

truncate()

Options:

Parameters

Tags

Return values

truncateByWidth()

Parameters

Tags

Return values

utf8()

Parameters

Return values

uuid()

Tags

Return values

wordWrap()

Parameters

Text
in package

Application