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.
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.
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.
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.
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.
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>
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:
Strips the supplied $text
of any HTML links.
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...
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
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...
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