Text

Text

class Cake\Utility\Text

The Text class includes convenience methods for creating and manipulatingstrings and is normally accessed statically. Example:Text::uuid().

If you need Cake\View\Helper\TextHelper functionalities outsideof a View, use the Text class:

namespace App\Controller;
 
use Cake\Utility\Text;
 
class UsersController extends AppController
{
    public function initialize(): void
    {
        parent::initialize();
        $this->loadComponent('Auth')
    };
 
    public function afterLogin()
    {
        $message = $this->Users->find('new_message');
        if (!empty($message)) {
            // Notify user of new message
            $this->Flash->success(__(
                'You have a new message: {0}',
                Text::truncate($message['Message']['body'], 255, ['html' => true])
            ));
        }
    }
}

Convert Strings into ASCII

static Cake\Utility\Text::transliterate($string, $transliteratorId = null)

Transliterate by default converts all characters in provided string intoequivalent ASCII characters. The method expects UTF-8 encoding. The characterconversion can be controlled using transliteration identifiers which you canpass using the $transliteratorId argument or change the default identifierstring using Text::setTransliteratorId(). ICU transliteration identifiersare basically of form <source script>:<target script> and you can specifymultiple conversion pairs separated by ;. You can find more info abouttransliterator identifiershere:

// apple puree
Text::transliterate('apple purée');
 
// Ubermensch (only latin characters are transliterated)
Text::transliterate('Übérmensch', 'Latin-ASCII;');

Creating URL Safe Strings

static Cake\Utility\Text::slug($string, $options = [])

Slug transliterates all characters into ASCII versions and converting unmatchedcharacters and spaces to dashes. The slug method expects UTF-8 encoding.

You can provide an array of options that controls slug. $options can also bea string in which case it will be used as replacement string. The supportedoptions are:

replacement Replacement string, defaults to ‘-‘.
transliteratorId A valid tranliterator id string. If default nullText::$_defaultTransliteratorId to be used.If false no transliteration will be done, only non words will be removed.
preserve Specific non-word character to preserve. Defaults to null.For e.g. this option can be set to ‘.’ to generate clean file names:

// apple-puree
Text::slug('apple purée');
 
// apple_puree
Text::slug('apple purée', '_');
 
// foo-bar.tar.gz
Text::slug('foo bar.tar.gz', ['preserve' => '.']);

Generating UUIDs

static Cake\Utility\Text::uuid

The UUID method is used to generate unique identifiers as per RFC 4122. TheUUID is a 128-bit string in the format of485fc381-e790-47a3-9794-1337c0a8fe68.

Text::uuid(); // 485fc381-e790-47a3-9794-1337c0a8fe68

Simple String Parsing

static Cake\Utility\Text::tokenize($data, $separator = ', ', $leftBound = '(', $rightBound = ')')

Tokenizes a string using $separator, ignoring any instance of $separatorthat appears between $leftBound and $rightBound.

This method can be useful when splitting up data that has regular formattingsuch as tag lists:

$data = "cakephp 'great framework' php";
$result = Text::tokenize($data, ' ', "'", "'");
// Result contains
['cakephp', "'great framework'", 'php'];

Cake\Utility\Text::parseFileSize(string $size, $default)

This method unformats a number from a human-readable byte size to an integernumber of bytes:

$int = Text::parseFileSize('2GB');

Formatting Strings

static Cake\Utility\Text::insert($string, $data, $options = [])

The insert method is used to create string templates and to allow for key/valuereplacements:

Text::insert(
    'My name is :name and I am :age years old.',
    ['name' => 'Bob', 'age' => '65']
);
// Returns: "My name is Bob and I am 65 years old."

static Cake\Utility\Text::cleanInsert($string, $options = [])

Cleans up a Text::insert formatted string with given $options dependingon the ‘clean’ key in $options. The default method used is text but html isalso available. The goal of this function is to replace all whitespace andunneeded markup around placeholders that did not get replaced byText::insert.

You can use the following options in the options array:

$options = [
    'clean' => [
        'method' => 'text', // or html
    ],
    'before' => '',
    'after' => ''
];

Wrapping Text

static Cake\Utility\Text::wrap($text, $options = [])

Wraps a block of text to a set width and indents blocks as well.Can intelligently wrap text so words are not sliced across lines:

$text = 'This is the song that never ends.';
$result = Text::wrap($text, 22);
 
// Returns
This is the song that
never ends.

You can provide an array of options that control how wrapping is done. Thesupported options are:

width The width to wrap to. Defaults to 72.
wordWrap Whether or not to wrap whole words. Defaults to true.
indent The character to indent lines with. Defaults to ‘’.
indentAt The line number to start indenting text. Defaults to 0.

static Cake\Utility\Text::wrapBlock($text, $options = [])

If you need to ensure that the total width of the generated block won’texceed a certain length even with internal identation, you need to usewrapBlock() instead of wrap(). This is particulary useful to generatetext for the console for example. It accepts the same options as wrap():

$text = 'This is the song that never ends. This is the song that never ends.';
$result = Text::wrapBlock($text, [
    'width' => 22,
    'indent' => ' → ',
    'indentAt' => 1
]);
 
// Returns
This is the song that
 → never ends. This
 → is the song that
 → never ends.

Highlighting Substrings

Cake\Utility\Text::highlight(string $haystack, string $needle, array $options = [])

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

Options:

format string - The piece of HTML with the phrase that will behighlighted
html bool - If true, will ignore any HTML tags, ensuring that onlythe 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:

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

Removing Links

Cake\Utility\Text::stripLinks($text)

Strips the supplied $text of any HTML links.

Truncating Text

Cake\Utility\Text::truncate(string $text, int $length = 100, array $options)

If $text is longer than $length, this method truncates it at $lengthand adds a suffix consisting of 'ellipsis', if defined. If 'exact' ispassed as false, the truncation will occur at the first whitespace after thepoint 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 followingpossible 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\Utility\Text::tail(string $text, int $length = 100, array $options)

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

$options is used to pass all extra parameters, and has the followingpossible 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\Utility\Text::excerpt(string $haystack, string $needle, integer $radius=100, string $ellipsis="…")

Extracts an excerpt from $haystack surrounding the $needle with a numberof characters on each side determined by $radius, and prefix/suffix with$ellipsis. This method is especially handy for search results. The querystring 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\Utility\Text::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