A PHP string manipulation library with multibyte support. Compatible with PHP
5.4+, PHP 7+, and HHVM.
s('string')->toTitleCase()->ensureRight('y') == 'Stringy'
Refer to the 1.x branch or
2.x branch for older
documentation.
<table>
<tr>
<td><a href="#appendstring-string">append</a></td>
<td><a href="#atint-index">at</a></td>
<td><a href="#betweenstring-start-string-end--int-offset">between</a></td>
<td><a href="#camelize">camelize</a></td>
</tr>
<tr>
<td><a href="#chars">chars</a></td>
<td><a href="#collapsewhitespace">collapseWhitespace</a></td>
<td><a href="#containsstring-needle--boolean-casesensitive--true-">contains</a></td>
<td><a href="#containsallarray-needles--boolean-casesensitive--true-">containsAll</a></td>
</tr>
<tr>
<td><a href="#containsanyarray-needles--boolean-casesensitive--true-">containsAny</a></td>
<td><a href="#countsubstrstring-substring--boolean-casesensitive--true-">countSubstr</a></td>
<td><a href="#dasherize">dasherize</a></td>
<td><a href="#delimitint-delimiter">delimit</a></td>
</tr>
<tr>
<td><a href="#endswithstring-substring--boolean-casesensitive--true-">endsWith</a></td>
<td><a href="#endswithanystring-substrings--boolean-casesensitive--true-">endsWithAny</a></td>
<td><a href="#ensureleftstring-substring">ensureLeft</a></td>
<td><a href="#ensurerightstring-substring">ensureRight</a></td>
</tr>
<tr>
<td><a href="#firstint-n">first</a></td>
<td><a href="#getencoding">getEncoding</a></td>
<td><a href="#haslowercase">hasLowerCase</a></td>
<td><a href="#hasuppercase">hasUpperCase</a></td>
</tr>
<tr>
<td><a href="#htmldecode">htmlDecode</a></td>
<td><a href="#htmlencode">htmlEncode</a></td>
<td><a href="#humanize">humanize</a></td>
<td><a href="#indexofstring-needle--offset--0-">indexOf</a></td>
</tr>
<tr>
<td><a href="#indexoflaststring-needle--offset--0-">indexOfLast</a></td>
<td><a href="#insertint-index-string-substring">insert</a></td>
<td><a href="#isalpha">isAlpha</a></td>
<td><a href="#isalphanumeric">isAlphanumeric</a></td>
</tr>
<tr>
<td><a href="#isbase64">isBase64</a></td>
<td><a href="#isblank">isBlank</a></td>
<td><a href="#ishexadecimal">isHexadecimal</a></td>
<td><a href="#isjson">isJson</a></td>
</tr>
<tr>
<td><a href="#islowercase">isLowerCase</a></td>
<td><a href="#isserialized">isSerialized</a></td>
<td><a href="#isuppercase">isUpperCase</a></td>
<td><a href="#lastint-n">last</a></td>
</tr>
<tr>
<td><a href="#length">length</a></td>
<td><a href="#lines">lines</a></td>
<td><a href="#longestcommonprefixstring-otherstr">longestCommonPrefix</a></td>
<td><a href="#longestcommonsuffixstring-otherstr">longestCommonSuffix</a></td>
</tr>
<tr>
<td><a href="#longestcommonsubstringstring-otherstr">longestCommonSubstring</a></td>
<td><a href="#lowercasefirst">lowerCaseFirst</a></td>
<td><a href="#padint-length--string-padstr-----string-padtype--right-">pad</a></td>
<td><a href="#padbothint-length--string-padstr----">padBoth</a></td>
</tr>
<tr>
<td><a href="#padleftint-length--string-padstr----">padLeft</a></td>
<td><a href="#padrightint-length--string-padstr----">padRight</a></td>
<td><a href="#prependstring-string">prepend</a></td>
<td><a href="#regexreplacestring-pattern-string-replacement--string-options--msr">regexReplace</a></td>
</tr>
<tr>
<td><a href="#removeleftstring-substring">removeLeft</a></td>
<td><a href="#removerightstring-substring">removeRight</a></td>
<td><a href="#repeatint-multiplier">repeat</a></td>
<td><a href="#replacestring-search-string-replacement">replace</a></td>
</tr>
<tr>
<td><a href="#reverse">reverse</a></td>
<td><a href="#safetruncateint-length--string-substring---">safeTruncate</a></td>
<td><a href="#shuffle">shuffle</a></td>
<td><a href="#slugify-string-replacement-----string-language--en">slugify</a></td>
</tr>
<tr>
<td><a href="#sliceint-start--int-end-">slice</a></td>
<td><a href="#splitstring-pattern--int-limit-">split</a></td>
<td><a href="#startswithstring-substring--boolean-casesensitive--true-">startsWith</a></td>
<td><a href="#startswithanystring-substrings--boolean-casesensitive--true-">startsWithAny</a></td>
</tr>
<tr>
<td><a href="#stripwhitespace">stripWhitespace</a></td>
<td><a href="#substrint-start--int-length-">substr</a></td>
<td><a href="#surroundstring-substring">surround</a></td>
<td><a href="#swapcase">swapCase</a></td>
</tr>
<tr>
<td><a href="#tidy">tidy</a></td>
<td><a href="#titleize-array-ignore">titleize</a></td>
<td><a href="#toascii-string-language--en--bool-removeunsupported--true-">toAscii</a></td>
<td><a href="#toboolean">toBoolean</a></td>
</tr>
<tr>
<td><a href="#tolowercase">toLowerCase</a></td>
<td><a href="#tospaces-tablength--4-">toSpaces</a></td>
<td><a href="#totabs-tablength--4-">toTabs</a></td>
<td><a href="#totitlecase">toTitleCase</a></td>
</tr>
<tr>
<td><a href="#touppercase">toUpperCase</a></td>
<td><a href="#trim-string-chars">trim</a></td>
<td><a href="#trimleft-string-chars">trimLeft</a></td>
<td><a href="#trimright-string-chars">trimRight</a></td>
</tr>
<tr>
<td><a href="#truncateint-length--string-substring---">truncate</a></td>
<td><a href="#underscored">underscored</a></td>
<td><a href="#uppercamelize">upperCamelize</a></td>
<td><a href="#uppercasefirst">upperCaseFirst</a></td>
</tr>
</table>
Why?
In part due to a lack of multibyte support (including UTF-8) across many of
PHP's standard string functions. But also to offer an OO wrapper around the
mbstring module's multibyte-compatible functions. Stringy handles some quirks,
provides additional functionality, and hopefully makes strings a little easier
to work with!
// Standard library
strtoupper('fòôbàř'); // 'FòôBàř'
strlen('fòôbàř'); // 10
// mbstring
mb_strtoupper('fòôbàř'); // 'FÒÔBÀŘ'
mb_strlen('fòôbàř'); // '6'
// Stringy
s('fòôbàř')->toUpperCase(); // 'FÒÔBÀŘ'
s('fòôbàř')->length(); // '6'
Installation
If you're using Composer to manage dependencies, you can include the following
in your composer.json file:
"require": {
"danielstjules/stringy": "~3.1.0"
}
Then, after running composer update or php composer.phar update, you can
load the class using Composer's autoloading:
require 'vendor/autoload.php';
Otherwise, you can simply require the file directly:
require_once 'path/to/Stringy/src/Stringy.php';
And in either case, I'd suggest using an alias.
use Stringy\Stringy as S;
Please note that Stringy relies on the mbstring module for its underlying
multibyte support. If the module is not found, Stringy will use
symfony/polyfill-mbstring.
ex-mbstring is a non-default, but very common module. For example, with debian
and ubuntu, it's included in libapache2-mod-php5, php5-cli, and php5-fpm. For
OSX users, it's a default for any version of PHP installed with homebrew.
If compiling PHP from scratch, it can be included with the
--enable-mbstring flag.
OO and Chaining
The library offers OO method chaining, as seen below:
use Stringy\Stringy as S;
echo S::create('fòô bàř')->collapseWhitespace()->swapCase(); // 'FÒÔ BÀŘ'
Stringy\Stringy has a __toString() method, which returns the current string
when the object is used in a string context, ie:
(string) S::create('foo') // 'foo'
Implemented Interfaces
Stringy\Stringy implements the IteratorAggregate interface, meaning that
foreach can be used with an instance of the class:
$stringy = S::create('fòôbàř');
foreach ($stringy as $char) {
echo $char;
}
// 'fòôbàř'
It implements the Countable interface, enabling the use of count() to
retrieve the number of characters in the string:
$stringy = S::create('fòô');
count($stringy); // 3
Furthermore, the ArrayAccess interface has been implemented. As a result,
isset() can be used to check if a character at a specific index exists. And
since Stringy\Stringy is immutable, any call to offsetSet or offsetUnset
will throw an exception. offsetGet has been implemented, however, and accepts
both positive and negative indexes. Invalid indexes result in an
OutOfBoundsException.
$stringy = S::create('bàř');
echo $stringy[2]; // 'ř'
echo $stringy[-2]; // 'à'
isset($string
