This document is for CakePHP's development version, which can be significantly different from previous releases.
You may want to read current stable release documentation instead.

Page Contents

Text

class Cake\View\Helper\TextHelper(View $view, array $config = [])

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.

Linking Email addresses

Cake\View\Helper\TextHelper::autoLinkEmails(string $text, array $options = [])

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>

This method automatically escapes its input. Use the escape option to disable this if necessary.

Linking URLs

Cake\View\Helper\TextHelper::autoLinkUrls(string $text, array $options = [])

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

This method automatically escapes its input. Use the escape option to disable this if necessary.

Linking Both URLs and Email Addresses

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

This method automatically escapes its input. Use the escape option to disable this if necessary.

Further options:

  • stripProtocol: Strips http:// and https:// from the beginning of the link label. 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 ellipsis.

Converting Text into Paragraphs

Cake\View\Helper\TextHelper::autoParagraph(string $text)

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>

Highlighting Substrings

Cake\View\Helper\TextHelper::highlight(string $haystack, string $needle, array $options = [])

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

Options:

  • format string - The piece of HTML with the phrase that 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',
    ['format' => '<span class="highlight">\1</span>']
);

// Called as Text
use Cake\Utility\Text;

echo Text::highlight(
    $lastSentence,
    'using',
    ['format' => '<span class="highlight">\1</span>']
);

Output:

Truncating Text

Cake\View\Helper\TextHelper::truncate(string $text, int $length = 100, array $options)

If $text is longer than $length, 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:

[
    'ellipsis' => '...',
    'exact' => true,
    'html' => false
]

Example:

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

// Called as Text
use Cake\Utility\Text;

echo Text::truncate(
    'The killer crept forward and tripped on the rug.',
    22,
    [
        'ellipsis' => '...',
        'exact' => false
    ]
);

Output:

The killer crept...

Truncating the Tail of a String

Cake\View\Helper\TextHelper::tail(string $text, int $length = 100, array $options)

If $text is longer than $length, 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:

[
    'ellipsis' => '...',
    'exact' => true
]

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,
    [
        'ellipsis' => '...',
        'exact' => false
    ]
);

// Called as Text
use Cake\Utility\Text;

echo Text::tail(
    $sampleText,
    70,
    [
        'ellipsis' => '...',
        'exact' => false
    ]
);

Output:

...a TV, a C# program that can divide by zero, death metal t-shirts

Extracting an Excerpt

Cake\View\Helper\TextHelper::excerpt(string $haystack, string $needle, integer $radius=100, string $ellipsis="...")

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 Text
use Cake\Utility\Text;

echo Text::excerpt($lastParagraph, 'method', 50, '...');

Output:

... by $radius, and prefix/suffix with $ellipsis. This method is especially
handy for search results. The query...

Converting an Array to Sentence Form

Cake\View\Helper\TextHelper::toList(array $list, $and='and', $separator=', ')

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

$colors = ['red', 'orange', 'yellow', 'green', 'blue', 'indigo', 'violet'];

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

// Called as Text
use Cake\Utility\Text;

echo Text::toList($colors);

Output:

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