Modules

Kohana_Text

This class is a transparent base class for Text and should not be accessed directly.

Text helper class. Provides simple methods for working with text.

package
Kohana
category
Helpers
author
Kohana Team
copyright
© 2007-2012 Kohana Team
license
https://kohana.top/license

Class declared in SYSPATH/classes/Kohana/Text.php on line 12.

Properties

public static array $units

number units and text equivalents

array(31) (
    1000000000 => string(7) "billion"
    1000000 => string(7) "million"
    1000 => string(8) "thousand"
    100 => string(7) "hundred"
    90 => string(6) "ninety"
    80 => string(6) "eighty"
    70 => string(7) "seventy"
    60 => string(5) "sixty"
    50 => string(5) "fifty"
    40 => string(5) "forty"
    30 => string(6) "thirty"
    20 => string(6) "twenty"
    19 => string(8) "nineteen"
    18 => string(8) "eighteen"
    17 => string(9) "seventeen"
    16 => string(7) "sixteen"
    15 => string(7) "fifteen"
    14 => string(8) "fourteen"
    13 => string(8) "thirteen"
    12 => string(6) "twelve"
    11 => string(6) "eleven"
    10 => string(3) "ten"
    9 => string(4) "nine"
    8 => string(5) "eight"
    7 => string(5) "seven"
    6 => string(3) "six"
    5 => string(4) "five"
    4 => string(4) "four"
    3 => string(5) "three"
    2 => string(3) "two"
    1 => string(3) "one"
)

Methods

public static alternate( ) (defined in Kohana_Text)

Alternates between two or more strings.

echo Text::alternate('one', 'two'); // "one"
echo Text::alternate('one', 'two'); // "two"
echo Text::alternate('one', 'two'); // "one"

Note that using multiple iterations of different strings may produce unexpected results.

Return Values

  • string

Source Code

public static function alternate()
{
    static $i;

    if (func_num_args() === 0) {
        $i = 0;
        return '';
    }

    $args = func_get_args();
    return $args[($i++ % count($args))];
}

Converts text email addresses and anchors into links. Existing links will not be altered.

echo Text::auto_link($text);

This method is not foolproof since it uses regex to parse HTML.

Parameters

  • string $text required - Text to auto link

Tags

Return Values

  • string

Source Code

public static function auto_link($text)
{
    // Auto link emails first to prevent problems with "[email protected]"
    return Text::auto_link_urls(Text::auto_link_emails($text));
}

Converts text email addresses into links. Existing links will not be altered.

echo Text::auto_link_emails($text);

This method is not foolproof since it uses regex to parse HTML.

Parameters

  • string $text required - Text to auto link

Tags

Return Values

  • string

Source Code

public static function auto_link_emails($text)
{
    // Find and replace all email addresses that are not part of an existing html mailto anchor
    // Note: The "58;" negative lookbehind prevents matching of existing encoded html mailto anchors
    //       The html entity for a colon (:) is : or : or : etc.
    return preg_replace_callback('~\b(?<!href="mailto:|58;)(?!\.)[-+_a-z0-9.]++(?<!\.)@(?![-.])[-a-z0-9.]+(?<!\.)\.[a-z]{2,6}\b(?!</a>)~i', 'Text::_auto_link_emails_callback', $text);
}

Converts text anchors into links. Existing links will not be altered.

echo Text::auto_link_urls($text);

This method is not foolproof since it uses regex to parse HTML.

Parameters

  • string $text required - Text to auto link

Tags

Return Values

  • string

Source Code

public static function auto_link_urls($text)
{
    // Find and replace all http/https/ftp/ftps links that are not part of an existing html anchor
    $text = preg_replace_callback('~\b(?<!href="|">)(?:ht|f)tps?://[^<\s]+(?:/|\b)~i', 'Text::_auto_link_urls_callback1', $text);

    // Find and replace all naked www.links.com (without http://)
    return preg_replace_callback('~\b(?<!://|">)www(?:\.[a-z0-9][-a-z0-9]*+)+\.[a-z]{2,6}[^<\s]*\b~i', 'Text::_auto_link_urls_callback2', $text);
}

public static auto_p( string $str [, boolean $br = bool TRUE ] ) (defined in Kohana_Text)

Automatically applies "p" and "br" markup to text. Basically nl2br on steroids.

echo Text::auto_p($text);

This method is not foolproof since it uses regex to parse HTML.

Parameters

  • string $str required - Subject
  • boolean $br = bool TRUE - Convert single linebreaks to

Return Values

  • string

Source Code

public static function auto_p($str, $br = true)
{
    // Trim whitespace
    if (($str = trim($str)) === '')
        return '';

    // Standardize newlines
    $str = str_replace(["\r\n", "\r"], "\n", $str);

    // Trim whitespace on each line
    $str = preg_replace('~^[ \t]+~m', '', $str);
    $str = preg_replace('~[ \t]+$~m', '', $str);

    // The following regexes only need to be executed if the string contains html
    if ($html_found = (strpos($str, '<') !== false)) {
        // Elements that should not be surrounded by p tags
        $no_p = '(?:p|div|h[1-6r]|ul|ol|li|blockquote|d[dlt]|pre|t[dhr]|t(?:able|body|foot|head)|c(?:aption|olgroup)|form|s(?:elect|tyle)|a(?:ddress|rea)|ma(?:p|th))';

        // Put at least two linebreaks before and after $no_p elements
        $str = preg_replace('~^<' . $no_p . '[^>]*+>~im', "\n$0", $str);
        $str = preg_replace('~</' . $no_p . '\s*+>$~im', "$0\n", $str);
    }

    // Do the <p> magic!
    $str = '<p>' . trim($str) . '</p>';
    $str = preg_replace('~\n{2,}~', "</p>\n\n<p>", $str);

    // The following regexes only need to be executed if the string contains html
    if ($html_found !== false) {
        // Remove p tags around $no_p elements
        $str = preg_replace('~<p>(?=</?' . $no_p . '[^>]*+>)~i', '', $str);
        $str = preg_replace('~(</?' . $no_p . '[^>]*+>)</p>~i', '$1', $str);
    }

    // Convert single linebreaks to <br />
    if ($br === true) {
        $str = preg_replace('~(?<!\n)\n(?!\n)~', "<br />\n", $str);
    }

    return $str;
}

public static bytes( integer $bytes [, string $force_unit = NULL , string $format = NULL , boolean $si = bool TRUE ] ) (defined in Kohana_Text)

Returns human readable sizes. Based on original functions written by Aidan Lister and Quentin Zervaas.

echo Text::bytes(filesize($file));

Parameters

  • integer $bytes required - Size in bytes
  • string $force_unit = NULL - A definitive unit
  • string $format = NULL - The return string format
  • boolean $si = bool TRUE - Whether to use SI prefixes or IEC

Return Values

  • string

Source Code

public static function bytes($bytes, $force_unit = null, $format = null, $si = true)
{
    // Format string
    $format = ($format === null) ? '%01.2f %s' : (string) $format;

    // IEC prefixes (binary)
    if ($si == false OR strpos($force_unit, 'i') !== false) {
        $units = ['B', 'KiB', 'MiB', 'GiB', 'TiB', 'PiB'];
        $mod = 1024;
    }
    // SI prefixes (decimal)
    else {
        $units = ['B', 'kB', 'MB', 'GB', 'TB', 'PB'];
        $mod = 1000;
    }

    // Determine unit to use
    if (($power = array_search((string) $force_unit, $units)) === false) {
        $power = ($bytes > 0) ? floor(log($bytes, $mod)) : 0;
    }

    return sprintf($format, $bytes / pow($mod, $power), $units[$power]);
}

public static censor( string $str , array $badwords [, string $replacement = string(1) "#" , boolean $replace_partial_words = bool TRUE ] ) (defined in Kohana_Text)

Replaces the given words with a string.

// Displays "What the #####, man!"
echo Text::censor('What the frick, man!', [
    'frick' => '#####',
]);

Parameters

  • string $str required - Phrase to replace words in
  • array $badwords required - Words to replace
  • string $replacement = string(1) "#" - Replacement string
  • boolean $replace_partial_words = bool TRUE - Replace words across word boundaries (space, period, etc)

Tags

Return Values

  • string

Source Code

public static function censor($str, $badwords, $replacement = '#', $replace_partial_words = true)
{
    foreach ((array) $badwords as $key => $badword) {
        $badwords[$key] = str_replace('\*', '\S*?', preg_quote((string) $badword));
    }

    $regex = '(' . implode('|', $badwords) . ')';

    if ($replace_partial_words === false) {
        // Just using \b isn't sufficient when we need to replace a badword that already contains word boundaries itself
        $regex = '(?<=\b|\s|^)' . $regex . '(?=\b|\s|$)';
    }

    $regex = '!' . $regex . '!ui';

    // if $replacement is a single character: replace each of the characters of the badword with $replacement
    if (UTF8::strlen($replacement) == 1) {
        return preg_replace_callback($regex, function($matches) use ($replacement) {
            return str_repeat($replacement, UTF8::strlen($matches[1]));
        }, $str);
    }

    // if $replacement is not a single character, fully replace the badword with $replacement
    return preg_replace($regex, $replacement, $str);
}

public static limit_chars( string $str [, integer $limit = integer 100 , string $end_char = NULL , boolean $preserve_words = bool FALSE ] ) (defined in Kohana_Text)

Limits a phrase to a given number of characters.

$text = Text::limit_chars($text);

Parameters

  • string $str required - Phrase to limit characters of
  • integer $limit = integer 100 - Number of characters to limit to
  • string $end_char = NULL - End character or entity
  • boolean $preserve_words = bool FALSE - Enable or disable the preservation of words while limiting

Tags

Return Values

  • string

Source Code

public static function limit_chars($str, $limit = 100, $end_char = null, $preserve_words = false)
{
    $end_char = ($end_char === null) ? '…' : $end_char;

    $limit = (int) $limit;

    if (trim($str) === '' OR UTF8::strlen($str) <= $limit)
        return $str;

    if ($limit <= 0)
        return $end_char;

    if ($preserve_words === false)
        return rtrim(UTF8::substr($str, 0, $limit)) . $end_char;

    // Don't preserve words. The limit is considered the top limit.
    // No strings with a length longer than $limit should be returned.
    if (!preg_match('/^.{0,' . $limit . '}\s/us', $str, $matches))
        return $end_char;

    return rtrim($matches[0]) . ((strlen($matches[0]) === strlen($str)) ? '' : $end_char);
}

public static limit_words( string $str [, integer $limit = integer 100 , string $end_char = NULL ] ) (defined in Kohana_Text)

Limits a phrase to a given number of words.

$text = Text::limit_words($text);

Parameters

  • string $str required - Phrase to limit words of
  • integer $limit = integer 100 - Number of words to limit to
  • string $end_char = NULL - End character or entity

Return Values

  • string

Source Code

public static function limit_words($str, $limit = 100, $end_char = null)
{
    $limit = (int) $limit;
    $end_char = ($end_char === null) ? '…' : $end_char;

    if (trim($str) === '')
        return $str;

    if ($limit <= 0)
        return $end_char;

    preg_match('/^\s*+(?:\S++\s*+){1,' . $limit . '}/u', $str, $matches);

    // Only attach the end character if the matched string is shorter
    // than the starting string.
    return rtrim($matches[0]) . ((strlen($matches[0]) === strlen($str)) ? '' : $end_char);
}

public static number( integer $number ) (defined in Kohana_Text)

Format a number to human-readable text.

// Display: one thousand and twenty-four
echo Text::number(1024);

// Display: five million, six hundred and thirty-two
echo Text::number(5000632);

Parameters

  • integer $number required - Number to format

Tags

  • Since - 3.0.8

Return Values

  • string

Source Code

public static function number($number)
{
    // The number must always be an integer
    $number = (int) $number;

    // Uncompiled text version
    $text = [];

    // Last matched unit within the loop
    $last_unit = null;

    // The last matched item within the loop
    $last_item = '';

    foreach (Text::$units as $unit => $name) {
        if ($number / $unit >= 1) {
            // $value = the number of times the number is divisible by unit
            $number -= $unit * ($value = (int) floor($number / $unit));
            // Temporary var for textifying the current unit
            $item = '';

            if ($unit < 100) {
                if ($last_unit < 100 AND $last_unit >= 20) {
                    $last_item .= '-' . $name;
                } else {
                    $item = $name;
                }
            } else {
                $item = Text::number($value) . ' ' . $name;
            }

            // In the situation that we need to make a composite number (i.e. twenty-three)
            // then we need to modify the previous entry
            if (empty($item)) {
                array_pop($text);

                $item = $last_item;
            }

            $last_item = $text[] = $item;
            $last_unit = $unit;
        }
    }

    if (count($text) > 1) {
        $and = array_pop($text);
    }

    $text = implode(', ', $text);

    if (isset($and)) {
        $text .= ' and ' . $and;
    }

    return $text;
}

public static random( [ string $type = NULL , integer $length = integer 8 ] ) (defined in Kohana_Text)

Generates a random string of a given type and length.

$str = Text::random(); // 8 character random string

The following types are supported:

alnum
Upper and lower case a-z, 0-9 (default)
alpha
Upper and lower case a-z
hexdec
Hexadecimal characters a-f, 0-9
distinct
Uppercase characters and numbers that cannot be confused

You can also create a custom type by providing the "pool" of characters as the type.

Parameters

  • string $type = NULL - A type of pool, or a string of characters to use as the pool
  • integer $length = integer 8 - Length of string to return

Tags

Return Values

  • string

Source Code

public static function random($type = null, $length = 8)
{
    if ($type === null) {
        // Default is to generate an alphanumeric string
        $type = 'alnum';
    }

    $utf8 = false;

    switch ($type) {
        case 'alnum':
            $pool = '0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ';
            break;
        case 'alpha':
            $pool = 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ';
            break;
        case 'hexdec':
            $pool = '0123456789abcdef';
            break;
        case 'numeric':
            $pool = '0123456789';
            break;
        case 'nozero':
            $pool = '123456789';
            break;
        case 'distinct':
            $pool = '2345679ACDEFHJKLMNPRSTUVWXYZ';
            break;
        default:
            $pool = (string) $type;
            $utf8 = !UTF8::is_ascii($pool);
            break;
    }

    // Split the pool into an array of characters
    $pool = ($utf8 === true) ? UTF8::str_split($pool, 1) : str_split($pool, 1);

    // Largest pool key
    $max = count($pool) - 1;

    $str = '';
    for ($i = 0; $i < $length; $i++) {
        // Select a random character from the pool and add it to the string
        $str .= $pool[mt_rand(0, $max)];
    }

    // Make sure alnum strings contain at least one letter and one digit
    if ($type === 'alnum' AND $length > 1) {
        if (ctype_alpha($str)) {
            // Add a random digit
            $str[mt_rand(0, $length - 1)] = chr(mt_rand(48, 57));
        } elseif (ctype_digit($str)) {
            // Add a random letter
            $str[mt_rand(0, $length - 1)] = chr(mt_rand(65, 90));
        }
    }

    return $str;
}

public static reduce_slashes( string $str ) (defined in Kohana_Text)

Reduces multiple slashes in a string to single slashes.

$str = Text::reduce_slashes('foo//bar/baz'); // "foo/bar/baz"

Parameters

  • string $str required - String to reduce slashes of

Return Values

  • string

Source Code

public static function reduce_slashes($str)
{
    return preg_replace('#(?<!:)//+#', '/', $str);
}

public static similar( array $words ) (defined in Kohana_Text)

Finds the text that is similar between a set of words.

$match = Text::similar(['fred', 'fran', 'free']); // "fr"

Parameters

  • array $words required - Words to find similar text of

Return Values

  • string

Source Code

public static function similar(array $words)
{
    // First word is the word to match against
    $word = current($words);

    for ($i = 0, $max = strlen($word); $i < $max; ++$i) {
        foreach ($words as $w) {
            // Once a difference is found, break out of the loops
            if (!isset($w[$i]) OR $w[$i] !== $word[$i])
                break 2;
        }
    }

    // Return the similar text
    return substr($word, 0, $i);
}

public static ucfirst( string $string [, string $delimiter = string(1) "-" ] ) (defined in Kohana_Text)

Uppercase words that are not separated by spaces, using a custom delimiter or the default.

 $str = Text::ucfirst('content-type'); // returns "Content-Type"

Parameters

  • string $string required - String to transform
  • string $delimiter = string(1) "-" - Delimiter to use

Tags

Return Values

  • string

Source Code

public static function ucfirst($string, $delimiter = '-')
{
    // Put the keys back the Case-Convention expected
    return implode($delimiter, array_map('UTF8::ucfirst', explode($delimiter, $string)));
}

public static user_agent( string $agent , mixed $value ) (defined in Kohana_Text)

Returns information about the client user agent.

// Returns "Chrome" when using Google Chrome
$browser = Text::user_agent($agent, 'browser');

Multiple values can be returned at once by using an array:

// Get the browser and platform with a single call
$info = Text::user_agent($agent, ['browser', 'platform']);

When using an array for the value, an associative array will be returned.

Parameters

  • string $agent required - User_agent
  • mixed $value required - Array or string to return: browser, version, robot, mobile, platform

Tags

Return Values

  • mixed - Requested information, false if nothing is found

Source Code

public static function user_agent($agent, $value)
{
    if (is_array($value)) {
        $data = [];
        foreach ($value as $part) {
            // Add each part to the set
            $data[$part] = Text::user_agent($agent, $part);
        }

        return $data;
    }

    if ($value === 'browser' OR $value == 'version') {
        // Extra data will be captured
        $info = [];

        // Load browsers
        $browsers = Kohana::$config->load('user_agents')->browser;

        foreach ($browsers as $search => $name) {
            if (stripos($agent, $search) !== false) {
                // Set the browser name
                $info['browser'] = $name;

                if (preg_match('#' . preg_quote($search) . '[^0-9.]*+([0-9.][0-9.a-z]*)#i', $agent, $matches)) {
                    // Set the version number
                    $info['version'] = $matches[1];
                } else {
                    // No version number found
                    $info['version'] = false;
                }

                return $info[$value];
            }
        }
    } else {
        // Load the search group for this type
        $group = Kohana::$config->load('user_agents')->$value;

        foreach ($group as $search => $name) {
            if (stripos($agent, $search) !== false) {
                // Set the value name
                return $name;
            }
        }
    }

    // The value requested could not be found
    return false;
}

public static widont( string $str ) (defined in Kohana_Text)

Prevents widow words by inserting a non-breaking space between the last two words.

echo Text::widont($text);

regex courtesy of the Typogrify project

Parameters

  • string $str required - Text to remove widows from

Tags

  • Link -

Return Values

  • string

Source Code

public static function widont($str)
{
    // use '%' as delimiter and 'x' as modifier
    $widont_regex = "%
(?:</?(?:a|em|span|strong|i|b)[^>]*>)|[^<>\s]) # must be proceeded by an approved inline opening or closing tag or a nontag/nonspace
s+                                             # the space to replace
[^<>\s]+                                       # must be flollowed by non-tag non-space characters
s*                                             # optional white space!
</(a|em|span|strong|i|b)>\s*)*                 # optional closing inline tags with optional white space after each
(</(p|h[1-6]|li|dt|dd)>)|$))                   # end with a closing p, h1-6, li or the end of the string
";
    return preg_replace($widont_regex, '$1&nbsp;$2', $str);
}

Source Code

protected static function _auto_link_emails_callback($matches)
{
    return HTML::mailto($matches[0]);
}

Source Code

protected static function _auto_link_urls_callback1($matches)
{
    return HTML::anchor($matches[0]);
}

Source Code

protected static function _auto_link_urls_callback2($matches)
{
    return HTML::anchor('http://' . $matches[0], $matches[0]);
}