W3cubDocs

/CakePHP 3.4

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
Extended by Cake\View\Helper\TextHelper

Properties summary

  • $_defaultConfig protected
    array
    Default config for this class
  • $_engine protected
    stdClass
    String utility instance
  • $_placeholders protected
    array

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

  • $helpers public
    array
    helpers

Magic properties summary

Inherited Properties

Method Summary

  • __call() public
    Call methods from String utility class
  • __construct() public
    Constructor
  • 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.
  • Adds email links (<a href="mailto:....) to a given text.
  • Adds links (<a href=....) to a given text, by finding text that begins with strings like http:// and ftp://.

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

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

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

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

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

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

http://book.cakephp.org/3.0/en/views/helpers/text.html#linking-urls

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

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

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

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

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

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

implementedEvents()source public

implementedEvents( )

Event listeners.

Returns

array

Overrides

Cake\View\Helper::implementedEvents()
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

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

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

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

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

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

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

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

Methods inherited from Cake\View\Helper

__debugInfo()source public

__debugInfo( )

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

Returns

array

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

_confirm()source 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()source 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()source public

getView( )

Get the view instance this helper is bound to.

Returns

Cake\View\View
The bound view instance.

initialize()source 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()source 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()source protected

_configRead( string|null $key )

Reads a config key.

Parameters

string|null $key
Key to read.

Returns

mixed

_configWrite()source 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()source 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()source 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->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']);

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

getConfig( string|null $key 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');

Parameters

string|null $key optional null
The key to get or null for the whole config.

Returns

mixed
Config value being read.

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

$_defaultConfigsource

protected array

Default config for this class

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

$_enginesource

protected stdClass

String utility instance

$_placeholderssource

protected array

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

[]

$helperssource

public array

helpers

['Html']

Magic properties detail

© 2005–2017 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/3.4/class-Cake.View.Helper.TextHelper.html