$str
$str : string
An instance's string.
$str : string
An instance's string.
$encoding : string
The string's encoding, which should be one of the mbstring module's supported encodings.
__construct(mixed $str = '', string $encoding = null) : mixed
Initializes a Stringy object and assigns both str and encoding properties the supplied values. $str is cast to a string prior to assignment, and if $encoding is not specified, it defaults to mb_internal_encoding(). Throws an InvalidArgumentException if the first argument is an array or object without a __toString method.
| mixed | $str | Value to modify, after being cast to string |
| string | $encoding | The character encoding |
if an array or object without a __toString method is passed as the first argument
create(mixed $str = '', string $encoding = null) : static
Creates a Stringy object and assigns both str and encoding properties the supplied values. $str is cast to a string prior to assignment, and if $encoding is not specified, it defaults to mb_internal_encoding(). It then returns the initialized object. Throws an InvalidArgumentException if the first argument is an array or object without a __toString method.
| mixed | $str | Value to modify, after being cast to string |
| string | $encoding | The character encoding |
if an array or object without a __toString method is passed as the first argument
A Stringy object
between(string $start, string $end, int $offset) : static
Returns the substring between $start and $end, if found, or an empty string. An optional offset may be supplied from which to begin the search for the start string.
| string | $start | Delimiter marking the start of the substring |
| string | $end | Delimiter marking the end of the substring |
| int | $offset | Index from which to begin the search |
Object whose $str is a substring between $start and $end
collapseWhitespace() : static
Trims the string and replaces consecutive whitespace characters with a single space. This includes tabs and newline characters, as well as multibyte whitespace such as the thin space and ideographic space.
Object with a trimmed $str and condensed whitespace
contains(string $needle, bool $caseSensitive = true) : bool
Returns true if the string contains $needle, false otherwise. By default the comparison is case-sensitive, but can be made insensitive by setting $caseSensitive to false.
| string | $needle | Substring to look for |
| bool | $caseSensitive | Whether or not to enforce case-sensitivity |
Whether or not $str contains $needle
containsAll(string[] $needles, bool $caseSensitive = true) : bool
Returns true if the string contains all $needles, false otherwise. By default the comparison is case-sensitive, but can be made insensitive by setting $caseSensitive to false.
| string[] | $needles | Substrings to look for |
| bool | $caseSensitive | Whether or not to enforce case-sensitivity |
Whether or not $str contains $needle
containsAny(string[] $needles, bool $caseSensitive = true) : bool
Returns true if the string contains any $needles, false otherwise. By default the comparison is case-sensitive, but can be made insensitive by setting $caseSensitive to false.
| string[] | $needles | Substrings to look for |
| bool | $caseSensitive | Whether or not to enforce case-sensitivity |
Whether or not $str contains $needle
countSubstr(string $substring, bool $caseSensitive = true) : int
Returns the number of occurrences of $substring in the given string.
By default, the comparison is case-sensitive, but can be made insensitive by setting $caseSensitive to false.
| string | $substring | The substring to search for |
| bool | $caseSensitive | Whether or not to enforce case-sensitivity |
The number of $substring occurrences
delimit(string $delimiter) : static
Returns a lowercase and trimmed string separated by the given delimiter.
Delimiters are inserted before uppercase characters (with the exception of the first character of the string), and in place of spaces, dashes, and underscores. Alpha delimiters are not converted to lowercase.
| string | $delimiter | Sequence used to separate parts of the string |
Object with a delimited $str
endsWith(string $substring, bool $caseSensitive = true) : bool
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.
| string | $substring | The substring to look for |
| bool | $caseSensitive | Whether or not to enforce case-sensitivity |
Whether or not $str ends with $substring
endsWithAny(string[] $substrings, bool $caseSensitive = true) : bool
Returns true if the string ends with any of $substrings, false otherwise.
By default, the comparison is case-sensitive, but can be made insensitive by setting $caseSensitive to false.
| string[] | $substrings | Substrings to look for |
| bool | $caseSensitive | Whether or not to enforce case-sensitivity |
Whether or not $str ends with $substring
getIterator() : \ArrayIterator
Returns a new ArrayIterator, thus implementing the IteratorAggregate interface. The ArrayIterator's constructor is passed an array of chars in the multibyte string. This enables the use of foreach with instances of Stringy\Stringy.
An iterator for the characters in the string
htmlDecode(int|null $flags = ENT_COMPAT) : static
Convert all HTML entities to their applicable characters. An alias of html_entity_decode. For a list of flags, refer to http://php.net/manual/en/function.html-entity-decode.php
| int|null | $flags | Optional flags |
Object with the resulting $str after being html decoded.
htmlEncode(int|null $flags = ENT_COMPAT) : static
Convert all applicable characters to HTML entities. An alias of htmlentities. Refer to http://php.net/manual/en/function.htmlentities.php for a list of flags.
| int|null | $flags | Optional flags |
Object with the resulting $str after being html encoded.
indexOf(string $needle, int $offset) : int|bool
Returns the index of the first occurrence of $needle in the string, and false if not found. Accepts an optional offset from which to begin the search.
| string | $needle | Substring to look for |
| int | $offset | Offset from which to search |
The occurrence's index if found, otherwise false
indexOfLast(string $needle, int $offset) : int|bool
Returns the index of the last occurrence of $needle in the string, and false if not found. Accepts an optional offset from which to begin the search. Offsets may be negative to count from the last character in the string.
| string | $needle | Substring to look for |
| int | $offset | Offset from which to search |
The last occurrence's index if found, otherwise false
longestCommonSubstring(string $otherStr) : static
Returns the longest common substring between the string and $otherStr.
In the case of ties, it returns that which occurs first.
| string | $otherStr | Second string for comparison |
Object with its $str being the longest common substring
offsetExists(mixed $offset) : bool
Returns whether or not a character exists at an index. Offsets may be negative to count from the last character in the string. Implements part of the ArrayAccess interface.
| mixed | $offset | The index to check |
Whether or not the index exists
offsetGet(mixed $offset) : mixed
Returns the character at the given index. Offsets may be negative to count from the last character in the string. Implements part of the ArrayAccess interface, and throws an OutOfBoundsException if the index does not exist.
| mixed | $offset | The index from which to retrieve the char |
If the positive or negative offset does not exist
The character at the specified index
offsetSet(mixed $offset, mixed $value) : mixed
Implements part of the ArrayAccess interface, but throws an exception when called. This maintains the immutability of Stringy objects.
| mixed | $offset | The index of the character |
| mixed | $value | Value to set |
When called
pad(int $length, string $padStr = ' ', string $padType = 'right') : static
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.
| int | $length | Desired string length after padding |
| string | $padStr | String used to pad, defaults to space |
| string | $padType | One of 'left', 'right', 'both' |
Object with a padded $str
padBoth(int $length, string $padStr = ' ') : static
Returns a new string of a given length such that both sides of the string are padded. Alias for pad() with a $padType of 'both'.
| int | $length | Desired string length after padding |
| string | $padStr | String used to pad, defaults to space |
String with padding applied
padLeft(int $length, string $padStr = ' ') : static
Returns a new string of a given length such that the beginning of the string is padded. Alias for pad() with a $padType of 'left'.
| int | $length | Desired string length after padding |
| string | $padStr | String used to pad, defaults to space |
String with left padding
padRight(int $length, string $padStr = ' ') : static
Returns a new string of a given length such that the end of the string is padded. Alias for pad() with a $padType of 'right'.
| int | $length | Desired string length after padding |
| string | $padStr | String used to pad, defaults to space |
String with right padding
regexReplace(string $pattern, string $replacement, string $options = 'msr') : static
Replaces all occurrences of $pattern in $str by $replacement. An alias for mb_ereg_replace(). Note that the 'i' option with multibyte patterns in mb_ereg_replace() requires PHP 5.6+ for correct results. This is due to a lack of support in the bundled version of Oniguruma in PHP < 5.6, and current versions of HHVM (3.8 and below).
| string | $pattern | The regular expression pattern |
| string | $replacement | The string to replace with |
| string | $options | Matching conditions to be used |
Object with the resulting $str after the replacements
safeTruncate(int $length, string $substring = '') : static
Truncates the string to a given length, while ensuring that it does not split words. If $substring is provided, and truncating occurs, the string is further truncated so that the substring may be appended without exceeding the desired length.
| int | $length | Desired length of the truncated string |
| string | $substring | The substring to append if it can fit |
Object with the resulting $str after truncating
slugify(string $replacement = '-', string $language = 'en') : static
Converts the string into an URL slug. This includes replacing non-ASCII characters with their closest ASCII equivalents, removing remaining non-ASCII and non-alphanumeric characters, and replacing whitespace with $replacement. The replacement defaults to a single dash, and the string is also converted to lowercase. The language of the source string can also be supplied for language-specific transliteration.
| string | $replacement | The string used to replace whitespace |
| string | $language | Language of the source string |
Object whose $str has been converted to an URL slug
startsWith(string $substring, bool $caseSensitive = true) : bool
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.
| string | $substring | The substring to look for |
| bool | $caseSensitive | Whether or not to enforce case-sensitivity |
Whether or not $str starts with $substring
startsWithAny(string[] $substrings, bool $caseSensitive = true) : bool
Returns true if the string begins with any of $substrings, false otherwise. By default the comparison is case-sensitive, but can be made insensitive by setting $caseSensitive to false.
| string[] | $substrings | Substrings to look for |
| bool | $caseSensitive | Whether or not to enforce case-sensitivity |
Whether or not $str starts with $substring
slice(int $start, int $end = null) : static
Returns the substring beginning at $start, and up to, but not including the index specified by $end. If $end is omitted, the function extracts the remaining string. If $end is negative, it is computed from the end of the string.
| int | $start | Initial index from which to begin extraction |
| int | $end | Optional index at which to end extraction |
Object with its $str being the extracted substring
split(string $pattern, int $limit = null) : static[]
Splits the string with the provided regular expression, returning an array of Stringy objects. An optional integer $limit will truncate the results.
| string | $pattern | The regex with which to split the string |
| int | $limit | Optional maximum number of results to return |
An array of Stringy objects
substr(int $start, int $length = null) : static
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.
| int | $start | Position of the first character to use |
| int | $length | Maximum number of characters used |
Object with its $str being the substring
titleize(array $ignore = null) : static
Returns a trimmed string with the first letter of each word capitalized.
Also accepts an array, $ignore, allowing you to list words not to be capitalized.
| array | $ignore | An array of words not to capitalize |
Object with a titleized $str
toAscii(string $language = 'en', bool $removeUnsupported = true) : static
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 by default. The language or locale of the source string can be supplied for language-specific transliteration in any of the following formats: en, en_GB, or en-GB. For example, passing "de" results in "äöü" mapping to "aeoeue" rather than "aou" as in other languages.
| string | $language | Language of the source string |
| bool | $removeUnsupported | Whether or not to remove the unsupported characters |
Object whose $str contains only ASCII characters
toBoolean() : bool
Returns a boolean representation of the given logical string value.
For example, 'true', '1', 'on' and 'yes' will return true. 'false', '0', 'off', and 'no' will return false. In all instances, case is ignored. For other numeric strings, their sign will determine the return value. In addition, blank strings consisting of only whitespace will return false. For all other strings, the return value is a result of a boolean cast.
A boolean value for the string
toSpaces(int $tabLength = 4) : static
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.
| int | $tabLength | Number of spaces to replace each tab with |
Object whose $str has had tabs switched to spaces
toTabs(int $tabLength = 4) : static
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.
| int | $tabLength | Number of spaces to replace with a tab |
Object whose $str has had spaces switched to tabs
trim(string $chars = null) : static
Returns a string with whitespace removed from the start and end of the string. Supports the removal of unicode whitespace. Accepts an optional string of characters to strip instead of the defaults.
| string | $chars | Optional string of characters to strip |
Object with a trimmed $str
trimLeft(string $chars = null) : static
Returns a string with whitespace removed from the start of the string.
Supports the removal of unicode whitespace. Accepts an optional string of characters to strip instead of the defaults.
| string | $chars | Optional string of characters to strip |
Object with a trimmed $str
trimRight(string $chars = null) : static
Returns a string with whitespace removed from the end of the string.
Supports the removal of unicode whitespace. Accepts an optional string of characters to strip instead of the defaults.
| string | $chars | Optional string of characters to strip |
Object with a trimmed $str
truncate(int $length, string $substring = '') : static
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.
| int | $length | Desired length of the truncated string |
| string | $substring | The substring to append if it can fit |
Object with the resulting $str after truncating
underscored() : static
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.
Object with an underscored $str
langSpecificCharsArray(string $language = 'en') : array
Returns language-specific replacements for the toAscii() method.
For example, German will map 'ä' to 'ae', while other languages will simply return 'a'.
| string | $language | Language of the source string |
An array of replacements.
applyPadding(int $left, int $right, string $padStr = ' ') : static
Adds the specified amount of left and right padding to the given string.
The default character used is a space.
| int | $left | Length of left padding |
| int | $right | Length of right padding |
| string | $padStr | String used to pad |
String with padding applied