Class TextHelper

Text helper library.

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

Cake\View\Helper implements Cake\Event\EventListenerInterface uses Cake\Core\InstanceConfigTrait

Cake\View\Helper\TextHelper

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

Properties summary

$_defaultConfig protected

array

Default config for this class
$_engine protected

Cake\Utility\Text

Cake Utility Text instance
$_placeholders protected

array

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

array

helpers

Magic properties summary

$Html public

Cake\View\Helper\HtmlHelper

Inherited Properties

_View, _helperMap, fieldset, tags _config, _configInitialized

Method Summary

__call() public

Call methods from String utility class
__construct() public

Constructor
_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.
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

<

p> added for double line return
excerpt() public

Extracts an excerpt from the text surrounding the phrase with a number of characters on each side determined by radius.
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.
stripLinks() public

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

Overrides

Cake\View\Helper::__call()

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

Overrides

Cake\View\Helper::__construct()

_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

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

autoLink() public ¶

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

Link

https://book.cakephp.org/3.0/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

Link

https://book.cakephp.org/3.0/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

Link

https://book.cakephp.org/3.0/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

p> added for double line return

Parameters

string $text: Text

Returns

string

The text with proper

p> and
tags

Link

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

excerpt() public ¶

excerpt( string $text , string $phrase , integer $radius 100 , 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
integer $radius optional 100: 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

\Cake\Utility\Text::excerpt()

Link

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

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

\Cake\Utility\Text::highlight()

Link

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

implementedEvents() public ¶

implementedEvents( )

Event listeners.

Returns

array

Overrides

Cake\View\Helper::implementedEvents()

stripLinks() public ¶

stripLinks( string $text )

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

Parameters

string $text: Text

Returns

string
The text without links

See

\Cake\Utility\Text::stripLinks()

Link

https://book.cakephp.org/3.0/en/views/helpers/text.html#removing-links

tail() public ¶

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

Returns

string
Trimmed string.

See

\Cake\Utility\Text::tail()

Link

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

toList() public ¶

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.

See

\Cake\Utility\Text::toList()

Link

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

truncate() public ¶

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

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

Link

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

Methods inherited from Cake\View\Helper

__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
Helper instance if helper with provided name exists

__set() public ¶

__set( string $name , mixed $value )

Magic setter for removed properties.

Parameters

string $name: Property name.
mixed $value: Value to set.

_cleanConfirmMessage() protected ¶

_cleanConfirmMessage( string $message )

Returns a string read to be used in confirm()

Parameters

string $message: The message to clean

Returns

mixed

_confirm() protected ¶

_confirm( string $message , string $okCode , string $cancelCode '' , array $options [] )

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

Parameters

string $message: Message to be displayed
string $okCode: Code to be executed after user chose 'OK'
string $cancelCode optional '': Code to be executed after user chose 'Cancel'
array $options optional []: Array of options

Returns

string
onclick JS code

addClass() public ¶

addClass( array $options [] , string|null $class null , string $key 'class' )

Adds the given class to the element options

Parameters

array $options optional []: Array options/attributes to add a class to
string|null $class optional null: The class name being added.
string $key optional 'class': the key to use for class.

Returns

array
Array of options with $key set.

getView() public ¶

getView( )

Get the view instance this helper is bound to.

Returns

Cake\View\View
The bound view instance.

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.

Methods used from Cake\Core\InstanceConfigTrait

_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|null $key )

Reads a config key.

Parameters

string|null $key: Key to read.

Returns

mixed

_configWrite() protected ¶

_configWrite( string|array $key , mixed $value , boolean|string $merge false )

Writes a config key.

Parameters

string|array $key: Key to write to.
mixed $value: Value to write.
boolean|string $merge optional false: 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

config() public ¶

config( string|array|null $key null , mixed|null $value null , boolean $merge true )

Gets/Sets the config.

Usage

Reading the whole config:

$this->config();

Reading a specific value:

$this->config('key');

Reading a nested value:

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

Setting a specific value:

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

Setting a nested value:

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

Updating multiple config settings at the same time:

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

Deprecated

3.4.0 use setConfig()/getConfig() instead.

Parameters

string|array|null $key optional null: The key to get/set, or a complete array of configs.
mixed|null $value optional null: The value to set.
boolean $merge optional true: Whether to recursively merge or overwrite existing config, defaults to true.

Returns

mixed
Config value being read, or the object itself on write operations.

Throws

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

configShallow() public ¶

configShallow( string|array $key , mixed|null $value null )

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 null: The value to set.

Returns

$this

getConfig() public ¶

getConfig( string|null $key null , mixed $default null )

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 null: The key to get or null for the whole config.
mixed $default optional null: The return value when the key does not exist.

Returns

mixed
Config value being read.

setConfig() public ¶

setConfig( string|array $key , mixed|null $value null , boolean $merge true )

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 null: The value to set.
boolean $merge optional true: 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.

Properties detail

`$_defaultConfig` ¶

protected array

Default config for this class

[
    'engine' => 'Cake\Utility\Text'
]

`$_engine` ¶

protected Cake\Utility\Text

Cake Utility Text instance

`$_placeholders` ¶

protected array

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

[]

`$helpers` ¶

public array

helpers

['Html']

Magic properties detail

`$Html` ¶

public Cake\View\Helper\HtmlHelper

Namespaces

Classes

Traits

Class TextHelper

Properties summary

Magic properties summary

Inherited Properties

Method Summary

__call() public

__construct() public

_insertPlaceHolder() protected

_linkEmails() protected

_linkUrls() protected

autoLink() public

autoLinkEmails() public

autoLinkUrls() public

autoParagraph() public

excerpt() public

highlight() public

implementedEvents() public

stripLinks() public

tail() public

toList() public

truncate() public

Method Detail

__call() public ¶

Parameters

Returns

Overrides

__construct() public ¶

Settings:

Parameters

Throws

Overrides

_insertPlaceHolder() protected ¶

Parameters

Returns

_linkEmails() protected ¶

Parameters

Returns

See

_linkUrls() protected ¶

Parameters

Returns

autoLink() public ¶

Options

Parameters

Returns

Link

autoLinkEmails() public ¶

Options

Parameters

Returns

Link

autoLinkUrls() public ¶

Options

Parameters

Returns

Link

autoParagraph() public ¶

Parameters

Returns

Link

excerpt() public ¶

Parameters

Returns

See

Link

highlight() public ¶

Parameters

Returns

See

Link

implementedEvents() public ¶

Returns

Overrides

stripLinks() public ¶

Parameters

Returns

See