Str Class

The Str class is a set of methods to help with the manipulation of strings.

The class also contains multibyte agnostic versions of PHP's multibyte-aware functions in category 2, as defined on this page. They are drop-in replacements for both versions. For example, you can replace both strlen() and mb_strlen() with Str::strlen(), which will return a multi-byte aware result based on whether or not PHP's mbstring extension is loaded.

The php.ini setting mbstring.func_overload is not supported by FuelPHP. The framework refuses to start when it is set!

increment($str, $first = 1)

The increment method allows you to append a number to the end of a string or increment that number if it already exists.

Static Yes
Parameters
Param Default Description
$string required The string to increment.
$first 
1
 The first number to increment with.
Returns string
Example 
$string = "filename";
Str::increment($string); // returns filename_1

$string = "filename_1";
Str::increment($string); // returns filename_2

$string = "filename";
Str::increment($string, 3); // returns filename_3

random($type = 'alnum', $length = 8)

The random method generates a random string based on the type given.

Static Yes
Parameters
Param Default Description
$type alnum The type of string to generate. Your choices are alnum, numeric, nozero, alpha, distinct, hexdec, unique, sha1 and uuid.
$length 
16
 The number of characters you would like the final string to be (unique, sha1 and uuid ignore this parameter).
Returns string
Example 
// alnum (uppercase and lowercase letters mixed with numbers)
Str::random('alnum', 16);
// Returns: SvZi9Dh3lq7zQYim

// numeric (just numbers)
Str::random('numeric', 16);
// Returns: 1045343964672481

// nozero (just numbers excluding zero)
Str::random('nozero', 16);
// Returns: 3244623373994515

// alpha (just uppercase and lowercase letters)
Str::random('alpha', 16);
// Returns: LuVAXbmxQbbWoYqz

// distinct (uppercase letters and numbers that cannot be confused)
Str::random('distinct', 16);
// Returns: R79MPKMH4KTRN35J

// hexdec (hexadecimal characters a-f, 0-9)
Str::random('hexdec', 16);
// Returns: 09c34e42f36547f8

// unique (32 character string based on md5)
Str::random('unique');
// Returns: ed4bb844a35b7a4edb7eed0d3795d328

// sha1 (40 character string based on sha1)
Str::random('sha1');
// Returns: af5c5a8cc3be9a3180205c1ed2975015cd6cf1e7

// uuid (version 4 - random)
Str::random('uuid');
// Returns: f47ac10b-58cc-4372-a567-0e02b2c3d479

truncate($string, $limit, $continuation = '...', $is_html = false)

The truncate method allows you to limit characters and provide a continuation string without breaking html.

Static Yes
Parameters
Param Default Description
$string required The string to truncate.
$limit required The number of characters to allow in the string.
$continuation 
'...'
 The string to append to the end of the truncated string.
$is_html 
false
 If the string contains html. Setting this as true will make the method not break html.
Returns string
Example 
$string = "Lorem ipsum dolor sit amet, consectetur adipiscing elit.";
Str::truncate($string, 15); // returns Lorem ipsum dol...

$string = "Lorem ipsum dolor sit amet, consectetur adipiscing elit.";
Str::truncate($string, 15, '...Read More'); // returns Lorem ipsum dol...Read More

alternator(*$args)

Returns a closure that will alternate the values you've passed to this method as arguments, unless you call the closure with false as argument - in which case it will just return the value without moving to the next and return the same value on the next call.

Static Yes
Parameters
Param Default Description
*$args required As many arguments as you need to alternate
Returns Closure
Example 
$alt = Str::alternator('one', 'two', 'three', 'four');
echo $alt(); // outputs 'one'
echo $alt(); // outputs 'two'
echo $alt(false); // outputs 'three', but doens't move to the next as you can see in the next call
echo $alt(); // outputs 'three'
echo $alt(); // outputs 'four'
echo $alt(); // outputs 'one'
// etc...

tr($string, $array = array())

The tr method parse the params from given string using PHP's strtr().

Static Yes
Parameters
Param Type Default Description
$string string Required The input string.
$array array 
array()
 params to str_replace.
Returns string
Example 
Str::tr('Hello :name', array('name' => 'World')); // returns 'Hello World'

is_json($string)

The is_json method check if a string is json encoded.

Static Yes
Parameters
Param Type Default Description
$string string Required The input string.
Returns bool
Example 
Str::is_json('{"0":"An","encoded":["string"]}'); // returns true

is_serialized($string)

The is_serialized method check if a string is serialized.

Static Yes
Parameters
Param Type Default Description
$string string Required The input string.
Returns bool
Example 
Str::is_serialized('a:2:{i:0;s:2:"An";s:7:"encoded";a:1:{i:0;s:6:"string";}}');
// returns true

is_html($string)

The is_html method check if a string is html.

Static Yes
Parameters
Param Type Default Description
$string string Required The input string.
Returns bool
Example 
Str::is_html('Lorem ipsum <b>dolor sit amet</b>, consectetur <u>adipiscing</u> elit.');
// returns true

is_xml($string)

The is_xml method check if a string is a valid xml. Requires the libxml extension.

Static Yes
Parameters
Param Type Default Description
$string string Required The input string.
Returns bool
Example 
Str::is_xml('<?xml version="1.0" encoding="utf-8"?><xml><foo>bar</foo></xml>');
// returns true

starts_with($str, $start, $ignore_case = false)

The starts_with method checks whether a string has a precific beginning.

Static Yes
Parameters
Param Default Description
$str required The string to check.
$start required The beginning to check for.
$ignore_case 
false
 Whether to ignore the case.
Returns bool
Example 
$string = "Lorem ipsum dolor sit amet";

Str::starts_with($string, 'Lorem'); // returns true
Str::starts_with($string, 'lorem'); // returns false
Str::starts_with($string, 'lorem', true); // returns true

ends_with($str, $end, $ignore_case = false)

The ends_with method checks whether or not a string has a precific ending.

Static Yes
Parameters
Param Default Description
$str required The string to check.
$end required The ending to check for.
$ignore_case 
false
 Whether to ignore the case.
Returns bool
Example 
$string = "Lorem ipsum dolor sit amet";

Str::ends_with($string, 'amet'); // returns true
Str::ends_with($string, 'Amet'); // returns false
Str::ends_with($string, 'Amet', true); // returns true

number_format($num, $decimals = null, $thousands_separator = null, $decimal_separator = null, $currency_symbol = false)

The number_format is virtually identical to the PHP built-in function with the same name, but it also supports a currency symbol, and it uses information from the current locale to determine the value for fields which are null.

Note that in the argument list, the thousand and decimal separator are the other way around compared to the PHP built-in function, because it happens more often that the thousand separator needs to be supressed.

Static Yes
Parameters
Param Default Description
$num required The float value to format.
$decimals 
null
 The ending to check for.
$thousands_separator 
null
 Thousand separator to use.
$decimal_separator 
null
 Decimal separator to use.
$currency_symbol 
null
 Currency Symbol to use. If null, information from the current the locale will be used. By default, it is false, and no currency info will added to the number.
Returns bool
Example 
$num = 123456.789;

setlocale(LC_ALL, 'nl_NL.UTF-8');
echo Str::number_format($num);                          // will return "123456,79"
echo Str::number_format($num, null, null, null, "EUR"); // will return "EUR 123.456,789"
echo Str::number_format($num, 3, "");                   // will return "€ 123456,789"

setlocale(LC_ALL, 'en_US.UTF-8');
echo Str::number_format($num);                          // will return "123,456.79"
echo Str::number_format($num, 3, "");                   // will return "123456.789"
echo Str::number_format($num, 3, null, null, null);     // will return "$123,456.789"