About

str/str

$str = new Str('Hello, 世界');
$str->last(2); // 世界
$str->chars(); // ['世', '界']

$str
    ->ensureLeft('Hello, ') // Hello, 世界
    ->ensureRight('!!!') // Hello, 世界!!!
    ->trimRight('!') // Hello, 世界
    ->prepend('Str say - '); // Str say - Hello, 世界

$send = function (string $s) {};
$send((string)$str); // same
$send($str->getString()); // same

Install

Requirements:

• php7.1

composer require str/str

Features

• strongly typed
• no exceptions thrown
• fast
• new functions

A fast string manipulation library with multi-byte support. Inspired by the "Stringy" library, with focus on speed.

Lib uses php7 features and does not throw any exceptions (because all input parameters are strongly typed). The code is completely covered by unit tests.

Functions Index:

A

• afterFirst
• afterLast
• append
• appendUniqueIdentifier
• at

B

• beforeFirst
• beforeLast
• between

C

• camelize
• chars
• chop
• collapseWhitespace
• contains
• containsAll
• containsAny
• countSubstr

D

• dasherize
• delimit

E

• endsWith
• endsWithAny
• ensureLeft
• ensureRight

F

• first

G

• getString

H

• hasLowerCase
• hasPrefix
• hasSuffix
• hasUpperCase
• htmlDecode
• htmlEncode
• humanize

I

• indexOf
• indexOfLast
• insert
• isAlpha
• isAlphanumeric
• isBase64
• isBlank
• isEmail
• isHexadecimal
• isIpV4
• isIpV6
• isJson
• isLowerCase
• isSerialized
• isUUIDv4
• isUpperCase

J

• join

L

• last
• length
• lines
• longestCommonPrefix
• longestCommonSubstring
• longestCommonSuffix
• lowerCaseFirst

M

• make
• matchesPattern
• move

O

• overwrite

P

• padBoth
• padLeft
• padRight
• pop
• popReversed
• prepend

Q

• quote

R

• random
• regexReplace
• removeLeft
• removeRight
• repeat
• replace
• replaceWithLimit
• reverse

S

• safeTruncate
• shift
• shiftReversed
• shuffle
• slice
• slugify
• snakeize
• split
• startsWith
• startsWithAny
• stripWhitespace
• substr
• surround
• swapCase

T

• tidy
• titleize
• toAscii
• toBoolean
• toLowerCase
• toSpaces
• toTabs
• toTitleCase
• toUpperCase
• trim
• trimLeft
• trimRight
• truncate

U

• underscored
• unquote
• upperCamelize
• upperCaseFirst

W

• words

Functions List:

afterFirst

Inserts given $substr $times into the original string after the first occurrence of $needle.

$str = new Str('foo bar baz');
echo (string)$str->afterFirst('a', 'duh', 2);
// foo baduhduhr baz

Parameters:

• string $needle
• string $substr
• int $times

Return:

• \Str

afterLast

Inserts given $substr $times into the original string after the last occurrence of $needle.

$str = new Str('foo bar baz');
echo (string)$str->afterLast('a', 'duh', 2);
// foo bar baduhduhz

Parameters:

• string $needle
• string $substr
• int $times

Return:

• \Str

append

Append $sub to the string.

$str = new Str('/Acme');
echo (string)$str->append('/');
// /Acme/

Parameters:

• string $sub

Return:

• \Str

appendUniqueIdentifier

Appends a random string consisting of $possibleChars, if specified, of given $size or random length between $size and $sizeMax to the original string.

$str = new Str('foo');
echo $str->appendUniqueIdentifier(3, -1, 'foba_rz');
// foozro

Parameters:

• int $size
• int $sizeMax
• string $possibleChars

Return:

• \Str

at

Returns the character at $pos, with indexes starting at 0.

$str = new Str('/Acme/');
echo (string)$str->at(2);
// c

Parameters:

• int $pos

Return:

• \Str

beforeFirst

Inserts given $substr $times into the original string before the first occurrence of $needle.

$str = new Str('foo bar baz');
echo (string)$str->beforeFirst('a', 'duh');
// foo bduhar baz

Parameters:

• string $needle
• string $substr
• int $times

Return:

• \Str

beforeLast

Inserts given $substr $times into the original string before the last occurrence of $needle.

$str = new Str('foo bar baz');
echo (string)$str->beforeLast('a', 'duh');
// foo bar bduhaz

Parameters:

• string $needle
• string $substr
• int $times

Return:

• \Str

between

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.

$str = new Str('/Acme/');
echo (string)$str->between('/', '/');
// Acme

Parameters:

• string $start
• string $end
• int $offset

Return:

• \Str

camelize

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.

$str = new Str('ac me');
echo (string)$str->camelize();
// acMe

Parameters: nothing

Return:

• \Str

chars

Returns an array consisting of the characters in the string.

$str = new Str('/Acme/');
echo (string)$str->chars();
// ['/', 'A', 'c', 'm', 'e', '/']

Parameters: nothing

Return:

• array

chop

Cuts the original string in pieces of $step size.

$str = new Str('foo bar baz');
echo $str->chop(2);
// ['fo', 'o ', 'ba', 'r ', 'ba', 'z']

Parameters:

• int $step

Return:

• array

collapseWhitespace

Trims the string and replaces consecutive whitespace characters with a single space. This includes tabs and newline characters, as well as multi-byte whitespace such as the thin space and ideographic space.

$str = new Str('foo bar baz');
echo (string)$str->collapseWhitespace();
// foo bar baz

Parameters: nothing

Return:

• \Str

contains

Check if the string contains $needle substring.

$str = new Str('/Acme/');
echo $str->contains('/');
// true
$str = new Str('/Acme/');
echo $str->contains('a', false);
// true

Parameters:

• string $needle
• bool $caseSensitive

Return:

• bool

containsAll

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.

$str = new Str('/Accmme/');
echo $str->containsAll(['m', 'c', '/']);
// true

Parameters:

• array $needles
• bool $caseSensitive

Return:

• bool

containsAny

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.

$str = new Str('/Accmme/');
echo $str->containsAny(['foo', 'c', 'bar']);
// true

Parameters:

• array $needles
• bool $caseSensitive

Return:

• bool

countSubstr

Returns the number of occurrences of $needle in the given string. By default the comparison is case-sensitive, but can be made insensitive by setting $caseSensitive to false.

$str = new Str('/Accmme/');
echo $str->countSubstr('m');
// 2

Parameters:

• string $needle
• bool $caseSensitive

Return:

• int

dasherize

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.

$str = new Str('Ac me');
echo (string)$str->dasherize();
// ac-me

Parameters: nothing

Return:

• \Str

delimit

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.

$str = new Str('Ac me');
echo (string)$str->delimit('#');
// ac#me

Parameters:

• $delimiter

Return:

• \Str

endsWith

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.

$str = new Str('/Accmme/');
echo $str->endsWith('e/');
// true

Parameters:

• string $substring
• bool $caseSensitive

Return:

• bool

endsWithAny

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.

$str = new Str('/Accmme/');
echo $str->endsWithAny(['foo', 'e/', 'bar']);
// true

Parameters:

• array $substrings
• bool $caseSensitive

Return:

• bool

ensureLeft

Check whether $prefix exists in the string, and prepend $prefix to the string if it doesn't.

$str = new Str('Acme/');
echo (string)$str->ensureLeft('/');
// /Acme/
$str = new Str('/Acme/');
echo (string)$str->ensureLeft('/');
// /Acme/

Parameters:

• string $check

Return:

• \Str

ensureRight

Check whether $suffix exists in the string, and append $suffix to the string if it doesn't.

$str = new Str('/Acme');
echo (string)$str->ensureRight('/'); // /Acme/
$str = new Str('/Acme/');
echo (string)$str->ensureRight('/'); // /Acme/

Parameters:

• string $check

Return:

• \Str

first

Returns the first $length characters of the string.

$str = new Str('/Acme/');
echo (string)$str->first(2);
// /A

Parameters:

• int $length

Return:

• \Str

getString

Parameters: nothing

Return:

• string

hasLowerCase

Returns true if the string contains a lower case char, false otherwise.

$str = new Str('Acme');
echo $str->hasLowerCase();
// true

Parameters: nothing

Return:

• bool

hasPrefix

Check if the string has $prefix at the start.

$str = new Str('/Acme/');
echo $str->hasPrefix('/');
// true

Parameters:

• string $prefix

Return:

• bool

hasSuffix

Check if the string has $suffix at the end.

$str = new Str('/Acme/');
echo $str->hasSuffix('/');
// true

Parameters:

• string $suffix

Return:

• bool

hasUpperCase

Returns true if the string contains an upper case char, false otherwise.

$str = new Str('Acme');
echo $str->hasUpperCase();
// true

Parameters: nothing

Return:

• bool

htmlDecode

Convert all HTML entities to their applicable characters. An alias of html_entity_decode. For a list of flags, refer to PHP documentation.

$str = new Str('<Acme>');
echo (string)$str->htmlDecode();
// <Acme>

Parameters:

• int $flags

Return:

• \Str

htmlEncode

Convert all applicable characters to HTML entities. An alias of htmlentities. Refer to PHP documentation for a list of flags.

$str = new Str('<Acme>');
echo (string)$str->htmlEncode();
// &lt;Acme&gt;

Parameters:

• int $flags

Return:

• \Str

humanize

Capitalizes the first word of the string, replaces underscores with spaces.

$str = new Str('foo_id');
echo (string)$str->humanize();
// Foo

Parameters: nothing

Return:

• \Str

indexOf

Returns the index of the first occurrence of $needle in the string, and -1 if not found. Accepts an optional $offset from which to begin the search.

$str = new Str('/Accmme/');
echo $str->indexOf('m');
// 4

Parameters:

• string $needle
• int $offset

Return:

• int

indexOfLast

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.

$str = new Str('/Accmme/');
echo $str->indexOfLast('m');
// 5

Parameters:

• string $needle
• int $offset

Return:

• int

insert

Inserts $substring into the string at the $index provided.

$str = new Str('/Ace/');
echo (string)$str->insert('m', 3);
// /Acme/

Parameters:

• string $substring
• int $index

Return:

• \Str

isAlpha

Returns true if the string contains only alphabetic chars, false otherwise.

$str = new Str('Acme');
echo $str->isAlpha();
// true

Parameters: nothing

Return:

• bool

isAlphanumeric

Returns true if the string contains only alphabetic and numeric chars, false otherwise.

$str = new Str('Acme1');
echo $str->isAlphanumeric();
// true

Parameters: nothing

Return:

• bool

isBase64

Check if this string is valid base64 encoded data. Function do encode(decode(s)) === s, so this is not so fast.

Parameters: nothing

Return:

• bool

isBlank

Returns true if the string contains only whitespace chars, false otherwise.

$str = new Str('Acme');
echo $str->isBlank();
// false

Parameters: nothing

Return:

• bool

isEmail

Splits the original string in pieces by '@' delimiter and returns true in case the resulting array consists of 2 parts.

$str = new Str('test@[email protected]');
echo $str->isEmail();
// false

Parameters: nothing

Return:

• bool

isHexadecimal

Returns true if the string contains only hexadecimal chars, false otherwise.

$str = new Str('Acme');
echo $str->isHexadecimal();
// false

Parameters: nothing

Return:

• bool

isIpV4

Return true if this is valid ipv4 address

$str = new Str('1.0.1.0');
echo $str->isIpV4();
// true

Parameters: nothing

Return:

• bool

isIpV6

Return true if this is valid ipv6 address

$str = new Str('2001:cdba::3257:9652');
echo $str->isIpV6();
// true

Parameters: nothing

Return:

• bool

isJson

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.

$str = new Str('Acme');
echo $str->isJson();
// false

Parameters: nothing

Return:

• bool

isLowerCase

Returns true if the string contains only lower case chars, false otherwise.

$str = new Str('Acme');
echo $str->isLowerCase();
// false

Parameters: nothing

Return:

• bool

isSerialized

Returns true if the string is serialized, false otherwise.

$str = new Str('Acme');
echo $str->isSerialized();
// false

Parameters: nothing

Return:

• bool

isUUIDv4

It doesn't matter whether the given UUID has dashes.

$str = new Str('76d7cac8-1bd7-11e8-accf-0ed5f89f718b');
echo $str->isUUIDv4();
// false
$str = new Str('ae815123-537f-4eb3-a9b8-35881c29e1ac');
echo $str->isUUIDv4();
// true

Parameters: nothing

Return:

• bool

isUpperCase

Returns true if the string contains only upper case chars, false otherwise.

$str = new Str('Acme');
echo $str->isUpperCase();
// false

Parameters: nothing

Return:

• bool

join

Joins the original string with an array of other strings with the given $separator.

$str = new Str('foo');
echo $str->join('*', ['bar', 'baz']);
// foo*bar*baz

Parameters:

• string $separator
• array $otherStrings

Return:

• \Str

last

Returns the first $length characters of the string.

$str = new Str('/Acme/');
echo (string)$str->last(2);
// e/

Parameters:

• int $length

Return:

• \Str

length

Returns the length of the string.

$str = new Str('/Acme/');
echo $str->length();
// 6

Parameters: nothing

Return:

• int

lines

Splits on newlines and carriage returns, returning an array of strings corresponding to the lines in the string.

$str = new Str("Acme\r\nAcme");
echo $str->lines();
// ['Acme', 'Acme']

Parameters: nothing

Return:

• array

longestCommonPrefix

Returns the longest common prefix between the string and $otherStr.

$str = new Str('Acme');
echo (string)$str->longestCommonPrefix('Accurate');
// Ac

Parameters:

• string $otherStr

Return:

• \Str

longestCommonSubstring

Returns the longest common substring between the string and $otherStr. In the case of ties, it returns that which occurs first.

$str = new Str('Acme');
echo (string)$str->longestCommonSubstring('meh');
// me

Parameters:

• string $otherStr

Return:

• \Str

longestCommonSuffix

Returns the longest common suffix between the string and $otherStr.

$str = new Str('Acme');
echo (string)$str->longestCommonSuffix('Do believe me');
// me

Parameters:

• string $otherStr

Return:

• \Str

lowerCaseFirst

Converts the first character of the string to lower case.

$str = new Str('Acme Foo');
echo (string)$str->lowerCaseFirst();
// acme Foo

Parameters: nothing

Return:

• \Str

make

Create a new Str object using static method for it.

$str = Str::make('Acme');
echo (string)$str; // Acme

Parameters:

• string $str

Return:

• \Str

matchesPattern

Returns true if the string match regexp pattern

$s = new Str('foo baR');
echo $str->matchesPattern('.*aR');
// true

Parameters:

• string $pattern

Return:

• bool

move

Move substring of desired $length to $destination index of the original string. In case $destination is less than $length returns the string untouched.

$str = new Str('/Acme/');
echo (string)$str->move(0, 2, 4);
// cm/Ae/

Parameters:

• int $start
• int $length
• int $destination

Return:

• \Str

overwrite

Replaces substring in the original string of $length with given $substr.

$str = new Str('/Acme/');
echo (string)$str->overwrite(0, 2, 'BAR');
// BARcme/

Parameters:

• int $start
• int $length
• string $substr

Return:

• \Str

padBoth

Returns a new string of a given length such that both sides of the string are padded.

$str = new Str('Acme');
echo (string)$str->padBoth(6, '/');
// /Acme/

Parameters:

• int $length
• string $padStr

Return:

• \Str

padLeft

Returns a new string of a given length such that the beginning of the string is padded.

$str = new Str('Acme/');
echo (string)$str->padLeft(6, '/');
// /Acme/

Parameters:

• int $length
• string $padStr

Return:

• \Str

padRight

Returns a new string of a given length such that the end of the string is padded.

$str = new Str('/Acme');
echo (string)$str->padRight(6, '/');
// /Acme/

Parameters:

• int $length
• string $padStr

Return:

• \Str

pop

Returns the substring of the string from the last occurrence of $delimiter to the end.

$str = new Str('Acme/foo');
echo $str->pop('/');
// foo

Parameters:

• string $delimiter

Return:

• \Str

popReversed

Returns the substring of the original string from the beginning to the last occurrence of $delimiter.

$str = new Str('Acme/foo/bar');
echo $str->popReversed('/');
// Acme/foo

Parameters:

• string $delimiter

Return:

• \Str

prepend

Prepend $sub to the string.

$str = new Str('Acme/');
echo (string)$str->prepend('/');
// /Acme/

Parameters:

• string $sub

Return:

• \Str

quote

Wraps each word in the string with specified $quote.

$str = new Str('foo bar baz');
echo $str->quote('*');
// *foo* *bar* *baz*

Parameters:

• string $quote

Return:

• \Str

random

Generates a random string consisting of $possibleChars, if specified, of given $size or random length between $size and $sizeMax. If $possibleChars is not specified, the generated string will consist of ASCII alphanumeric chars.

$str = new Str('foo bar');
echo $str->random(3, -1, 'fobarz');
// zfa
$str = new Str('');
echo $str->random(3);
// 1ho

Parameters:

• int $size
• int $sizeMax
• string $possibleChars

Return:

• \Str

regexReplace

Replaces all occurrences of $pattern in the string by $replacement. An alias for mb_ereg_replace(). Note that the 'i' option with multi-byte 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).

$str = new Str('Acme Foo');
echo (string)$str->regexReplace('A', 'a');
// acme Foo

Parameters:

• string $pattern
• string $replacement
• string $options

Return:

• \Str

removeLeft

Returns the string with the prefix $substring removed, if present.

$str = new Str('/Acme/');
echo (string)$str->removeLeft('/');
// Acme/

Parameters:

• string $substring

Return:

• \Str

removeRight

Returns the string with the suffix $substring removed, if present.

$str = new Str('/Acme/');
echo (string)$str->removeRight('/');
// /Acme

Parameters:

• string $substring

Return:

• \Str

repeat

Returns a repeated string given a $multiplier. An alias for str_repeat.

$str = new Str('Acme/');
echo (string)$str->repeat(2);
// Acme/Acme/

Parameters:

• int $multiplier

Return:

• \Str

replace

Replaces all occurrences of $old in the string by $new.

$str = new Str('/Acme/');
echo (string)$str->replace('/', '#');
// #Acme#

Parameters:

• string $old
• string $new

Return:

• \Str

replaceWithLimit

Replace returns a copy of the string s with the first n non-overlapping instances of old replaced by new. If old is empty, it matches at the beginning of the string and after each UTF-8 sequence, yielding up to k+1 replacements for a k-rune string. If n < 0, there is no limit on the number of replacements.

$str = new Str('/Acme/');
echo (string)$str->replaceWithLimit('/', '#', 1);
// #Acme/

Parameters:

• string $old
• string $new
• int $limit

Return:

• \Str

reverse

Returns a reversed string. A multi-byte version of strrev().

$str = new Str('/Acme/');
echo (string)$str->reverse();
// /emcA/

Parameters: nothing

Return:

• \Str

safeTruncate

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.

$str = new Str('What are your plans today?');
echo (string)$str->safeTruncate(22, '...');
// What are your plans...

Parameters:

• int $length
• string $substring

Return:

• \Str

shift

Returns the substring of the original string from beginning to the first occurrence of $delimiter.

$str = new Str('Acme/foo');
echo $str->shift('/');
// Acme

Parameters:

• string $delimiter

Return:

• \Str

shiftReversed

Returns the substring of the original string from the first occurrence of $delimiter to the end.

$str = new Str('Acme/foo/bar');
echo $str->shiftReversed('/');
// foo/bar

Parameters:

• string $delimiter

Return:

• \Str

shuffle

A multi-byte str_shuffle() function. It returns a string with its characters in random order.

$str = new Str('/Acme/');
echo (string)$str->shuffle();
// mAe//c

Parameters: nothing

Return:

• \Str

slice

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.

$str = new Str('Acme');
echo (string)$str->slice(2);
// me

Parameters:

• int $start
• int|null $end

Return:

• \Str

slugify

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.

$str = new Str('Acme foo bar!');
echo (string)$str->slugify();
// acme-foo-bar

Parameters:

• string $replacement
• string $language

Return:

• \Str

snakeize

Returns a snake_case version of the string.

$str = new Str('Foo Bar');
echo (string)$str->snakeize();
// foo_bar

Parameters: nothing

Return:

• \Str

split

Splits the string with the provided $pattern, returning an array of strings. An optional integer $limit will truncate the results.

$str = new Str('Acme#Acme');
echo $str->split('#', 1);
// ['Acme']

Parameters:

• string $pattern
• int $limit

Return:

• array

startsWith

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.

$str = new Str('/Accmme/');
echo $str->startsWith('/A');
// true

Parameters:

• string $substring
• bool $caseSensitive

Return:

• bool

startsWithAny

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.

$str = new Str('/Accmme/');
echo $str->startsWithAny(['foo', '/A', 'bar']);
// true

Parameters:

• array $substrings
• bool $caseSensitive

Return:

• bool

stripWhitespace

Strip all whitespace characters. This includes tabs and newline characters, as well as multi-byte whitespace such as the thin space and ideographic space.

$str = new Str('Acme foo');
echo (string)$str->stripWhitespace();
// Acmefoo

Parameters: nothing

Return:

• \Str

substr

Returns the substring beginning at $start with the specified $length. It differs from the mb_substr() function in that providing a $length of 0 will return the rest of the string, rather than an empty string.

$str = new Str('/Acme/');
echo (string)$str->substr(1, 4);
// Acme

Parameters:

• int $start
• int $length

Return:

• \Str

surround

Surrounds the string with the given $substring.

$str = new Str('Acme');
echo (string)$str->surround('/');
// /Acme/

Parameters:

• string $substring

Return:

• \Str

swapCase

Returns a case swapped version of the string.

$str = new Str('foObARbAz');
echo (string)$str->swapCase();
// FOoBarBaZ

Parameters: nothing

Return:

• \Str

tidy

Returns a string with smart quotes, ellipsis characters, and dashes from Windows-1252 (commonly used in Word documents) replaced by their ASCII equivalents.

$str = new Str('“I see…”');
echo (string)$str->tidy();
// "I see..."

Parameters: nothing

Return:

• \Str

titleize

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.

$str = new Str('i like to watch DVDs at home');
echo (string)$str->titleize(['at', 'to', 'the']);
// I Like to Watch Dvds at Home

Parameters:

• array $ignore

Return:

• \Str

toAscii

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.

$str = new Str('Äcmế');
echo (string)$str->toAscii();
// Acme

Parameters:

• string $language
• bool $removeUnsupported

Return:

• \Str

toBoolean

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.

$str = new Str('yes');
echo $str->toBoolean();
// true

Parameters: nothing

Return:

• bool

toLowerCase

Make the string lowercase.

$str = new Str('/Acme/');
echo (string)$str->toLowerCase();
// /acme/

Parameters: nothing

Return:

• \Str

toSpaces

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.

$str = new Str('foo    bar');
echo (string)$str->toSpaces(0);
// foobar

Parameters:

• int $tabLength

Return:

• \Str

toTabs

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.

$str = new Str('foo bar');
echo (string)$str->toTabs();
// foo    bar

Parameters:

• int $tabLength

Return:

• \Str

toTitleCase

Converts the first character of each word in the string to uppercase.

$str = new Str('foo bar baz');
echo (string)$str->toTitleCase();
// Foo Bar Baz

Parameters: nothing

Return:

• \Str

toUpperCase

Make the string uppercase.

$str = new Str('/Acme/');
echo (string)$str->toUpperCase();
// /ACME/

Parameters: nothing

Return:

• \Str

trim

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.

$str = new Str('/Acme/');
echo (string)$str->trim('/');
// Acme

Parameters:

• string $chars

Return:

• \Str

trimLeft

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.

$str = new Str('/Acme/');
echo (string)$str->trimLeft('/');
// Acme/

Parameters:

• string $chars

Return:

• \Str

trimRight

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.

$str = new Str('/Acme/');
echo (string)$str->trimRight('/');
// /Acme

Parameters:

• string $chars

Return:

• \Str

truncate

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.

$str = new Str('What are your plans today?');
echo (string)$str->truncate(19, '...');
// What are your pl...

Parameters:

• int $length
• string $substring

Return:

• \Str

underscored

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.

$str = new Str('foo Bar baz');
echo (string)$str->underscored();
// foo_bar_baz

Parameters: nothing

Return:

• \Str

unquote

Unwraps each word in the original string, deleting the specified $quote.

$str = new Str('*foo* bar* ***baz*');
echo $str->unquote('*');
// foo bar baz

Parameters:

• string $quote

Return:

• \Str

upperCamelize

Returns an UpperCamelCase version of the string. It trims surrounding spaces, capitalizes letters following digits, spaces, dashes and underscores, and removes spaces, dashes, underscores.

$str = new Str('foo bar baz');
echo (string)$str->upperCamelize();
// FooBarBaz

Parameters: nothing

Return:

• \Str

upperCaseFirst

Converts the first character of the string to upper case.

$str = new Str('acme foo');
echo (string)$str->upperCaseFirst();
// Acme foo

Parameters: nothing

Return:

• \Str

words

Splits on whitespace, returning an array of strings corresponding to the words in the string.

$str = new Str('foo bar baz');
echo $str->words();
// ['foo', 'bar', 'baz']

Parameters: nothing

Return:

• array

Benchmark

lib code tests (versus):

make lib-code-tests

how to get total RANK:

make rank

generate md:

make md

run tests:

make test

Test subjects:

• FS (str/str)
• Stringy (danielstjules/Stringy)

RANK (sum time of all benchmarks): smaller - is better!

see all other benchmark results

Development

Please use php cs fixer before commit: https://github.com/FriendsOfPHP/PHP-CS-Fixer

you can add watcher in any IDE for automatic fix code style on save.