Class TextHelper

Text helper library.

Text manipulations: Highlight, excerpt, truncate, strip of links, convert email addresses to mailto: links...

Namespace: Cake\View\Helper

Properties summary

  • $Html public
    \Cake\View\Helper\HtmlHelper
  • $_View protected
    \Cake\View\View

    The View instance this helper is attached to

  • $_config protected
    array

    Runtime config

  • $_configInitialized protected
    bool

    Whether the config property has already been configured with defaults

  • $_defaultConfig protected
    array

    Default config for this class

  • $_engine protected
    \Cake\Utility\Text

    Cake Utility Text instance

  • $_helperMap protected
    array

    A helper lookup table used to lazy load helper objects.

  • $_placeholders protected
    array

    An array of hashes and their contents.

  • $helpers public
    array

    helpers

Method Summary

  • __call() public

    Call methods from String utility class

  • __construct() public

    Constructor

  • __debugInfo() public

    Returns an array that can be used to describe the internal state of this object.

  • __get() public

    Lazy loads helpers.

  • _configDelete() protected

    Deletes a single config key.

  • _configRead() protected

    Reads a config key.

  • _configWrite() protected

    Writes a config key.

  • _confirm() protected

    Returns a string to be used as onclick handler for confirm dialogs.

  • _insertPlaceHolder() protected

    Saves the placeholder for a string, for later use. This gets around double escaping content in URL's.

  • _linkEmails() protected

    Links email addresses

  • _linkUrls() protected

    Replace placeholders with links.

  • addClass() public

    Adds the given class to the element options

  • autoLink() public

    Convert all links and email addresses to HTML links.

  • autoLinkEmails() public

    Adds email links (<a href="mailto:....) to a given text.

  • autoLinkUrls() public

    Adds links (<a href=....) to a given text, by finding text that begins with strings like http:// and ftp://.

  • autoParagraph() public

    Formats paragraphs around given text for all line breaks
    added for single line return

    added for double line return

  • configShallow() public

    Merge provided config with existing config. Unlike config() which does a recursive merge for nested keys, this method does a simple merge.

  • excerpt() public

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

  • getConfig() public

    Returns the config.

  • getConfigOrFail() public

    Returns the config for this specific key.

  • getView() public

    Get the view instance this helper is bound to.

  • highlight() public

    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.

  • implementedEvents() public

    Event listeners.

  • initialize() public

    Constructor hook method.

  • setConfig() public

    Sets the config.

  • slug() public

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

  • tail() public

    Truncates text starting from the end.

  • toList() public

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

  • truncate() public

    Truncates text.

Method Detail

__call() public 

__call(string $method, array $params)

Call methods from String utility class

Parameters

string $method

Method to invoke

array $params

Array of params for the method.

Returns

mixed

Whatever is returned by called method, or false on failure

__construct() public 

__construct(\Cake\View\View $view, array $config)

Constructor

Settings:

  • engine Class name to use to replace String functionality. The class needs to be placed in the Utility directory.

Parameters

\Cake\View\View $view

the view object the helper is attached to.

array $config optional

Settings array Settings array

Throws

Cake\Core\Exception\Exception
when the engine class could not be found.

__debugInfo() public 

__debugInfo()

Returns an array that can be used to describe the internal state of this object.

Returns

array

__get() public 

__get(string $name)

Lazy loads helpers.

Parameters

string $name

Name of the property being accessed.

Returns

\Cake\View\Helper|null|void

Helper instance if helper with provided name exists

_configDelete() protected 

_configDelete(string $key)

Deletes a single config key.

Parameters

string $key

Key to delete.

Throws

Cake\Core\Exception\Exception
if attempting to clobber existing config

_configRead() protected 

_configRead(?string $key)

Reads a config key.

Parameters

string|null $key

Key to read.

Returns

mixed

_configWrite() protected 

_configWrite(mixed $key, mixed $value, mixed $merge)

Writes a config key.

Parameters

string|array $key

Key to write to.

mixed $value

Value to write.

bool|string $merge optional

True to merge recursively, 'shallow' for simple merge, false to overwrite, defaults to false.

Throws

Cake\Core\Exception\Exception
if attempting to clobber existing config

_confirm() protected 

_confirm(string $okCode, string $cancelCode)

Returns a string to be used as onclick handler for confirm dialogs.

Parameters

string $okCode

Code to be executed after user chose 'OK'

string $cancelCode

Code to be executed after user chose 'Cancel'

Returns

string

"onclick" JS code

_insertPlaceHolder() protected 

_insertPlaceHolder(array $matches)

Saves the placeholder for a string, for later use. This gets around double escaping content in URL's.

Parameters

array $matches

An array of regexp matches.

Returns

string

Replaced values.

_linkEmails() protected 

_linkEmails(string $text, array $options)

Links email addresses

Parameters

string $text

The text to operate on

array $options

An array of options to use for the HTML.

Returns

string

See Also

\Cake\View\Helper\TextHelper::autoLinkEmails()

_linkUrls() protected 

_linkUrls(string $text, array $htmlOptions)

Replace placeholders with links.

Parameters

string $text

The text to operate on.

array $htmlOptions

The options for the generated links.

Returns

string

The text with links inserted.

addClass() public 

addClass(array $options, string $class, string $key)

Adds the given class to the element options

Parameters

array $options

Array options/attributes to add a class to

string $class

The class name being added.

string $key optional

the key to use for class. Defaults to 'class'.

Returns

array

Array of options with $key set.

autoLink(string $text, array $options)

Convert all links and email addresses to HTML links.

Options

  • escape Control HTML escaping of input. Defaults to true.

Parameters

string $text

Text

array $options optional

Array of HTML options, and options listed above.

Returns

string

The text with links

Links

https://book.cakephp.org/4/en/views/helpers/text.html#linking-both-urls-and-email-addresses

autoLinkEmails() public 

autoLinkEmails(string $text, array $options)

Adds email links (<a href="mailto:....) to a given text.

Options

  • escape Control HTML escaping of input. Defaults to true.

Parameters

string $text

Text

array $options optional

Array of HTML options, and options listed above.

Returns

string

The text with links

Links

https://book.cakephp.org/4/en/views/helpers/text.html#linking-email-addresses

autoLinkUrls() public 

autoLinkUrls(string $text, array $options)

Adds links (<a href=....) to a given text, by finding text that begins with strings like http:// and ftp://.

Options

  • escape Control HTML escaping of input. Defaults to true.

Parameters

string $text

Text

array $options optional

Array of HTML options, and options listed above.

Returns

string

The text with links

Links

https://book.cakephp.org/4/en/views/helpers/text.html#linking-urls

autoParagraph() public 

autoParagraph(?string $text)

Formats paragraphs around given text for all line breaks
added for single line return

added for double line return

Parameters

string|null $text

Text

Returns

string

The text with proper

and
tags

Links

https://book.cakephp.org/4/en/views/helpers/text.html#converting-text-into-paragraphs

configShallow() public 

configShallow(mixed $key, mixed $value)

Merge provided config with existing config. Unlike config() which does a recursive merge for nested keys, this method does a simple merge.

Setting a specific value:

$this->configShallow('key', $value);

Setting a nested value:

$this->configShallow('some.nested.key', $value);

Updating multiple config settings at the same time:

$this->configShallow(['one' => 'value', 'another' => 'value']);

Parameters

string|array $key

The key to set, or a complete array of configs.

mixed|null $value optional

The value to set.

Returns

$this

excerpt() public 

excerpt(string $text, string $phrase, int $radius, string $ending)

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 $ending optional

Ending that will be appended

Returns

string

Modified string

See Also

\Cake\Utility\Text::excerpt()

Links

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

getConfig() public 

getConfig(?string $key, mixed $default)

Returns the config.

Usage

Reading the whole config:

$this->getConfig();

Reading a specific value:

$this->getConfig('key');

Reading a nested value:

$this->getConfig('some.nested.key');

Reading with default value:

$this->getConfig('some-key', 'default-value');

Parameters

string|null $key optional

The key to get or null for the whole config.

mixed $default optional

The return value when the key does not exist.

Returns

mixed

Configuration data at the named key or null if the key does not exist.

getConfigOrFail() public 

getConfigOrFail(string $key)

Returns the config for this specific key.

The config value for this key must exist, it can never be null.

Parameters

string $key

The key to get.

Returns

mixed

Configuration data at the named key

Throws

InvalidArgumentException

getView() public 

getView()

Get the view instance this helper is bound to.

Returns

\Cake\View\View

The bound view instance.

highlight() public 

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

Parameters

string $text

Text to search the phrase in

string $phrase

The phrase that will be searched

array $options optional

An array of HTML attributes and options.

Returns

string

The highlighted text

See Also

\Cake\Utility\Text::highlight()

Links

https://book.cakephp.org/4/en/views/helpers/text.html#highlighting-substrings

implementedEvents() public 

implementedEvents()

Event listeners.

Returns

array

initialize() public 

initialize(array $config)

Constructor hook method.

Implement this method to avoid having to overwrite the constructor and call parent.

Parameters

array $config

The configuration settings provided to this helper.

setConfig() public 

setConfig(mixed $key, mixed $value, mixed $merge)

Sets the config.

Usage

Setting a specific value:

$this->setConfig('key', $value);

Setting a nested value:

$this->setConfig('some.nested.key', $value);

Updating multiple config settings at the same time:

$this->setConfig(['one' => 'value', 'another' => 'value']);

Parameters

string|array $key

The key to set, or a complete array of configs.

mixed|null $value optional

The value to set.

bool $merge optional

Whether to recursively merge or overwrite existing config, defaults to true.

Returns

$this

Throws

Cake\Core\Exception\Exception
When trying to set a key that is invalid.

slug() public 

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 Text::setTransliteratorId() or Text::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\Text::setTransliterator()

\Cake\Utility\Text::setTransliteratorId()

tail() public 

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 HTML attributes and options.

Returns

string

Trimmed string.

See Also

\Cake\Utility\Text::tail()

Links

https://book.cakephp.org/4/en/views/helpers/text.html#truncating-the-tail-of-a-string

toList() public 

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.

See Also

\Cake\Utility\Text::toList()

Links

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

truncate() public 

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

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

Links

https://book.cakephp.org/4/en/views/helpers/text.html#truncating-text

Property Detail

$Html public

Type

\Cake\View\Helper\HtmlHelper

$_View protected

The View instance this helper is attached to

Type

\Cake\View\View

$_config protected

Runtime config

Type

array

$_configInitialized protected

Whether the config property has already been configured with defaults

Type

bool

$_defaultConfig protected

Default config for this class

Type

array

$_engine protected

Cake Utility Text instance

Type

\Cake\Utility\Text

$_helperMap protected

A helper lookup table used to lazy load helper objects.

Type

array

$_placeholders protected

An array of hashes and their contents.

Used when inserting links into text.

Type

array

$helpers public

helpers

Type

array

© 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.View.Helper.TextHelper.html