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: http://book.cakephp.org/3.0/en/views/helpers/text.html

Property Summary

$Html public @property

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

stdClass

String utility instance
$_helperMap protected

array

A helper lookup table used to lazy load helper objects.
$_placeholders protected

array

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

array

Holds the fields ['field_name' => ['type' => 'string', 'length' => 100]], primaryKey and validates ['field_name']
$helpers public

array

helpers
$plugin public

string

Plugin path
$request public

Cake\Network\Request

Request object
$tags public

array

Holds tag templates.
$theme public

string

The current theme name if any.

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

Delete a single config key
_configRead() protected

Read a config variable
_configWrite() protected

Write a config variable
_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
config() public

Usage
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.
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.
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): mixed

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

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

Returns

array

__get() ¶ public

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

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

_configDelete() ¶ protected

_configDelete(string $key): void

Delete a single config key

Parameters

string $key: Key to delete.

Returns

void

Throws

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

_configRead() ¶ protected

_configRead(string|null $key): mixed

Read a config variable

Parameters

string|null $key: Key to read.

Returns

mixed

_configWrite() ¶ protected

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

Write a config variable

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.

Returns

void

Throws

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

_confirm() ¶ protected

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

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

_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

Replaced values.

_linkEmails() ¶ protected

_linkEmails(string $text, array $options): string

Links email addresses

Parameters

string $text: The text to operate on
array $options: An array of options to use for the HTML.

Returns

string

_linkUrls() ¶ protected

_linkUrls(string $text, array $htmlOptions): string

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|null $class = null, string $key = 'class'): array

Adds the given class to the element options

Parameters

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

Returns

array

Array of options with $key set.

autoLink() ¶ public

autoLink(string $text, array $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 $options optional: Array of HTML options, and options listed above.

Returns

string

The text with links

Links

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

autoLinkEmails() ¶ public

autoLinkEmails(string $text, array $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 $options optional: Array of HTML options, and options listed above.

Returns

string

The text with links

Links

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

autoLinkUrls() ¶ public

autoLinkUrls(string $text, array $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 $options optional: Array of HTML options, and options listed above.

Returns

string

The text with links

Links

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

autoParagraph() ¶ public

autoParagraph(string $text): string

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

added for double line return

Parameters

string $text: Text

Returns

string

The text with proper

and
tags

Links

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

config() ¶ public

config(string|array|null $key = null, mixed|null $value = null, bool $merge = true): mixed

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

Parameters

string|array|null $key optional: The key to get/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

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

Returns

$this

The object itself.

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

Modified string

Links

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

highlight() ¶ public

highlight(string $text, string $phrase, array $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 $options optional: An array of HTML attributes and options.

Returns

string

The highlighted text

Links

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

implementedEvents() ¶ public

implementedEvents(): array

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

initialize() ¶ public

initialize(array $config): void

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.

Returns

void

stripLinks() ¶ public

stripLinks(string $text): string

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

Parameters

string $text: Text

Returns

string

The text without links

Links

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

tail() ¶ public

tail(string $text, int $length = 100, array $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 $options optional: An array of HTML attributes and options.

Returns

string

Trimmed string.

Links

http://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 = ', '): string

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

Links

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

truncate() ¶ public

truncate(string $text, int $length = 100, array $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 $options optional: An array of HTML attributes and options.

Returns

string

__construct() public

__debugInfo() public

__get() public

_configDelete() protected

_configRead() protected

_configWrite() protected

_confirm() protected

_insertPlaceHolder() protected

_linkEmails() protected

_linkUrls() protected

addClass() public

autoLink() public

autoLinkEmails() public

autoLinkUrls() public

autoParagraph() public

config() public

Usage

configShallow() public

excerpt() public

highlight() public

implementedEvents() public

initialize() public

stripLinks() public

tail() public

toList() public

truncate() public

Method Detail

__call() ¶ public

Parameters

Returns

__construct() ¶ public

Settings:

Parameters

Throws

__debugInfo() ¶ public

Returns

__get() ¶ public

Parameters

Returns

_configDelete() ¶ protected

Parameters

Returns

Throws

_configRead() ¶ protected

Parameters

Returns

_configWrite() ¶ protected

Parameters

Returns

Throws

_confirm() ¶ protected

Parameters

Returns

_insertPlaceHolder() ¶ protected

Parameters

Returns

_linkEmails() ¶ protected

Parameters

Returns

See Also

_linkUrls() ¶ protected

Parameters

Returns

addClass() ¶ public

Parameters

Returns

autoLink() ¶ public

Options

Parameters

Returns

Links

autoLinkEmails() ¶ public

Options

Parameters

Returns

`$Html` ¶ public @property

`$_View` ¶ protected

`$_config` ¶ protected

`$_configInitialized` ¶ protected

`$_defaultConfig` ¶ protected