Class TextHelper
Text helper library.
Text manipulations: Highlight, excerpt, truncate, strip of links, convert email addresses to mailto: links...
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 returnadded 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
__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 theUtility
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
_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
_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 $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
See Also
_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
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
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
Links
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
Links
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
Links
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
Links
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
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
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
Links
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
See Also
Links
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
See Also
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 stringexact
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
See Also
Links
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
See Also
Links
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 stringexact
If false, $text will not be cut mid-wordhtml
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
See Also
Links
Property Detail
$_configInitialized ¶ protected
Whether the config property has already been configured with defaults
Type
bool
$_placeholders ¶ protected
An array of md5sums and their contents. Used when inserting links into text.
Type
array
$fieldset ¶ public
Holds the fields ['field_name' => ['type' => 'string', 'length' => 100]], primaryKey and validates ['field_name']
Type
array