Page Contents

TextHelper

class TextHelper(View $view, array $settings = array())

The TextHelper contains methods to make text more usable and friendly in your views. It aids in enabling links, formatting URLs, creating excerpts of text around chosen words or phrases, highlighting key words in blocks of text, and gracefully truncating long stretches of text.

Changed in version 2.1: Several TextHelper methods have been moved into the String class to allow easier use outside of the View layer. Within a view, these methods are accessible via the TextHelper class. You can call one as you would call a normal helper method: $this->Text->method($args);.

TextHelper::autoLinkEmails(string $text, array $options=array())
Parameters:

  • $text (string) – The text to convert.

  • $options (array) – An array of html attributes for the generated links.

Adds links to the well-formed email addresses in $text, according to any options defined in $options (see HtmlHelper::link()).

$myText = 'For more information regarding our world-famous ' .
    'pastries and desserts, contact [email protected]';
$linkedText = $this->Text->autoLinkEmails($myText);

Output:

For more information regarding our world-famous pastries and desserts,
contact <a href="mailto:[email protected]">info@example.com</a>

Changed in version 2.1: In 2.1 this method automatically escapes its input. Use the escape option to disable this if necessary.

TextHelper::autoLinkUrls(string $text, array $options=array())
Parameters:

  • $text (string) – The text to convert.

  • $options (array) – An array html attributes for the generated links

Same as autoLinkEmails(), only this method searches for strings that start with https, http, ftp, or nntp and links them appropriately.

Changed in version 2.1: In 2.1 this method automatically escapes its input. Use the escape option to disable this if necessary.

Parameters:

  • $text (string) – The text to autolink.

  • $options (array) – An array html attributes for the generated links

Performs the functionality in both autoLinkUrls() and autoLinkEmails() on the supplied $text. All URLs and emails are linked appropriately given the supplied $options.

Changed in version 2.1: As of 2.1, this method automatically escapes its input. Use the escape option to disable this if necessary.

TextHelper::autoParagraph(string $text)
Parameters:

  • $text (string) – The text to convert.

Adds proper <p> around text where double-line returns are found, and <br> where single-line returns are found.

$myText = 'For more information
regarding our world-famous pastries and desserts.

contact [email protected]';
$formattedText = $this->Text->autoParagraph($myText);

Output:

<p>For more information<br />
regarding our world-famous pastries and desserts.</p>
<p>contact info@example.com</p>

New in version 2.4.

TextHelper::highlight(string $haystack, string $needle, array $options = array())
Parameters:

  • $haystack (string) – The string to search.

  • $needle (string) – The string to find.

  • $options (array) – An array of options, see below.

Highlights $needle in $haystack using the $options['format'] string specified or a default string.

Options:

  • ‘format’ - string The piece of HTML with that the phrase will be highlighted

  • ‘html’ - bool If true, will ignore any HTML tags, ensuring that only the correct text is highlighted

Example:

// called as TextHelper
echo $this->Text->highlight(
    $lastSentence,
    'using',
    array('format' => '<span class="highlight">\1</span>')
);

// called as CakeText
App::uses('CakeText', 'Utility');
echo CakeText::highlight(
    $lastSentence,
    'using',
    array('format' => '<span class="highlight">\1</span>')
);

Output:

Highlights $needle in $haystack <span class="highlight">using</span>
the $options['format'] string specified  or a default string.

Strips the supplied $text of any HTML links.

TextHelper::truncate(string $text, int $length=100, array $options)
Parameters:

  • $text (string) – The text to truncate.

  • $length (int) – The length, in characters, beyond which the text should be truncated.

  • $options (array) – An array of options to use.

If $text is longer than $length characters, this method truncates it at $length and adds a suffix consisting of 'ellipsis', if defined. If 'exact' is passed as false, the truncation will occur at the first whitespace after the point at which $length is exceeded. If 'html' is passed as true, HTML tags will be respected and will not be cut off.

$options is used to pass all extra parameters, and has the following possible keys by default, all of which are optional:

array(
    'ellipsis' => '...',
    'exact' => true,
    'html' => false
)

Example:

// called as TextHelper
echo $this->Text->truncate(
    'The killer crept forward and tripped on the rug.',
    22,
    array(
        'ellipsis' => '...',
        'exact' => false
    )
);

// called as CakeText
App::uses('CakeText', 'Utility');
echo CakeText::truncate(
    'The killer crept forward and tripped on the rug.',
    22,
    array(
        'ellipsis' => '...',
        'exact' => false
    )
);

Output:

The killer crept...

Changed in version 2.3: ending has been replaced by ellipsis. ending is still used in 2.2.1

TextHelper::tail(string $text, int $length=100, array $options)
Parameters:

  • $text (string) – The text to truncate.

  • $length (int) – The length, in characters, beyond which the text should be truncated.

  • $options (array) – An array of options to use.

If $text is longer than $length characters, this method removes an initial substring with length consisting of the difference and prepends a prefix consisting of 'ellipsis', if defined. If 'exact' is passed as false, the truncation will occur at the first whitespace prior to the point at which truncation would otherwise take place.

$options is used to pass all extra parameters, and has the following possible keys by default, all of which are optional:

array(
    'ellipsis' => '...',
    'exact' => true
)

New in version 2.3.

Example:

$sampleText = 'I packed my bag and in it I put a PSP, a PS3, a TV, ' .
    'a C# program that can divide by zero, death metal t-shirts'

// called as TextHelper
echo $this->Text->tail(
    $sampleText,
    70,
    array(
        'ellipsis' => '...',
        'exact' => false
    )
);

// called as CakeText
App::uses('CakeText', 'Utility');
echo CakeText::tail(
    $sampleText,
    70,
    array(
        'ellipsis' => '...',
        'exact' => false
    )
);

Output:

...a TV, a C# program that can divide by zero, death metal t-shirts
TextHelper::excerpt(string $haystack, string $needle, integer $radius=100, string $ellipsis="...")
Parameters:

  • $haystack (string) – The string to search.

  • $needle (string) – The string to excerpt around.

  • $radius (int) – The number of characters on either side of $needle you want to include.

  • $ellipsis (string) – Text to append/prepend to the beginning or end of the result.

Extracts an excerpt from $haystack surrounding the $needle with a number of characters on each side determined by $radius, and prefix/suffix with $ellipsis. This method is especially handy for search results. The query string or keywords can be shown within the resulting document.

// called as TextHelper
echo $this->Text->excerpt($lastParagraph, 'method', 50, '...');

// called as CakeText
App::uses('CakeText', 'Utility');
echo CakeText::excerpt($lastParagraph, 'method', 50, '...');

Output:

... by $radius, and prefix/suffix with $ellipsis. This method is
especially handy for search results. The query...
TextHelper::toList(array $list, $and='and')
Parameters:

  • $list (array) – Array of elements to combine into a list sentence.

  • $and (string) – The word used for the last join.

Creates a comma-separated list where the last two items are joined with ‘and’.

// called as TextHelper
echo $this->Text->toList($colors);

// called as CakeText
App::uses('CakeText', 'Utility');
echo CakeText::toList($colors);

Output:

red, orange, yellow, green, blue, indigo and violet