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/5/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 helper.
$_placeholders protected

array<string, array>

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

array<string, \Cake\View\Helper>

Loaded helper instances.
$helpers protected

array

helpers

Method Summary

__call() public

Call methods from String utility class
__construct() public

Default 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.
_prepareLinkLabel() protected

Prepares the link label.
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 @method

See Text::excerpt()
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 @method

See Text::highlight()
implementedEvents() public

Event listeners.
initialize() public

Constructor hook method.
setConfig() public

Sets the config.
slug() public @method

See Text::slug()
tail() public @method

See Text::tail()
toList() public @method

See Text::toList()
truncate() public @method

See Text::truncate()

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<string, mixed> $config = [])

Default Constructor

Parameters

Cake\View\View $view: The View this helper is being attached to.
array<string, mixed> $config optional: Configuration settings for the helper.

__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

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

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

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

_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

The text with links inserted.

_prepareLinkLabel() ¶ protected

_prepareLinkLabel(string $name, array<string, mixed> $options): string

Prepares the link label.

Parameters

string $name: Link label.
array<string, mixed> $options: The options for the generated link label.

Returns

string

Modified link label.

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>

Array of options with $key set.

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

The text with links

Links

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

The text with links

Links

https://book.cakephp.org/5/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.
stripProtocol Strips http:// and https:// from the beginning of the link. Default off.
maxLength The maximum length of the link label. Default off.
ellipsis The string to append to the end of the link label. Defaults to UTF8 version.

Parameters

string $text: Text
array<string, mixed> $options optional: Array of HTML options, and options listed above.

Returns

string

The text with links

Links

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

The text with proper

and
tags

Links

https://book.cakephp.org/5/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 @method

excerpt(string $text, string $phrase, int $radius = 100, string $ending = '…'): string

See Text::excerpt()

Parameters

string $text
string $phrase
int $radius optional
string $ending optional

Returns

string

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

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

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

Configuration data at the named key

Throws

InvalidArgumentException

getView() ¶ public

getView(): Cake\View\View

Get the view instance this helper is bound to.

Returns

Cake\View\View

The bound view instance.

highlight() ¶ public @method

highlight(string $text, array|string $phrase, array $options = []): string

See Text::highlight()

Parameters

string $text
array|string $phrase
array $options optional

Returns

string

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

slug(string $string, array|string $options = []): string

See Text::slug()

Parameters

string $string
array|string $options optional

Returns

string

tail() ¶ public @method

tail(string $text, int $length = 100, array $options = []): string

See Text::tail()

Parameters

string $text
int $length optional
array $options optional

Returns

string

toList() ¶ public @method

toList(array $list, ?string $and = null, string $separator = ', '): string

See Text::toList()

Parameters

array $list
?string $and optional
string $separator optional

Returns

string

truncate() ¶ public @method

truncate(string $text, int $length = 100, array $options = []): string

See Text::truncate()

Parameters

string $text
int $length optional
array $options optional

Returns

string

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

Type

array<string, mixed>

`$_placeholders` ¶ protected

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

Type

array<string, array>

`$helperInstances` ¶ protected

Loaded helper instances.

Type

array<string, \Cake\View\Helper>

`$helpers` ¶ protected

helpers

Type

array

Namespaces

Class TextHelper

Property Summary

Method Summary

__call() public

__construct() public

__debugInfo() public

__get() public

_configDelete() protected

_configRead() protected

_configWrite() protected

_confirm() protected

_insertPlaceHolder() protected

_linkEmails() protected

_linkUrls() protected

_prepareLinkLabel() protected

addClass() public

autoLink() public

autoLinkEmails() public

autoLinkUrls() public

autoParagraph() public

configShallow() public

excerpt() public @method

getConfig() public

getConfigOrFail() public

getView() public

highlight() public @method

implementedEvents() public

initialize() public

setConfig() public

slug() public @method

tail() public @method

toList() public @method

truncate() public @method

Method Detail

__call() ¶ public

Parameters

Returns

__construct() ¶ public

Parameters

__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

_prepareLinkLabel() ¶ protected

Parameters

Returns

addClass() ¶ public

Parameters

Returns

autoLink() ¶ public

Options

Parameters

Returns

Links

`$Html` ¶ public @property

`$_View` ¶ protected

`$_config` ¶ protected

`$_configInitialized` ¶ protected

`$_defaultConfig` ¶ protected