Stringy
A PHP string manipulation library with multibyte support
- - - - -Stringy
A PHP library with a variety of string manipulation functions with multibyte support. Offers both OO method chaining and a procedural-style static wrapper. Compatible with PHP 5.3+. Inspired by underscore.string.js.
-
-
-
- Requiring/Loading @@ -79,13 +88,13 @@
- safeTruncate
- shuffle
- slugify -
- standardize
- startsWith
- substr
- surround
- swapCase
- tidy
- titleize +
- toAscii
- toSpaces
- toTabs
- trim @@ -152,7 +161,7 @@ public, and can be accessed directly if required, ie:
S::create('foo')->
Methods
In the list below, any static method other than S::create refers to a
-method in Stringy\StaticStringy. For all others, they're found in Stringy\Stringy. Furthermore, all methods that return an object of type Stringy return a new object, and do not modify the original.
+method in Stringy\StaticStringy. For all others, they're found in Stringy\Stringy. Furthermore, all methods that return a Stringy object or string do not modify the original.
Note: If $encoding is not given, it defaults to mb_internal_encoding().
@@ -163,7 +172,7 @@ method in Stringy\StaticStringy. For all others, they're found in Stringy\String
S::substr(int $index [, string $encoding ])
-Gets the character of $str at $index, with indexes starting at 0.
+Returns the character of the string at $index, with indexes starting at 0.
S::create('fòô bàř', 'UTF-8')->at(6);
S::at('fòô bàř', 6, 'UTF-8'); // 'ř'
@@ -176,9 +185,9 @@ method in Stringy\StaticStringy. For all others, they're found in Stringy\String
S::camelize(string $str [, string $encoding ])
-Returns a camelCase version of a supplied string, with multibyte support.
-Trims surrounding spaces, capitalizes letters following digits, spaces,
-dashes and underscores, and removes spaces, dashes, underscores.
+Returns a camelCase version of the supplied string. Trims surrounding
+spaces, capitalizes letters following digits, spaces, dashes and
+underscores, and removes spaces, dashes, underscores.
S::create('Camel-Case')->camelize();
S::camelize('Camel-Case'); // 'camelCase'
@@ -192,7 +201,7 @@ dashes and underscores, and removes spaces, dashes, underscores.
S::collapseWhitespace(string $str)
Trims the string and replaces consecutive whitespace characters with a
-single space. This inclues tabs and newline characters.
+single space. This includes tabs and newline characters.
S::create(' Ο συγγραφέας ')->collapseWhitespace();
S::collapseWhitespace(' Ο συγγραφέας '); // 'Ο συγγραφέας'
@@ -205,7 +214,7 @@ single space. This inclues tabs and newline characters.
S::contains(string $haystack, string $needle [, string $encoding ])
-Returns true if $haystack contains $needle, false otherwise.
+Returns true if the string contains $needle, false otherwise.
S::create('Ο συγγραφέας είπε', 'UTF-8')->contains('συγγραφέας');
S::contains('Ο συγγραφέας είπε', 'συγγραφέας', 'UTF-8'); // true
@@ -218,7 +227,7 @@ single space. This inclues tabs and newline characters.
S::count(string $str, string $substring [, string $encoding ])
-Returns the number of occurences of $substring in $str. An alias for
+
Returns the number of occurrences of $substring in the given string. An alias for
mb_substr_count()
S::create('Ο συγγραφέας είπε', 'UTF-8')->count('α');
@@ -228,13 +237,13 @@ mb_substr_count()
create
-$stringy = S::create(string $str, [, $encoding ])
+S::create(string $str, [, $encoding ])
Creates a Stringy object and assigns both str and encoding properties
the supplied values. If $encoding is not specified, it defaults to
-mb_internal_encoding(). It then returns the instantiated object.
+mb_internal_encoding(). It then returns the initialized object.
-S::create('fòô bàř', 'UTF-8'); // 'fòô bàř'
+$stringy = S::create('fòô bàř', 'UTF-8'); // 'fòô bàř'
@@ -244,10 +253,9 @@ mb_internal_encoding(). It then returns the instantiated object.
S::dasherize(string $str [, string $encoding ])
-Returns a lowercase and trimmed string seperated by dashes, with
-multibyte support. Dashes are inserted before uppercase characters
-(with the exception of the first character of the string), and in place
-of spaces as well as underscores.
+Returns a lowercase and trimmed string separated by dashes. Dashes are
+inserted before uppercase characters (with the exception of the first
+character of the string), and in place of spaces as well as underscores.
S::create('TestDCase')->dasherize();
S::dasherize('TestDCase'); // 'test-d-case'
@@ -260,9 +268,9 @@ of spaces as well as underscores.
S::endsWith(string $str, string $substring [, boolean $caseSensitive = true [, string $encoding ]])
-Returns true if the string $str ends with $substring, false otherwise.
-By default, the comparison is case-sensitive, but can be made insensitive
-by setting $caseSensitive to false.
+Returns true if the string ends with $substring, false otherwise. By
+default, the comparison is case-sensitive, but can be made insensitive by
+setting $caseSensitive to false.
S::create('FÒÔ bàřs', 'UTF-8')->endsWith('àřs', true);
S::endsWith('FÒÔ bàřs', 'àřs', true, 'UTF-8'); // true
@@ -275,7 +283,7 @@ by setting $caseSensitive to false.
S::ensureLeft(string $substring [, string $encoding ])
-Ensures that $str begins with $substring.
+Ensures that the string begins with $substring. If it doesn't, it's prepended.
S::create('foobar')->ensureLeft('http://');
S::ensureLeft('foobar', 'http://'); // 'http://foobar'
@@ -288,7 +296,7 @@ by setting $caseSensitive to false.
S::ensureRight(string $substring [, string $encoding ])
-Ensures that $str ends with $substring.
+Ensures that the string begins with $substring. If it doesn't, it's appended.
S::create('foobar')->ensureRight('.com');
S::ensureRight('foobar', '.com'); // 'foobar.com'
@@ -301,7 +309,7 @@ by setting $caseSensitive to false.
S::first(int $n [, string $encoding ])
-Gets the first $n characters of $str.
+Returns the first $n characters of the string.
S::create('fòô bàř', 'UTF-8')->first(3);
S::first('fòô bàř', 3, 'UTF-8'); // 'fòô'
@@ -314,8 +322,8 @@ by setting $caseSensitive to false.
S::humanize(string $str [, string $encoding ])
-Capitalizes the first word of a string, replaces underscores with spaces,
-and strips '_id'.
+Capitalizes the first word of the string, replaces underscores with
+spaces, and strips '_id'.
S::create('author_id')->humanize();
S::humanize('author_id'); // 'Author'
@@ -328,7 +336,7 @@ and strips '_id'.
S::insert(string $str, int $index, string $substring [, string $encoding ])
-Inserts $substring into $str at the $index provided.
+Inserts $substring into the string at the $index provided.
S::create('fòô bà', 'UTF-8')->insert('ř', 6);
S::insert('fòô bà', 'ř', 6, 'UTF-8'); // 'fòô bàř'
@@ -341,7 +349,7 @@ and strips '_id'.
S::isAlpha(string $str [, string $encoding ])
-Returns true if $str contains only alphabetic chars, false otherwise.
+Returns true if the string contains only alphabetic chars, false otherwise.
S::create('丹尼爾', 'UTF-8')->isAlpha();
S::isAlpha('丹尼爾', 'UTF-8'); // true
@@ -354,7 +362,7 @@ and strips '_id'.
S::isAlphanumeric(string $str [, string $encoding ])
-Returns true if $str contains only alphabetic and numeric chars, false
+
Returns true if the string contains only alphabetic and numeric chars, false
otherwise.
S::create('دانيال1', 'UTF-8')->isAlphanumeric();
@@ -368,7 +376,7 @@ otherwise.
S::isBlank(string $str [, string $encoding ])
-Returns true if $str contains only whitespace chars, false otherwise.
+Returns true if the string contains only whitespace chars, false otherwise.
S::create("\n\t \v\f")->isBlank();
S::isBlank("\n\t \v\f"); // true
@@ -381,7 +389,7 @@ otherwise.
S::isLowerCase(string $str [, string $encoding ])
-Returns true if $str contains only lower case chars, false otherwise.
+Returns true if the string contains only lower case chars, false otherwise.
S::create('fòô bàř', 'UTF-8')->isLowerCase();
S::isLowerCase('fòô bàř', 'UTF-8'); // true
@@ -394,7 +402,7 @@ otherwise.
S::isUpperCase(string $str [, string $encoding ])
-Returns true if $str contains only upper case chars, false otherwise.
+Returns true if the string contains only upper case chars, false otherwise.
S::create('FÒÔBÀŘ',, 'UTF-8')->isUpperCase();
S::isUpperCase('FÒÔBÀŘ',, 'UTF-8'); // true
@@ -407,7 +415,7 @@ otherwise.
S::last(int $n [, string $encoding ])
-Gets the last $n characters of $str.
+Returns the last $n characters of the string.
S::create('fòô bàř', 'UTF-8')->last(3);
S::last('fòô bàř', 3, 'UTF-8'); // 'bàř'
@@ -420,7 +428,7 @@ otherwise.
S::length(string $str [, string $encoding ])
-Returns the length of $str. An alias for PHP's mb_strlen() function.
+Returns the length of the string. An alias for PHP's mb_strlen() function.
S::create('fòô bàř', 'UTF-8')->length();
S::length('fòô bàř', 'UTF-8'); // 7
@@ -433,7 +441,7 @@ otherwise.
S::longestCommonPrefix(string $str, string $otherStr [, $encoding ])
-Finds the longest common prefix between $str and $otherStr.
+Returns the longest common prefix between the string and $otherStr.
S::create('fòô bar', 'UTF-8')->longestCommonPrefix('fòr bar');
S::longestCommonPrefix('fòô bar', 'fòr bar', 'UTF-8'); // 'fò'
@@ -446,7 +454,7 @@ otherwise.
S::longestCommonSuffix(string $str, string $otherStr [, $encoding ])
-Finds the longest common suffix between $str and $otherStr.
+Returns the longest common suffix between the string and $otherStr.
S::create('fòô bàř', 'UTF-8')->longestCommonSuffix('fòr bàř');
S::longestCommonSuffix('fòô bàř', 'fòr bàř', 'UTF-8'); // ' bàř'
@@ -459,8 +467,8 @@ otherwise.
S::longestCommonSubstring(string $str, string $otherStr [, $encoding ])
-Finds the longest common substring between $str and $otherStr. In the
-case of ties, returns that which occurs first.
+Returns the longest common substring between the string and $otherStr. In the
+case of ties, it returns that which occurs first.
S::create('foo bar')->longestCommonSubstring('boo far');
S::longestCommonSubstring('foo bar', 'boo far'); // 'oo '
@@ -473,8 +481,7 @@ case of ties, returns that which occurs first.
S::lowerCaseFirst(string $str [, string $encoding ])
-Converts the first character of the supplied string to lower case, with
-support for multibyte strings.
+Converts the first character of the supplied string to lower case.
S::create('Σ test', 'UTF-8')->lowerCaseFirst();
S::lowerCaseFirst('Σ test', 'UTF-8'); // 'σ test'
@@ -487,11 +494,11 @@ support for multibyte strings.
S::pad(string $str , int $length [, string $padStr = ' ' [, string $padType = 'right' [, string $encoding ]]])
-Pads a string to a given length with another string. If length is less
-than or equal to the length of $str, then no padding takes places. The
-default string used for padding is a space, and the default type (one of
-'left', 'right', 'both') is 'right'. Throws an exception if $padType
-isn't one of those 3 values.
+Pads the string to a given length with $padStr. If length is less than
+or equal to the length of the string, no padding takes places. The default
+string used for padding is a space, and the default type (one of 'left',
+'right', 'both') is 'right'. Throws an InvalidArgumentException if
+$padType isn't one of those 3 values.
S::create('fòô bàř', 'UTF-8')->pad( 10, '¬ø', 'left',);
S::pad('fòô bàř', 10, '¬ø', 'left', 'UTF-8'); // '¬ø¬fòô bàř'
@@ -505,7 +512,7 @@ isn't one of those 3 values.
S::padBoth(string $str , int $length [, string $padStr = ' ' [, string $encoding ]])
Returns a new string of a given length such that both sides of the string
-string are padded. Alias for pad($str, $length, $padStr, 'both', $encoding)
+string are padded. Alias for pad() with a $padType of 'both'.
S::create('foo bar')->padBoth(9, ' ');
S::padBoth('foo bar', 9, ' '); // ' foo bar '
@@ -519,7 +526,7 @@ string are padded. Alias for pad($str, $length, $padStr, 'both', $encoding)
S::padLeft(string $str , int $length [, string $padStr = ' ' [, string $encoding ]])
Returns a new string of a given length such that the beginning of the
-string is padded. Alias for pad($str, $length, $padStr, 'left', $encoding)
+string is padded. Alias for pad() with a $padType of 'left'.
S::create($str, $encoding)->padLeft($length, $padStr);
S::padLeft('foo bar', 9, ' '); // ' foo bar'
@@ -533,7 +540,7 @@ string is padded. Alias for pad($str, $length, $padStr, 'left', $encoding)
S::padRight(string $str , int $length [, string $padStr = ' ' [, string $encoding ]])
Returns a new string of a given length such that the end of the string is
-padded. Alias for pad($str, $length, $padStr, 'right', $encoding)
+padded. Alias for pad() with a $padType of 'right'.
S::create('foo bar')->padRight(10, '_*');
S::padRight('foo bar', 10, '_*'); // 'foo bar_*_'
@@ -546,7 +553,7 @@ padded. Alias for pad($str, $length, $padStr, 'right', $encoding)
S::removeLeft(string $str, string $substring [, string $encoding ])
-Removes the prefix $substring if present.
+Returns a new string with the prefix $substring removed, if it was present.
S::create('fòô bàř', 'UTF-8')->removeLeft('fòô ');
S::removeLeft('fòô bàř', 'fòô ', 'UTF-8'); // 'bàř'
@@ -559,7 +566,7 @@ padded. Alias for pad($str, $length, $padStr, 'right', $encoding)
S::removeRight(string $str, string $substring [, string $encoding ])
-Removes the suffix $substring if present.
+Returns a new string with the suffix $substring removed, if it was present.
S::create('fòô bàř', 'UTF-8')->removeRight(' bàř');
S::removeRight('fòô bàř', ' bàř', 'UTF-8'); // 'fòô'
@@ -572,7 +579,7 @@ padded. Alias for pad($str, $length, $padStr, 'right', $encoding)
S::replace(string $str, string $search, string $replace [, string $encoding ])
-Replaces all occurrences of $search with $replace in $str.
+Returns a string with all occurrences of $search replaced with $replace.
S::create('fòô bàř fòô bàř', 'UTF-8')->replace('fòô ', '');
S::replace('fòô bàř fòô bàř', 'fòô ', '', 'UTF-8'); // 'bàř bàř'
@@ -585,7 +592,7 @@ padded. Alias for pad($str, $length, $padStr, 'right', $encoding)
S::reverse(string $str, [, string $encoding ])
-Reverses a string. A multibyte version of strrev.
+Returns a reversed string. A multibyte version of strrev().
S::create('fòô bàř', 'UTF-8')->reverse();
S::reverse('fòô bàř', 'UTF-8'); // 'řàb ôòf'
@@ -614,8 +621,7 @@ exceeding the desired length.
S::shuffle(string $str [, string $encoding ])
-A multibyte str_shuffle function. It randomizes the order of characters
-in a string.
+A multibyte str_shuffle() function. It returns a string with its characters in random order.
S::create('fòô bàř', 'UTF-8')->shuffle();
S::shuffle('fòô bàř', 'UTF-8'); // 'àôřb òf'
@@ -628,28 +634,15 @@ in a string.
S::slugify(string $str)
-Converts the supplied text into an URL slug. This includes replacing
-non-ASCII characters with their closest ASCII equivalents, removing
-non-alphanumeric and non-ASCII characters, and replacing whitespace with
-dashes. The string is also converted to lowercase.
+Converts the string into an URL slug. This includes replacing non-ASCII
+characters with their closest ASCII equivalents, removing non-alphanumeric
+and non-ASCII characters, and replacing whitespace with dashes. The string
+is also converted to lowercase.
S::create('Using strings like fòô bàř')->slugify();
S::slugify('Using strings like fòô bàř'); // 'using-strings-like-foo-bar'
-
-standardize
-
-$stringy->standardize()
-
-S::standardize(string $str)
-
-Converts some non-ASCII characters to their closest ASCII counterparts.
-
-S::create('fòô bàř')->standardize();
-S::standardize('fòô bàř'); // 'foo bar'
-
-
startsWith
@@ -657,7 +650,7 @@ dashes. The string is also converted to lowercase.
S::startsWith(string $str, string $substring [, boolean $caseSensitive = true [, string $encoding ]])
-Returns true if the string $str begins with $substring, false otherwise.
+
Returns true if the string begins with $substring, false otherwise.
By default, the comparison is case-sensitive, but can be made insensitive
by setting $caseSensitive to false.
@@ -672,7 +665,7 @@ by setting $caseSensitive to false.
S::substr(string $str, int $start [, int $length [, string $encoding ]])
-Gets the substring of $str beginning at $start with the specified $length.
+
Returns the substring beginning at $start with the specified $length.
It differs from the mb_substr() function in that providing a $length of
null will return the rest of the string, rather than an empty string.
@@ -700,7 +693,7 @@ null will return the rest of the string, rather than an empty string.
S::swapCase(string $str [, string $encoding ])
-Returns a case swapped version of a string.
+Returns a case swapped version of the string.
S::create('Ντανιλ', 'UTF-8')->swapCase();
S::swapCase('Ντανιλ', 'UTF-8'); // 'νΤΑΝΙΛ'
@@ -713,8 +706,8 @@ null will return the rest of the string, rather than an empty string.
S::tidy(string $str)
-Replaces smart quotes, ellipsis characters, and dashes from Windows-1252
-(and commonly used in Word documents) with their ASCII equivalents.
+Returns a string with smart quotes, ellipsis characters, and dashes from
+Windows-1252 (commonly used in Word documents) replaced by their ASCII equivalents.
S::create('“I see…”')->tidy();
S::tidy('“I see…”'); // '"I see..."'
@@ -727,7 +720,7 @@ null will return the rest of the string, rather than an empty string.
S::titleize(string $str [, array $ignore [, string $encoding ]])
-Capitalizes the first letter of each word in a string, after trimming.
+
Returns a trimmed string with the first letter of each word capitalized.
Ignores the case of other letters, allowing for the use of acronyms.
Also accepts an array, $ignore, allowing you to list words not to be
capitalized.
@@ -738,6 +731,20 @@ capitalized.
// 'I Like to Watch DVDs at Home'
+
+toAscii
+
+$stringy->toAscii()
+
+S::toAscii(string $str)
+
+Returns an ASCII version of the string. A set of non-ASCII characters are
+replaced with their closest ASCII counterparts, and the rest are removed.
+
+S::create('fòô bàř')->toAscii();
+S::toAscii('fòô bàř'); // 'foo bar'
+
+
toSpaces
@@ -745,7 +752,7 @@ capitalized.
S::toSpaces(string $str, [, int $tabLength = 4 ])
-Converts each tab in a string to some number of spaces, as defined by
+
Converts each tab in the string to some number of spaces, as defined by
$tabLength. By default, each tab is converted to 4 consecutive spaces.
S::create(' String speech = "Hi"')->toSpaces();
@@ -759,7 +766,7 @@ $tabLength. By default, each tab is converted to 4 consecutive spaces.
S::toTabs(string $str, [, int $tabLength = 4 ])
-Converts each occurence of some consecutive number of spaces, as defined
+
Converts each occurrence of some consecutive number of spaces, as defined
by $tabLength, to a tab. By default, each 4 consecutive spaces are
converted to a tab.
@@ -774,7 +781,7 @@ converted to a tab.
S::trim(string $str)
-Trims $str. An alias for PHP's trim() function.
+Returns the trimmed string. An alias for PHP's trim() function.
S::create('fòô bàř', 'UTF-8')->trim();
S::trim(' fòô bàř '); // 'fòô bàř'
@@ -787,7 +794,7 @@ converted to a tab.
S::truncate(string $str, int $length, [, string $substring = '' [, string $encoding ]])
-Truncates $str to a given length. If $substring is provided, and
+
Truncates the string to a given length. If $substring is provided, and
truncating occurs, the string is further truncated so that the substring
may be appended without exceeding the desired length.
@@ -802,10 +809,9 @@ may be appended without exceeding the desired length.
S::underscored(string $str [, string $encoding ])
-Returns a lowercase and trimmed string seperated by underscores, with
-multibyte support. Underscores are inserted before uppercase characters
-(with the exception of the first character of the string), and in place
-of spaces as well as dashes.
+Returns a lowercase and trimmed string separated by underscores.
+Underscores are inserted before uppercase characters (with the exception
+of the first character of the string), and in place of spaces as well as dashes.
S::create('TestUCase')->underscored();
S::underscored('TestUCase'); // 'test_u_case'
@@ -818,9 +824,9 @@ of spaces as well as dashes.
S::upperCamelize(string $str [, string $encoding ])
-Returns an UpperCamelCase version of a supplied string, with multibyte
-support. Trims surrounding spaces, capitalizes letters following digits,
-spaces, dashes and underscores, and removes spaces, dashes, underscores.
+Returns an UpperCamelCase version of the supplied string. It trims
+surrounding spaces, capitalizes letters following digits, spaces, dashes
+and underscores, and removes spaces, dashes, underscores.
S::create('Upper Camel-Case')->upperCamelize();
S::upperCamelize('Upper Camel-Case'); // 'UpperCamelCase'
@@ -833,8 +839,7 @@ spaces, dashes and underscores, and removes spaces, dashes, underscores.
S::upperCaseFirst(string $str [, string $encoding ])
-Converts the first character of the supplied string to upper case, with
-support for multibyte strings.
+Converts the first character of the supplied string to upper case.
S::create('σ test', 'UTF-8')->upperCaseFirst();
S::upperCaseFirst('σ test', 'UTF-8'); // 'Σ test'
@@ -851,11 +856,11 @@ support for multibyte strings.
Released under the MIT License - see LICENSE.txt for details.
-
+