A PHP string manipulation library with multibyte support. Offers both OO method chaining and a procedural-style static wrapper. Tested and compatible with PHP 5.3+ and HHVM. Inspired by underscore.string.js.
- Requiring/Loading
- OO and Procedural
- Implemented Interfaces
- PHP 5.6 Creation
- Methods
- at
- camelize
- chars
- collapseWhitespace
- contains
- containsAll
- containsAny
- countSubstr
- create
- dasherize
- delimit
- endsWith
- ensureLeft
- ensureRight
- first
- getEncoding
- hasLowerCase
- hasUpperCase
- htmlDecode
- htmlEncode
- humanize
- indexOf
- indexOfLast
- insert
- isAlpha
- isAlphanumeric
- isBlank
- isHexadecimal
- isJson
- isLowerCase
- isSerialized
- isUpperCase
- last
- length
- longestCommonPrefix
- longestCommonSuffix
- longestCommonSubstring
- lowerCaseFirst
- pad
- padBoth
- padLeft
- padRight
- regexReplace
- removeLeft
- removeRight
- replace
- reverse
- safeTruncate
- shuffle
- slugify
- startsWith
- substr
- surround
- swapCase
- tidy
- titleize
- toAscii
- toLowerCase
- toSpaces
- toTabs
- toTitleCase
- toUpperCase
- trim
- trimLeft
- trimRight
- truncate
- underscored
- upperCamelize
- upperCaseFirst
- Links
- Tests
- License
Requiring/Loading
If you're using Composer to manage dependencies, you can include the following in your composer.json file:
{
"require": {
"danielstjules/stringy": "~1.10"
}
}
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';
// or
require_once 'path/to/Stringy/src/StaticStringy.php';
And in either case, I'd suggest using an alias.
use Stringy\Stringy as S;
// or
use Stringy\StaticStringy as S;
OO and Procedural
The library offers both OO method chaining with Stringy\Stringy, as well as
procedural-style static method calls with Stringy\StaticStringy. An example
of the former is the following:
use Stringy\Stringy as S;
echo S::create('Fòô Bàř', 'UTF-8')->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'
Using the static wrapper, an alternative is the following:
use Stringy\StaticStringy as S;
$string = S::collapseWhitespace('Fòô Bàř', 'UTF-8');
echo S::swapCase($string, 'UTF-8'); // 'fÒÔ bÀŘ'
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àř', 'UTF-8');
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òô', 'UTF-8');
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àř', 'UTF-8');
echo $stringy[2]; // 'ř'
echo $stringy[-2]; // 'à'
isset($stringy[-4]); // false
$stringy[3]; // OutOfBoundsException
$stringy[2] = 'a'; // Exception
PHP 5.6 Creation
As of PHP 5.6, use function is
available for importing functions. Stringy exposes a namespaced function,
Stringy\create, which emits the same behaviour as Stringy\Stringy::create().
If running PHP 5.6, or another runtime that supports the use function syntax,
you can take advantage of an even simpler API as seen below:
use function Stringy\create as s;
// Instead of: S::create('Fòô Bàř', 'UTF-8')
s('Fòô Bàř', 'UTF-8')->collapseWhitespace()->swapCase();
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 a Stringy object or string do not modify
the original. Stringy objects are immutable.
Note: If $encoding is not given, it defaults to mb_internal_encoding().
at
$stringy->at(int $index)
S::at(int $index [, string $encoding ])
Returns the character at $index, with indexes starting at 0.
S::create('fòô bàř', 'UTF-8')->at(6);
S::at('fòô bàř', 6, 'UTF-8'); // 'ř'
camelize
$stringy->camelize();
S::camelize(string $str [, string $encoding ])
Returns a camelCase version of the string. Trims surrounding spaces, capitalizes letters following digits, spaces, dashes and underscores, and removes spaces, dashes, as well as underscores.
S::create('Camel-Case')->camelize();
S::camelize('Camel-Case'); // 'camelCase'
chars
$stringy->chars();
S::chars(string $str [, string $encoding ])
Returns an array consisting of the characters in the string.
S::create('Fòô Bàř', 'UTF-8')->chars();
S::chars('Fòô Bàř', 'UTF-8'); // array(F', 'ò', 'ô', ' ', 'B', 'à', 'ř')
collapseWhitespace
$stringy->collapseWhitespace()
S::collapseWhitespace(string $str [, string $encoding ])
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.
S::create(' Ο συγγραφέας ')->collapseWhitespace();
S::collapseWhitespace(' Ο συγγραφέας '); // 'Ο συγγραφέας'
contains
$stringy->contains(string $needle [, boolean $caseSensitive = true ])
S::contains(string $haystack, string $needle [, boolean $caseSensitive = true [, string $encoding ]])
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.
```php S::create('Ο συγγραφέας �
