mirror/stringy
1
0
Fork 0
mirror of https://github.com/danielstjules/Stringy.git synced 2025-08-05 21:07:27 +02:00
Code Issues Releases Wiki Activity

Update index.md with latest readme content

Browse Source
This commit is contained in:
Daniel St. Jules
2017-03-08 20:30:09 -05:00
parent e0b8131e66
commit a9ad19519f
1 changed files with 203 additions and 104 deletions
Download Patch File Download Diff File Expand all files Collapse all files

307
index.md
View File

@@ -1,14 +1,19 @@
![Stringy](http://danielstjules.com/github/stringy-logo.png) ![Stringy](http://danielstjules.com/github/stringy-logo.png)
A PHP string manipulation library with multibyte support. Compatible with PHP A PHP string manipulation library with multibyte support. Compatible with PHP
5.3+ and HHVM. Refer to the [1.x branch](https://github.com/danielstjules/Stringy/tree/1.x) 5.4+, PHP 7, and HHVM.
for older documentation.
``` php ``` php
s('string')->toTitleCase()->ensureRight('y') == 'Stringy' s('string')->toTitleCase()->ensureRight('y') == 'Stringy'
``` ```
Refer to the [1.x branch](https://github.com/danielstjules/Stringy/tree/1.x) or
[2.x branch](https://github.com/danielstjules/Stringy/tree/2.x) for older
documentation.
[![Build Status](https://api.travis-ci.org/danielstjules/Stringy.svg?branch=master)](https://travis-ci.org/danielstjules/Stringy) [![Build Status](https://api.travis-ci.org/danielstjules/Stringy.svg?branch=master)](https://travis-ci.org/danielstjules/Stringy)
[![Total Downloads](https://poser.pugx.org/danielstjules/stringy/downloads)](https://packagist.org/packages/danielstjules/stringy)
[![License](https://poser.pugx.org/danielstjules/stringy/license)](https://packagist.org/packages/danielstjules/stringy)
* [Why?](#why) * [Why?](#why)
* [Installation](#installation) * [Installation](#installation)
@@ -19,82 +24,128 @@ s('string')->toTitleCase()->ensureRight('y') == 'Stringy'
* [Class methods](#class-methods) * [Class methods](#class-methods)
* [create](#createmixed-str--encoding-) * [create](#createmixed-str--encoding-)
* [Instance methods](#instance-methods) * [Instance methods](#instance-methods)
* [append](#appendstring-string) <table>
* [at](#atint-index) <tr>
* [between](#betweenstring-start-string-end--int-offset) <td>[append](#appendstring-string)</td>
* [camelize](#camelize) <td>[at](#atint-index)</td>
* [chars](#chars) <td>[between](#betweenstring-start-string-end--int-offset)</td>
* [collapseWhitespace](#collapsewhitespace) <td>[camelize](#camelize)</td>
* [contains](#containsstring-needle--boolean-casesensitive--true-) </tr>
* [containsAll](#containsallarray-needles--boolean-casesensitive--true-) <tr>
* [containsAny](#containsanyarray-needles--boolean-casesensitive--true-) <td>[chars](#chars)</td>
* [countSubstr](#countsubstrstring-substring--boolean-casesensitive--true-) <td>[collapseWhitespace](#collapsewhitespace)</td>
* [dasherize](#dasherize) <td>[contains](#containsstring-needle--boolean-casesensitive--true-)</td>
* [delimit](#delimitint-delimiter) <td>[containsAll](#containsallarray-needles--boolean-casesensitive--true-)</td>
* [endsWith](#endswithstring-substring--boolean-casesensitive--true-) </tr>
* [ensureLeft](#ensureleftstring-substring) <tr>
* [ensureRight](#ensurerightstring-substring) <td>[containsAny](#containsanyarray-needles--boolean-casesensitive--true-)</td>
* [first](#firstint-n) <td>[countSubstr](#countsubstrstring-substring--boolean-casesensitive--true-)</td>
* [getEncoding](#getencoding) <td>[dasherize](#dasherize)</td>
* [hasLowerCase](#haslowercase) <td>[delimit](#delimitint-delimiter)</td>
* [hasUpperCase](#hasuppercase) </tr>
* [htmlDecode](#htmldecode) <tr>
* [htmlEncode](#htmlencode) <td>[endsWith](#endswithstring-substring--boolean-casesensitive--true-)</td>
* [humanize](#humanize) <td>[endsWithAny](#endswithanystring-substrings--boolean-casesensitive--true-)</td>
* [indexOf](#indexofstring-needle--offset--0-) <td>[ensureLeft](#ensureleftstring-substring)</td>
* [indexOfLast](#indexoflaststring-needle--offset--0-) <td>[ensureRight](#ensurerightstring-substring)</td>
* [insert](#insertint-index-string-substring) </tr>
* [isAlpha](#isalpha) <tr>
* [isAlphanumeric](#isalphanumeric) <td>[first](#firstint-n)</td>
* [isBlank](#isblank) <td>[getEncoding](#getencoding)</td>
* [isHexadecimal](#ishexadecimal) <td>[hasLowerCase](#haslowercase)</td>
* [isJson](#isjson) <td>[hasUpperCase](#hasuppercase)</td>
* [isLowerCase](#islowercase) </tr>
* [isSerialized](#isserialized) <tr>
* [isUpperCase](#isuppercase) <td>[htmlDecode](#htmldecode)</td>
* [last](#last) <td>[htmlEncode](#htmlencode)</td>
* [length](#length) <td>[humanize](#humanize)</td>
* [lines](#lines) <td>[indexOf](#indexofstring-needle--offset--0-)</td>
* [longestCommonPrefix](#longestcommonprefixstring-otherstr) </tr>
* [longestCommonSuffix](#longestcommonsuffixstring-otherstr) <tr>
* [longestCommonSubstring](#longestcommonsubstringstring-otherstr) <td>[indexOfLast](#indexoflaststring-needle--offset--0-)</td>
* [lowerCaseFirst](#lowercasefirst) <td>[insert](#insertint-index-string-substring)</td>
* [pad](#padint-length--string-padstr-----string-padtype--right-) <td>[isAlpha](#isalpha)</td>
* [padBoth](#padbothint-length--string-padstr----) <td>[isAlphanumeric](#isalphanumeric)</td>
* [padLeft](#padleftint-length--string-padstr----) </tr>
* [padRight](#padrightint-length--string-padstr----) <tr>
* [prepend](#prependstring-string) <td>[isBase64](#isbase64)</td>
* [regexReplace](#regexreplacestring-pattern-string-replacement--string-options--msr) <td>[isBlank](#isblank)</td>
* [removeLeft](#removeleftstring-substring) <td>[isHexadecimal](#ishexadecimal)</td>
* [removeRight](#removerightstring-substring) <td>[isJson](#isjson)</td>
* [repeat](#repeatmultiplier) </tr>
* [replace](#replacestring-search-string-replacement) <tr>
* [reverse](#reverse) <td>[isLowerCase](#islowercase)</td>
* [safeTruncate](#safetruncateint-length--string-substring---) <td>[isSerialized](#isserialized)</td>
* [shuffle](#shuffle) <td>[isUpperCase](#isuppercase)</td>
* [slugify](#slugify-string-replacement----) <td>[last](#lastint-n)</td>
* [startsWith](#startswithstring-substring--boolean-casesensitive--true-) </tr>
* [slice](#sliceint-start--int-end-) <tr>
* [split](#splitstring-pattern--int-limit-) <td>[length](#length)</td>
* [substr](#substrint-start--int-length-) <td>[lines](#lines)</td>
* [surround](#surroundstring-substring) <td>[longestCommonPrefix](#longestcommonprefixstring-otherstr)</td>
* [swapCase](#swapcase) <td>[longestCommonSuffix](#longestcommonsuffixstring-otherstr)</td>
* [tidy](#tidy) </tr>
* [titleize](#titleize-array-ignore) <tr>
* [toAscii](#toascii) <td>[longestCommonSubstring](#longestcommonsubstringstring-otherstr)</td>
* [toBoolean](#toboolean) <td>[lowerCaseFirst](#lowercasefirst)</td>
* [toLowerCase](#tolowercase) <td>[pad](#padint-length--string-padstr-----string-padtype--right-)</td>
* [toSpaces](#tospaces-tablength--4-) <td>[padBoth](#padbothint-length--string-padstr----)</td>
* [toTabs](#totabs-tablength--4-) </tr>
* [toTitleCase](#totitlecase) <tr>
* [toUpperCase](#touppercase) <td>[padLeft](#padleftint-length--string-padstr----)</td>
* [trim](#trim-string-chars) <td>[padRight](#padrightint-length--string-padstr----)</td>
* [trimLeft](#trimleft-string-chars) <td>[prepend](#prependstring-string)</td>
* [trimRight](#trimright-string-chars) <td>[regexReplace](#regexreplacestring-pattern-string-replacement--string-options--msr)</td>
* [truncate](#truncateint-length--string-substring---) </tr>
* [underscored](#underscored) <tr>
* [upperCamelize](#uppercamelize) <td>[removeLeft](#removeleftstring-substring)</td>
* [upperCaseFirst](#uppercasefirst) <td>[removeRight](#removerightstring-substring)</td>
<td>[repeat](#repeatint-multiplier)</td>
<td>[replace](#replacestring-search-string-replacement)</td>
</tr>
<tr>
<td>[reverse](#reverse)</td>
<td>[safeTruncate](#safetruncateint-length--string-substring---)</td>
<td>[shuffle](#shuffle)</td>
<td>[slugify](#slugify-string-replacement----)</td>
</tr>
<tr>
<td>[slice](#sliceint-start--int-end-)</td>
<td>[split](#splitstring-pattern--int-limit-)</td>
<td>[startsWith](#startswithstring-substring--boolean-casesensitive--true-)</td>
<td>[startsWithAny](#startswithanystring-substrings--boolean-casesensitive--true-)</td>
</tr>
<tr>
<td>[stripWhitespace](#stripwhitespace)</td>
<td>[substr](#substrint-start--int-length-)</td>
<td>[surround](#surroundstring-substring)</td>
<td>[swapCase](#swapcase)</td>
</tr>
<tr>
<td>[tidy](#tidy)</td>
<td>[titleize](#titleize-array-ignore)</td>
<td>[toAscii](#toascii-string-language--en--bool-removeunsupported--true-)</td>
<td>[toBoolean](#toboolean)</td>
</tr>
<tr>
<td>[toLowerCase](#tolowercase)</td>
<td>[toSpaces](#tospaces-tablength--4-)</td>
<td>[toTabs](#totabs-tablength--4-)</td>
<td>[toTitleCase](#totitlecase)</td>
</tr>
<tr>
<td>[toUpperCase](#touppercase)</td>
<td>[trim](#trim-string-chars)</td>
<td>[trimLeft](#trimleft-string-chars)</td>
<td>[trimRight](#trimright-string-chars)</td>
</tr>
<tr>
<td>[truncate](#truncateint-length--string-substring---)</td>
<td>[underscored](#underscored)</td>
<td>[upperCamelize](#uppercamelize)</td>
<td>[upperCaseFirst](#uppercasefirst)</td>
</tr>
</table>
* [Extensions](#extensions) * [Extensions](#extensions)
* [Tests](#tests) * [Tests](#tests)
* [License](#license) * [License](#license)
@@ -128,7 +179,7 @@ in your composer.json file:
```json ```json
"require": { "require": {
"danielstjules/stringy": "~2.1" "danielstjules/stringy": "~3.0"
} }
``` ```
@@ -151,11 +202,13 @@ And in either case, I'd suggest using an alias.
use Stringy\Stringy as S; use Stringy\Stringy as S;
``` ```
Please note that Stringy relies on the `mbstring` PHP module for its underlying Please note that Stringy relies on the `mbstring` module for its underlying
multibyte support. This is a non-default, but very common module. For example, multibyte support. If the module is not found, Stringy will use
with debian and ubuntu, it's included in libapache2-mod-php5, php5-cli, and [symfony/polyfill-mbstring](https://github.com/symfony/polyfill-mbstring).
php5-fpm. For OSX users, it's a default for any version of PHP installed with ex-mbstring is a non-default, but very common module. For example, with debian
homebrew. If compiling PHP from scratch, it can be included with the 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. `--enable-mbstring` flag.
## OO and Chaining ## OO and Chaining
@@ -234,9 +287,9 @@ integer, boolean, etc.
```php ```php
use Stringy\StaticStringy as S; use Stringy\StaticStringy as S;
// Translates to Stringy::create('fòôbàř', 'UTF-8')->slice(0, 3); // Translates to Stringy::create('fòôbàř')->slice(0, 3);
// Returns a Stringy object with the string "fòô" // Returns a Stringy object with the string "fòô"
S::slice('fòôbàř', 0, 3, 'UTF-8'); S::slice('fòôbàř', 0, 3);
``` ```
## Class methods ## Class methods
@@ -250,7 +303,7 @@ then returns the initialized object. Throws an InvalidArgumentException
if the first argument is an array or object without a __toString method. if the first argument is an array or object without a __toString method.
```php ```php
$stringy = S::create('fòôbàř', 'UTF-8'); // 'fòôbàř' $stringy = S::create('fòôbàř'); // 'fòôbàř'
``` ```
## Instance Methods ## Instance Methods
@@ -383,7 +436,17 @@ default, the comparison is case-sensitive, but can be made insensitive by
setting $caseSensitive to false. setting $caseSensitive to false.
```php ```php
s('fòôbàř')->endsWith('bàř', true); // true s('fòôbàř')->endsWith('bàř'); // true
```
##### endsWithAny(string[] $substrings [, boolean $caseSensitive = true ])
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.
```php
s('fòôbàř')->endsWithAny(['bàř', 'baz']); // true
``` ```
##### ensureLeft(string $substring) ##### ensureLeft(string $substring)
@@ -396,7 +459,7 @@ s('foobar')->ensureLeft('http://'); // 'http://foobar'
##### ensureRight(string $substring) ##### ensureRight(string $substring)
Ensures that the string begins with $substring. If it doesn't, it's appended. Ensures that the string ends with $substring. If it doesn't, it's appended.
```php ```php
s('foobar')->ensureRight('.com'); // 'foobar.com' s('foobar')->ensureRight('.com'); // 'foobar.com'
@@ -415,7 +478,7 @@ s('fòôbàř')->first(3); // 'fòô'
Returns the encoding used by the Stringy object. Returns the encoding used by the Stringy object.
```php ```php
s('fòôbàř', 'UTF-8')->getEncoding(); // 'UTF-8' s('fòôbàř')->getEncoding(); // 'UTF-8'
``` ```
##### hasLowerCase() ##### hasLowerCase()
@@ -509,6 +572,14 @@ otherwise.
s('دانيال1')->isAlphanumeric(); // true s('دانيال1')->isAlphanumeric(); // true
``` ```
##### isBase64()
Returns true if the string is base64 encoded, false otherwise.
```php
s('Zm9vYmFy')->isBase64(); // true
```
##### isBlank() ##### isBlank()
Returns true if the string contains only whitespace chars, false otherwise. Returns true if the string contains only whitespace chars, false otherwise.
@@ -527,7 +598,9 @@ s('A102F')->isHexadecimal(); // true
##### isJson() ##### isJson()
Returns true if the string is JSON, false otherwise. Returns true if the string is JSON, false otherwise. Unlike json_decode
in PHP 5.x, this method is consistent with PHP 7 and other JSON parsers,
in that an empty string is not considered valid JSON.
```php ```php
s('{"foo":"bar"}')->isJson(); // true s('{"foo":"bar"}')->isJson(); // true
@@ -671,7 +744,8 @@ to a lack of support in the bundled version of Oniguruma in PHP < 5.6,
and current versions of HHVM (3.8 and below). and current versions of HHVM (3.8 and below).
```php ```php
s('fòô ')->regexReplace('f[òô]+\s', 'bàř', 'msr'); // 'bàř' s('fòô ')->regexReplace('f[òô]+\s', 'bàř'); // 'bàř'
s('fò')->regexReplace('(ò)', '\\1ô'); // 'fòô'
``` ```
##### removeLeft(string $substring) ##### removeLeft(string $substring)
@@ -747,16 +821,6 @@ is also converted to lowercase.
s('Using strings like fòô bàř')->slugify(); // 'using-strings-like-foo-bar' s('Using strings like fòô bàř')->slugify(); // 'using-strings-like-foo-bar'
``` ```
##### startsWith(string $substring [, boolean $caseSensitive = true ])
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.
```php
s('FÒÔbàřbaz')->startsWith('fòôbàř', false); // true
```
##### slice(int $start [, int $end ]) ##### slice(int $start [, int $end ])
Returns the substring beginning at $start, and up to, but not including Returns the substring beginning at $start, and up to, but not including
@@ -778,6 +842,36 @@ results.
s('foo,bar,baz')->split(',', 2); // ['foo', 'bar'] s('foo,bar,baz')->split(',', 2); // ['foo', 'bar']
``` ```
##### startsWith(string $substring [, boolean $caseSensitive = true ])
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.
```php
s('FÒÔbàřbaz')->startsWith('fòôbàř', false); // true
```
##### startsWithAny(string[] $substrings [, boolean $caseSensitive = true ])
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.
```php
s('FÒÔbàřbaz')->startsWithAny(['fòô', 'bàř'], false); // true
```
##### stripWhitespace()
Strip all whitespace characters. This includes tabs and newline
characters, as well as multibyte whitespace such as the thin space
and ideographic space.
```php
s(' Ο συγγραφέας ')->stripWhitespace(); // 'Οσυγγραφέας'
```
##### substr(int $start [, int $length ]) ##### substr(int $start [, int $length ])
Returns the substring beginning at $start with the specified $length. Returns the substring beginning at $start with the specified $length.
@@ -825,14 +919,19 @@ s('i like to watch television')->titleize($ignore);
// 'I Like to Watch Television' // 'I Like to Watch Television'
``` ```
##### toAscii() ##### toAscii([, string $language = 'en' [, bool $removeUnsupported = true ]])
Returns an ASCII version of the string. A set of non-ASCII characters are 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 replaced with their closest ASCII counterparts, and the rest are removed
unless instructed otherwise. 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.
```php ```php
s('fòôbàř')->toAscii(); // 'foobar' s('fòôbàř')->toAscii(); // 'foobar'
s('äöü')->toAscii(); // 'aou'
s('äöü')->toAscii('de'); // 'aeoeue'
``` ```
##### toBoolean() ##### toBoolean()