Class TextHelper

Text helper library.

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

Namespace: Cake\View\Helper
See: \Cake\Utility\Text
Link: https://book.cakephp.org/4/en/views/helpers/text.html

Property Summary

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

    The View instance this helper is attached to

  • $_config protected
    array<string, mixed>

    Runtime config

  • $_configInitialized protected
    bool

    Whether the config property has already been configured with defaults

  • $_defaultConfig protected
    array<string, mixed>

    Default config for this class

  • $_engine protected
    Cake\Utility\Text

    Cake Utility Text instance

  • $_helperMap protected
    array<string, array>

    A helper lookup table used to lazy load helper objects.

  • $_placeholders protected
    array<string, array>

    An array of hashes and their contents. Used when inserting links into text.

  • $helpers protected
    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): mixed

Call methods from String utility class

Parameters

string $method

Method to invoke

array $params

Array of params for the method.

Returns

mixed

__construct() public 

__construct(Cake\View\View $view, array<string, mixed> $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<string, mixed> $config optional

Settings array Settings array

Throws

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

__debugInfo() public 

__debugInfo(): array<string, mixed>

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

Returns

array<string, mixed>

__get() public 

__get(string $name): Cake\View\Helper|null|void

Lazy loads helpers.

Parameters

string $name

Name of the property being accessed.

Returns

Cake\View\Helper|null|void

_configDelete() protected 

_configDelete(string $key): void

Deletes a single config key.

Parameters

string $key

Key to delete.

Returns

void

Throws

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

_configRead() protected 

_configRead(string|null $key): mixed

Reads a config key.

Parameters

string|null $key

Key to read.

Returns

mixed

_configWrite() protected 

_configWrite(array<string, mixed>|string $key, mixed $value, string|bool $merge = false): void

Writes a config key.

Parameters

array<string, mixed>|string $key

Key to write to.

mixed $value

Value to write.

string|bool $merge optional

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

Returns

void

Throws

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

_confirm() protected 

_confirm(string $okCode, string $cancelCode): string

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

_insertPlaceHolder() protected 

_insertPlaceHolder(array $matches): string

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

_linkEmails() protected 

_linkEmails(string $text, array<string, mixed> $options): string

Links email addresses

Parameters

string $text

The text to operate on

array<string, mixed> $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<string, mixed> $htmlOptions): string

Replace placeholders with links.

Parameters

string $text

The text to operate on.

array<string, mixed> $htmlOptions

The options for the generated links.

Returns

string

addClass() public 

addClass(array<string, mixed> $options, string $class, string $key = 'class'): array<string, mixed>

Adds the given class to the element options

Parameters

array<string, mixed> $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<string, mixed>

autoLink() public 

autoLink(string $text, array<string, mixed> $options = []): string

Convert all links and email addresses to HTML links.

Options

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

Parameters

string $text

Text

array<string, mixed> $options optional

Array of HTML options, and options listed above.

Returns

string

Links

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

autoLinkEmails() public 

autoLinkEmails(string $text, array<string, mixed> $options = []): string

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

Array of HTML options, and options listed above.

Returns

string

Links

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

autoLinkUrls() public 

autoLinkUrls(string $text, array<string, mixed> $options = []): string

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

Array of HTML options, and options listed above.

Returns

string

Links

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

autoParagraph() public 

autoParagraph(string|null $text): string

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

Links

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

configShallow() public 

configShallow(array<string, mixed>|string $key, mixed|null $value = null): $this

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

array<string, mixed>|string $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 = 100, string $ending = '...'): 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 $ending optional

Ending that will be appended

Returns

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|null $key = null, mixed $default = null): mixed

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

getConfigOrFail() public 

getConfigOrFail(string $key): mixed

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

Throws

InvalidArgumentException

getView() public 

getView(): Cake\View\View

Get the view instance this helper is bound to.

Returns

Cake\View\View

highlight() public 

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

Parameters

string $text

Text to search the phrase in

string $phrase

The phrase that will be searched

array<string, mixed> $options optional

An array of HTML attributes and options.

Returns

string

See Also

\Cake\Utility\Text::highlight()

Links

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

implementedEvents() public 

implementedEvents(): array<string, mixed>

Event listeners.

By defining one of the callback methods a helper is assumed to be interested in the related event.

Override this method if you need to add non-conventional event listeners. Or if you want helpers to listen to non-standard events.

Returns

array<string, mixed>

initialize() public 

initialize(array<string, mixed> $config): void

Constructor hook method.

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

Parameters

array<string, mixed> $config

The configuration settings provided to this helper.

Returns

void

setConfig() public 

setConfig(array<string, mixed>|string $key, mixed|null $value = null, bool $merge = true): $this

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

array<string, mixed>|string $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\CakeException
When trying to set a key that is invalid.

slug() public 

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

If string it will be used 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 = 100, array<string, mixed> $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<string, mixed> $options optional

An array of HTML attributes and options.

Returns

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

array<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

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 = 100, array<string, mixed> $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

Parameters

string $text

String to truncate.

int $length optional

Length of returned string, including ellipsis.

array<string, mixed> $options optional

An array of HTML attributes and options.

Returns

string

See Also

\Cake\Utility\Text::truncate()

Links

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

Property Detail

$Html public @property

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<string, mixed>

$_configInitialized protected

Whether the config property has already been configured with defaults

Type

bool

$_defaultConfig protected

Default config for this class

Type

array<string, mixed>

$_engine protected

Cake Utility Text instance

Type

Cake\Utility\Text

$_helperMap protected

A helper lookup table used to lazy load helper objects.

Type

array<string, array>

$_placeholders protected

An array of hashes and their contents. Used when inserting links into text.

Type

array<string, array>

$helpers protected

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.4/class-Cake.View.Helper.TextHelper.html