@bjnstnkvc/str
v2.0.3
Published
JavaScript equivalent of Laravel Str helper.
Downloads
32
Readme
Str
JavaScript equivalent of Laravel Str helper.
Installation & setup
NPM
You can install the package via npm:
npm install @bjnstnkvc/str
and then import it into your project
import { Str } from '@bjnstnkvc/str'
CDN
You can install the package via jsDelivr CDN:
<script src="https://cdn.jsdelivr.net/npm/@bjnstnkvc/str/lib/main.min.js"></script>
Usage
Once imported, you can use these functions which provide a fluent interface to interact with Strings.
Strings
Str.after()
The Str.after
method returns everything after the given value in a string. The entire string will be returned if the value does not exist within the string:
Str.after('This is my name', 'This is');
// ' my name'
Str.afterLast()
The Str.afterLast
method returns everything after the last occurrence of the given value in a string. The entire
string will be returned if the value does not exist within the string:
Str.afterLast('App\\Http\\Controllers\\Controller', '\\');
// 'Controller'
Str.apa()
The Str.apa
method converts the given string to title case following
the APA guidelines:
Str.apa('Creating A Project');
// 'Creating a Project'
Str.ascii()
The Str.ascii
method will attempt to transliterate the string into an ASCII value:
Str.ascii('û');
// 'u'
Str.before()
The Str.before
method returns everything before the given value in a string:
Str.before('This is my name', 'my name');
// 'This is '
Str.beforeLast()
The Str.beforeLast
method returns everything before the last occurrence of the given value in a string:
Str.beforeLast('This is my name', 'is');
// 'This '
Str.between()
The Str.between
method returns the portion of a string between two values:
Str.between('This is my name', 'This', 'name');
// ' is my '
Str.betweenFirst()
The Str.betweenFirst
method returns the smallest possible portion of a string between two values:
Str.betweenFirst('[a] bc [d]', '[', ']');
// 'a'
Str.camel()
The Str.camel
method converts the given string to camelCase
:
Str.camel('foo_bar');
// 'fooBar'
Str.charAt()
The Str.charAt
method returns the character at the specified index. If the index is out of bounds, false is returned:
Str.charAt('This is my name.', 6);
// 's'
Str.contains()
The Str.contains
method determines if the given string contains the given value. This method is case-sensitive:
Str.contains('This is my name', 'my');
// true
You may also pass an array of values to determine if the given string contains any of the values in the array:
Str.contains('This is my name', ['my', 'foo']);
// true
Str.containsAll()
The Str.containsAll
method determines if the given string contains all the values in a given array:
Str.containsAll('This is my name', ['my', 'name']);
// true
Str.endsWith()
The Str.endsWith
method determines if the given string ends with the given value:
Str.endsWith('This is my name', 'name');
// true
You may also pass an array of values to determine if the given string ends with any of the values in the array:
Str.endsWith('This is my name', ['name', 'foo']);
// true
Str.endsWith('This is my name', ['this', 'foo']);
// false
Str.excerpt()
The Str.excerpt
method extracts an excerpt from a given string that matches the first instance of a phrase within that
string:
Str.excerpt('This is my name', 'my', { 'radius': 3 });
// '...is my na...'
The radius
option, which defaults to 100, allows you to define the number of characters that should appear on each side
of the truncated string.
In addition, you may use the omission option to define the string that will be prepended and appended to the truncated string:
Str.excerpt('This is my name', 'name', { 'radius': 3, 'omission': '(...) ' });
// '(...) my name'
Str.finish()
The Str.finish
method adds a single instance of the given value to a string if it does not already end with that
value:
Str.finish('this/string', '/');
// 'this/string/'
Str.finish('this/string/', '/');
// 'this/string/'
Str.fromBase64()
The Str.fromBase64
method converts the given string from Base64:
Str.fromBase64('TGFyYXZlbA==');
// 'Laravel'
Str.headline()
The Str.headline
method will convert strings delimited by casing, hyphens, or underscores into a space delimited
string
with each word's first letter capitalized:
Str.headline('steve_jobs');
// 'Steve Jobs'
Str.headline('EmailNotificationSent');
// 'Email Notification Sent'
Str.is()
The Str.is
method determines if a given string matches a given pattern. Asterisks may be used as wildcard values:
Str.is('foo*', 'foobar');
// true
Str.is('baz*', 'foobar');
// false
Str.isAscii()
The Str.isAscii
method determines if a given string is 7-bit ASCII:
Str.isAscii('Taylor');
// true
Str.isAscii('ü');
// false
Str.isJson()
The Str.isJson
method determines if the given string is valid JSON:
Str.isJson('[1,2,3]');
// true
Str.isJson('{"first": "John", "last": "Doe"}');
// true
Str.isJson('{first: "John", last: "Doe"}');
// false
Str.isUrl()
The Str.isUrl
method determines if the given string is a valid URL:
Str.isUrl('http://example.com');
// true
Str.isUrl('laravel');
// false
Str.isUlid()
The Str.isUlid
method determines if the given string is a valid ULID:
Str.isUlid('01gd6r360bp37zj17nxb55yv40');
// true
Str.isUlid('laravel');
// false
Str.isUuid()
The Str.isUuid
method determines if the given string is a valid UUID:
Str.isUuid('a0a2a2d2-0b87-4a18-83f2-2529882be2de');
// true
Str.isUuid('laravel');
// false
Str.kebab()
The Str.kebab
method converts the given string to kebab-case:
Str.kebab('fooBar');
// 'foo-bar'
Str.lcfirst()
The Str.lcfirst
method returns the given string with the first character lowercased:
Str.lcfirst('Foo Bar');
// 'foo Bar'
Str.length()
The Str.length
method returns the length of the given string:
Str.length('Laravel');
// 7
Str.limit()
The Str.limit
method truncates the given string to the specified length:
Str.limit('The quick brown fox jumps over the lazy dog', 20);
// 'The quick brown fox...'
You may pass a third argument to the method to change the string that will be appended to the end of the truncated string:
Str.limit('The quick brown fox jumps over the lazy dog', 20, ' (...)');
// 'The quick brown fox (...)'
Str.lower()
The Str.lower
method converts the given string to lowercase:
Str.lower('LARAVEL');
// 'laravel'
Str.mask()
The Str.mask
method masks a portion of a string with a repeated character, and may be used to obfuscate segments of
strings such as email addresses and phone numbers:
Str.mask('[email protected]', '*', 3);
// 'tay***************'
If needed, you provide a negative number as the third argument to the mask method, which will instruct the method to begin masking at the given distance from the end of the string:
Str.mask('[email protected]', '*', -15, 3);
// 'tay***@example.com'
Str.orderedUuid()
The Str.orderedUuid
method generates a "timestamp first" UUID that may be efficiently stored in an indexed database
column. Each UUID that is generated using this method will be sorted after UUIDs previously generated using the method:
Str.orderedUuid();
// '04fe4df5-7bae-45f4-8040-d0e4568f4054'
Str.padBoth()
The Str.padBoth
pads both sides of a string with another string until the final string reaches a desired length:
Str.padBoth('James', 10, '_');
// '__James___'
Str.padBoth('James', 10);
// ' James '
Str.padLeft()
The Str.padLeft
pads the left side of a string with another string until the final string reaches a desired length:
Str.padLeft('James', 10, '-=');
// '-=-=-James'
Str.padLeft('James', 10);
// ' James'
Str.padRight()
The Str.padRight
pads the right side of a string with another string until the final string reaches a desired length:
Str.padRight('James', 10, '-');
// 'James-----'
Str.padRight('James', 10);
// 'James '
Str.password()
The Str.password
method may be used to generate a secure, random password of a given length. The password will consist
of a combination of letters, numbers, symbols, and spaces. By default, passwords are 32 characters long:
Str.password();
// 'EbJo2vE-AS:U,$%_gkrV4n,q~1xy/-_4'
Str.password(12);
// 'qwuar>#V|i]N'
Str.plural()
The Str.plural
method converts a singular word string to its plural form.
Str.plural('car');
// 'cars'
Str.plural('child');
// 'children'
You may provide an integer as a second argument to the function to retrieve the singular or plural form of the string:
Str.plural('child', 2);
// 'children'
Str.plural('child', 1);
// 'child'
Str.pluralStudly()
The Str.pluralStudly
method converts a singular word string formatted in studly caps case to its plural form.
Str.pluralStudly('VerifiedHuman');
// 'VerifiedHumans'
Str.pluralStudly('UserFeedback');
// 'UserFeedback'
You may provide an integer as a second argument to the function to retrieve the singular or plural form of the string:
Str.pluralStudly('VerifiedHuman', 2);
// 'VerifiedHumans'
Str.pluralStudly('VerifiedHuman', 1);
// 'VerifiedHuman'
Str.random()
The Str.random
method generates a random string of the specified length:
Str.random(40);
Str.remove()
The Str.remove
method removes the given value or array of values from the string:
Str.remove('e', 'Peter Piper picked a peck of pickled peppers.');
// 'Ptr Pipr pickd a pck of pickld ppprs.'
You may also pass false as a third argument to the remove method to ignore case when removing strings.
Str.remove('E', 'Peter Piper picked a peck of pickled peppers.', false);
// 'Ptr Pipr pickd a pck of pickld ppprs.'
Str.repeat()
The Str.repeat
method repeats the given string:
Str.repeat('a', 5);
// 'aaaaa'
Str.replace()
The Str.replace
method replaces a given string within the string:
Str.replace('9.x', '10.x', 'Laravel 10.x');
// 'Laravel 9.x'
The replace
method also accepts a caseSensitive argument. By default, the replace method is case-sensitive:
Str.replace('framework', 'Laravel', 'Framework 10.x', false);
// 'Framework 10.x'
Str.replaceArray()
The Str.replaceArray
method replaces a given value in the string sequentially using an array:
Str.replaceArray('?', ['8:30', '9:00'], 'The event will take place between ? and ?');
// 'The event will take place between 8:30 and 9:00'
Str.replaceFirst()
The Str.replaceFirst
method replaces the first occurrence of a given value in a string:
Str.replaceFirst('the', 'a', 'the quick brown fox jumps over the lazy dog');
// 'a quick brown fox jumps over the lazy dog'
Str.replaceLast()
The Str.replaceLast
method replaces the last occurrence of a given value in a string:
Str.replaceLast('the', 'a', 'the quick brown fox jumps over the lazy dog');
// 'the quick brown fox jumps over a lazy dog'
Str.replaceMatches()
The Str.replaceMatches
method replaces all portions of a string matching a pattern with the given replacement string:
Str.replaceMatches('/[^A-Za-z0-9]+/', '', '(+1) 501-555-1000')
// '15015551000'
The replaceMatches
method also accepts a closure that will be invoked with each portion of the string matching the
given
pattern, allowing you to perform the replacement logic within the closure and return the replaced value:
Str.replaceMatches('/\\d/', (matches) => '[' + matches[0] + ']', '123');
// '[1][2][3]'
Str.replaceStart()
The Str.replaceStart
method replaces the first occurrence of the given value only if the value appears at the start of
the string:
Str.replaceStart('Hello', 'Laravel', 'Hello World');
// 'Laravel World'
Str.replaceStart('World', 'Laravel', 'Hello World');
// 'Hello World'
Str.replaceEnd()
The Str.replaceEnd
method replaces the last occurrence of the given value only if the value appears at the end of the
string:
Str.replaceEnd('World', 'Laravel', 'Hello World');
// 'Hello Laravel'
Str.replaceEnd('Hello', 'Laravel', 'Hello World');
// 'Hello World'
Str.reverse()
The Str.reverse
method reverses the given string:
Str.reverse('Hello World');
// 'dlroW olleH'
Str.singular()
The Str.singular
method converts a string to its singular form.
Str.singular('cars');
// 'car'
Str.singular('children');
// 'child'
Str.slug()
The Str.slug
method generates a URL friendly "slug" from the given string:
Str.slug('Laravel 5 Framework', '-');
// 'laravel-5-framework'
Str.snake()
The Str.snake
method converts the given string to snake_case:
Str.snake('fooBar');
// 'foo_bar'
Str.snake('fooBar', '-');
// 'foo-bar'
Str.squish()
The Str.squish
method removes all extraneous white space from a string, including extraneous white space between
words:
Str.squish(' laravel framework ');
// 'laravel framework'
Str.start()
The Str.start
method adds a single instance of the given value to a string if it does not already start with that
value:
Str.start('this/string', '/');
// '/this/string'
Str.start('/this/string', '/');
// '/this/string'
Str.startsWith()
The Str.startsWith
method determines if the given string begins with the given value:
Str.startsWith('This is my name', 'This');
// true
If an array of possible values is passed, the startsWith method will return true if the string begins with any of the given values:
Str.startsWith('This is my name', ['This', 'That', 'There']);
// true
Str.studly()
The Str.studly
method converts the given string to StudlyCase:
Str.studly('foo_bar');
// 'FooBar'
Str.substr()
The Str.substr
method returns the portion of string specified by the start and length parameters:
Str.substr('The Laravel Framework', 4, 7);
// 'Laravel'
Str.substrCount()
The Str.substrCount
method returns the number of occurrences of a given value in the given string:
Str.substrCount('If you like ice cream, you will like snow cones.', 'like');
// 2
Str.substrReplace()
The Str.substrReplace
method replaces text within a portion of a string, starting at the position specified by the
third
argument and replacing the number of characters specified by the fourth argument. Passing 0 to the method's fourth
argument will insert the string at the specified position without replacing any of the existing characters in the
string:
Str.substrReplace('1300', ':', 2);
// '13:'
Str.substrReplace('1300', ':', 2, 0);
// '13:00'
Str.swap()
The Str.swap
method replaces multiple values in the given string:
Str.swap({ 'Tacos': 'Burritos', 'great': 'fantastic' }, 'Tacos are great!');
// 'Burritos are fantastic!'
Str.title()
The Str.title
method converts the given string to Title Case:
Str.title('a nice title uses the correct case');
// 'A Nice Title Uses The Correct Case'
Str.toBase64()
The Str.toBase64
method converts the given string to Base64:
Str.toBase64('Laravel');
// 'TGFyYXZlbA=='
Str.ucfirst()
The Str.ucfirst
method returns the given string with the first character capitalized:
Str.ucfirst('foo bar');
// 'Foo bar'
Str.ucsplit()
The Str.ucsplit
method splits the given string into an array by uppercase characters:
Str.ucsplit('FooBar');
// [0 => 'Foo', 1 => 'Bar']
Str.upper()
The Str.upper
method converts the given string to uppercase:
Str.upper('laravel');
// 'LARAVEL'
Str.ulid()
The Str.ulid
method generates a ULID, which is a compact, time-ordered unique identifier:
Str.ulid();
// '01gd6r360bp37zj17nxb55yv40'
Str.unwrap()
The Str.unwrap
method removes the specified strings from the beginning and end of a given string:
Str.unwrap('-Laravel-', '-');
// 'Laravel'
Str.unwrap('{framework: "Laravel"}', '{', '}');
// 'framework: "Laravel"'
Str.uuid()
The Str.uuid
method generates a UUID (version 4):
Str.uuid();
// '39923a8e-d504-42b5-894f-55e79e6632dd '
Str.wordCount()
The Str.wordCount
method returns the number of words that a string contains:
Str.wordCount('Hello, world!');
// 2
Str.wordWrap()
The Str.wordWrap
method wraps a string to a given number of characters:
Str.wordWrap('The quick brown fox jumped over the lazy dog.', 20, "<br />\n");
/*
The `quick` brown fox<br />
jumped over the lazy<br />
dog.
*/
Str.words()
The Str.words
method limits the number of words in a string. An additional string may be passed to this method via its
third argument to specify which string should be appended to the end of the truncated string:
Str.words('Perfectly balanced, as all things should be.', 3, ' >>>');
// 'Perfectly balanced, as >>>'
Str.wrap()
The Str.wrap
method wraps the given string with an additional string or a pair of strings
Str.wrap('Laravel', '"');
// '"Laravel"'
Str.wrap('is', 'This ', ' Laravel!');
// 'This is Laravel!'
str()
The str
function returns a Stringable instance of the given string.
import { str } from '@bjnstnkvc/str'
This function is equivalent to the Str.of
method.
str('Taylor').append(' Otwell');
// 'Taylor Otwell'
Fluent Strings
Fluent strings provide a more fluent, object-oriented interface for working with string values, allowing you to chain multiple string operations together using a more readable syntax compared to traditional string operations.
after
The after
method returns everything after the given value in a string. The entire string will be returned if the value
does not exist within the string:
Str.of('This is my name').after('This is');
// ' my name'
afterLast
The afterLast
method returns everything after the last occurrence of the given value in a string. The entire string will
be returned if the value does not exist within the string:
Str.of('App\\Http\\Controllers\\Controller').afterLast('\\');
// 'Controller'
apa
The apa
method converts the given string to title case following the APA guidelines:
Str.of('a nice title uses the correct case').apa();
// A Nice Title Uses the Correct Case
append
The append
method appends the given values to the string:
Str.of('Taylor').append(' Otwell');
// 'Taylor Otwell'
ascii
The ascii
method will attempt to transliterate the string into an ASCII value:
Str.of('ü').ascii();
// 'u'
basename
The basename
method will return the trailing name component of the given string:
Str.of('/foo/bar/baz').basename();
// 'baz'
If needed, you may provide an "extension" that will be removed from the trailing component:
Str.of('/foo/bar/baz.jpg').basename('.jpg');
// 'baz'
before
The before
method returns everything before the given value in a string:
Str.of('This is my name').before('my name');
// 'This is '
beforeLast
The beforeLast
method returns everything before the last occurrence of the given value in a string:
Str.of('This is my name').beforeLast('is');
// 'This '
between
The between
method returns the portion of a string between two values:
Str.of('This is my name').between('This', 'name');
// ' is my '
betweenFirst
The betweenFirst
method returns the smallest possible portion of a string between two values:
Str.of('[a] bc [d]').betweenFirst('[', ']');
// 'a'
camel
The camel
method converts the given string to camelCase:
Str.of('foo_bar').camel();
// 'fooBar'
charAt
The charAt
method returns the character at the specified index. If the index is out of bounds, false
is returned:
Str.of('This is my name.').charAt(6);
// 's'
classBasename
The classBasename
method returns the class name of the given class with the class's namespace removed:
Str.of('Foo\\Bar\\Baz').classBasename();
// 'Baz'
contains
The contains
method determines if the given string contains the given value. This method is case-sensitive:
Str.of('This is my name').contains('my');
// true
You may also pass an array of values to determine if the given string contains any of the values in the array:
Str.of('This is my name').contains(['my', 'foo']);
// true
containsAll
The containsAll
method determines if the given string contains all the values in the given array:
Str.of('This is my name').containsAll(['my', 'name']);
// true
dirname
The dirname
method return the parent directory portion of the given string:
Str.of('/foo/bar/baz').dirname();
// '/foo/bar'
If necessary, you may specify how many directory levels you wish to trim from the string:
Str.of('/foo/bar/baz').dirname(2);
// '/foo'
excerpt
The excerpt
method extracts an excerpt from the string that matches the first instance of a phrase within that string:
Str.of('This is my name').excerpt('my', { 'radius': 3 });
// '...is my na...'
The radius
option, which defaults to 100, allows you to define the number of characters that should appear on each side
of the truncated string.
In addition, you may use the omission option to change the string that will be prepended and appended to the truncated string:
Str.of('This is my name').excerpt('name', { 'radius': 3, 'omission': '(...) ' });
// '(...) my name'
endsWith
The endsWith
method determines if the given string ends with the given value:
Str.of('This is my name').endsWith('name');
// true
You may also pass an array of values to determine if the given string ends with any of the values in the array:
Str.of('This is my name').endsWith(['name', 'foo']);
// true
Str.of('This is my name').endsWith(['this', 'foo']);
// false
exactly
The exactly
method determines if the given string is an exact match with another string:
Str.of('Laravel').exactly('Laravel');
// true
explode
The explode
method splits the string by the given delimiter and returns an array containing each section of the split
string:
Str.of('foo bar baz').explode(' ');
// ['foo', 'bar', 'baz']
finish
The finish
method adds a single instance of the given value to a string if it does not already end with that value:
Str.of('this/string').finish('/');
// 'this/string/'
Str.of('this/string/').finish('/');
// 'this/string/'
fromBase64
The fromBase64
method converts the given string from Base64:
Str.of('TGFyYXZlbA==').fromBase64();
// 'Laravel'
headline
The headline
method will convert strings delimited by casing, hyphens, or underscores into a space delimited string with
each word's first letter capitalized:
Str.of('taylor_otwell').headline();
// 'Taylor Otwell'
Str.of('EmailNotificationSent').headline();
// 'Email Notification Sent'
is
The is
method determines if a given string matches a given pattern. Asterisks may be used as wildcard values
Str.of('foobar').is('foo*');
// true
Str.of('foobar').is('baz*');
// false
isAscii
The isAscii
method determines if a given string is an ASCII string:
Str.of('Taylor').isAscii();
// true
Str.of('ü').isAscii();
// false
isEmpty
The isEmpty
method determines if the given string is empty:
Str.of(' ').trim().isEmpty();
// true
Str.of('Laravel').trim().isEmpty();
// false
isNotEmpty
The isNotEmpty
method determines if the given string is not empty:
Str.of(' ').trim().isNotEmpty();
// false
Str.of('Laravel').trim().isNotEmpty();
// true
isJson
The isJson
method determines if a given string is valid JSON:
Str.of('[1,2,3]').isJson();
// true
Str.of('{"first": "John", "last": "Doe"}').isJson();
// true
Str.of('{first: "John", last: "Doe"}').isJson();
// false
isUlid
The isUlid
method determines if a given string is a ULID:
Str.of('01gd6r360bp37zj17nxb55yv40').isUlid();
// true
Str.of('Taylor').isUlid();
// false
isUrl
The isUrl
method determines if a given string is a URL:
Str.of('http://example.com').isUrl();
// true
Str.of('Taylor').isUrl();
// false
isUuid
The isUuid
method determines if a given string is a UUID:
Str.of('5ace9ab9-e9cf-4ec6-a19d-5881212a452c').isUuid();
// true
Str.of('Taylor').isUuid();
// false
kebab
The kebab
method converts the given string to kebab-case:
Str.of('fooBar').kebab();
// 'foo-bar'
lcfirst
The lcfirst
method returns the given string with the first character lowercased:
Str.of('Foo Bar').lcfirst();
// 'foo Bar'
length
The length
method returns the length of the given string:
Str.of('Laravel').length();
// 7
limit
The limit
method truncates the given string to the specified length:
Str.of('The quick brown fox jumps over the lazy dog').limit(20);
// 'The quick brown fox...'
You may also pass a second argument to change the string that will be appended to the end of the truncated string:
Str.of('The quick brown fox jumps over the lazy dog').limit(20, ' (...)');
// 'The quick brown fox (...)'
lower
The lower
method converts the given string to lowercase:
Str.of('LARAVEL').lower();
// 'laravel'
ltrim
The ltrim
method trims the left side of the string:
Str.of(' Laravel ').ltrim();
// 'Laravel '
Str.of('/Laravel/').ltrim('/');
// 'Laravel/'
mask
The mask
method masks a portion of a string with a repeated character, and may be used to obfuscate segments of strings
such as email addresses and phone numbers:
Str.of('[email protected]').mask('*', 3);
// 'tay***************'
If needed, you may provide negative numbers as the third or fourth argument to the mask method, which will instruct the method to begin masking at the given distance from the end of the string:
Str.of('[email protected]').mask('*', -15, 3);
// 'tay***@example.com'
Str.of('[email protected]').mask('*', 4, -4);
// 'tayl**********.com'
match
The match
method will return the portion of a string that matches a given regular expression pattern:
Str.of('foo bar').match('/bar/');
// 'bar'
Str.of('foo bar').match('/foo (.*)/');
// 'bar'
matchAll
The matchAll
method will return an array containing the portions of a string that match a given regular expression
pattern:
Str.of('bar foo bar').matchAll('/bar/');
// ['bar', 'bar']
If you specify a matching group within the expression, method will return an array of that group's matches:
Str.of('bar fun bar fly').matchAll('/f(\\w*)/');
// ['un', 'ly'];
If no matches are found, an empty array will be returned.
isMatch
The isMatch
method will return true if the string matches a given regular expression:
Str.of('foo bar').isMatch('/foo (.*)/');
// true
Str.of('laravel').isMatch('/foo (.*)/');
// false
newLine
The newLine
method appends an "end of line" character to a string:
Str.of('Laravel').newLine().append('Framework');
// 'Laravel
// Framework'
padBoth
The padBoth
method pads both sides of a string with another string until the final string reaches the desired length:
Str.of('James').padBoth(10, '_');
// '__James___'
Str.of('James').padBoth(10);
// ' James '
padLeft
The padLeft
pads the left side of a string with another string until the final string reaches the desired length:
Str.of('James').padLeft(10, '-=');
// '-=-=-James'
Str.of('James').padLeft(10);
// ' James'
padRight
The padRight
method pads the right side of a string with another string until the final string reaches the desired
length:
Str.of('James').padRight(10, '-');
// 'James-----'
Str.of('James').padRight(10);
// 'James '
pipe
The pipe
method allows you to transform the string by passing its current value to the given callable:
Str.of('Laravel').pipe('btoa').prepend('Base64 Encoded: ');
// 'Base64 Encoded: TGFyYXZlbA=='
Str.of('TGFyYXZlbA==').pipe('atob').prepend('Base64 Encoded: ');
// 'Base64 Decoded: Laravel'
Str.of('Laravel Framework').pipe('toUpperCase');
// 'LARAVEL FRAMEWORK'
Str.of('LARAVEL FRAMEWORK').pipe((string) => string.title());
// 'Laravel Framework'
Str.of('foo').pipe(string => 'bar');
// 'bar'
plural
The plural
method converts a singular word string to its plural form.
Str.of('car').plural();
// 'cars'
Str.of('child').plural();
// 'children'
You may provide an integer as a second argument to the function to retrieve the singular or plural form of the string:
Str.of('child').plural(2);
// 'children'
Str.of('child').plural(1);
// 'child'
position
The position
method returns the position of the first occurrence of a substring in a string. If the substring does not exist within the string, false
is returned:
Str.of('Hello, World!').position('Hello');
// 0
Str.of('Hello, World!').position('W');
// 7
You may provide an integer as a second argument to the function to retrieve the singular or plural form of the string:
Str.of('child').plural(2);
// 'children'
Str.of('child').plural(1);
// 'child'
prepend
The prepend
method prepends the given values onto the string:
Str.of('Framework').prepend('Laravel ');
// 'Laravel Framework'
remove
The remove
method removes the given value or array of values from the string:
Str.of('Arkansas is quite beautiful!').remove('quite ');
// 'Arkansas is beautiful!'
You may also pass false as a second parameter to ignore case when removing strings.
repeat
The repeat
method repeats the given string:
Str.of('a').repeat(5);
// 'aaaaa'
replace
The replace
method replaces a given string within the string:
Str.of('Laravel 9.x').replace('9.x', '10.x');
// 'Laravel 10.x'
The replace
method also accepts a caseSensitive
argument. By default, the replace method is case-sensitive:
Str.of('macOS 13.x').replace('macOS', 'iOS', false);
replaceArray
The replaceArray
method replaces a given value in the string sequentially using an array:
Str.of('The event will take place between ? and ?').replaceArray('?', ['8:30', '9:00']);
// 'The event will take place between 8:30 and 9:00'
replaceFirst
The replaceFirst
method replaces the first occurrence of a given value in a string:
Str.of('the quick brown fox jumps over the lazy dog').replaceFirst('the', 'a');
// 'a quick brown fox jumps over the lazy dog'
replaceLast
The replaceLast
method replaces the last occurrence of a given value in a string:
Str.of('the quick brown fox jumps over the lazy dog').replaceLast('the', 'a');
// 'the quick brown fox jumps over a lazy dog'
replaceMatches
The replaceMatches
method replaces all portions of a string matching a pattern with the given replacement string:
Str.of('(+1) 501-555-1000').replaceMatches('/[^A-Za-z0-9]+/', '');
// '15015551000'
The replaceMatches
method also accepts a closure that will be invoked with each portion of the string matching the given
pattern, allowing you to perform the replacement logic within the closure and return the replaced value:
Str.of('123').replaceMatches('/\\d/', (match) => '[' + match[0] + ']');
// '[1][2][3]'
replaceStart
The replaceStart
method replaces the first occurrence of the given value only if the value appears at the start of the string:
Str.of('Hello World').replaceStart('Hello', 'Laravel');
// 'Laravel World'
Str.of('Hello World').replaceStart('World', 'Laravel');
// 'Hello World'
replaceEnd
The replaceEnd
method replaces the last occurrence of the given value only if the value appears at the end of the string:
Str.of('Hello World').replaceEnd('World', 'Laravel');
// 'Hello Laravel'
Str.of('Hello World').replaceEnd('Hello', 'Laravel');
// 'Hello World'
rtrim
The rtrim
method trims the right side of the given string:
Str.of(' Laravel ').rtrim();
// ' Laravel'
Str.of('/Laravel/').rtrim('/');
// '/Laravel'
singular
The singular
method converts a string to its singular form.
Str.of('cars').singular();
// 'car'
Str.of('children').singular();
// 'child'
slug
The slug
method generates a URL friendly "slug" from the given string:
Str.of('Laravel Framework').slug('-');
// 'laravel-framework'
snake
The snake
method converts the given string to snake_case:
Str.of('fooBar').snake();
// 'foo_bar'
split
The split
method splits a string into an array using a regular expression:
Str.of('one, two, three').split('/[\s,]+/');
// ["one", "two", "three"]
squish
The squish
method removes all extraneous white space from a string, including extraneous white space between words:
Str.of(' laravel framework ').squish();
// 'laravel framework'
start
The start
method adds a single instance of the given value to a string if it does not already start with that value:
Str.of('this/string').start('/');
// '/this/string'
Str.of('/this/string').start('/');
// '/this/string'
startsWith
The startsWith
method determines if the given string begins with the given value:
Str.of('This is my name').startsWith('This');
// true
studly
The studly
method converts the given string to StudlyCase:
Str.of('foo_bar').studly();
// 'FooBar'
substr
The substr
method returns the portion of the string specified by the given start and length parameters:
Str.of('Laravel Framework').substr(8);
// 'Framework'
Str.of('Laravel Framework').substr(8, 5);
// 'Frame'
substrReplace
The substrReplace
method replaces text within a portion of a string, starting at the position specified by the second
argument and replacing the number of characters specified by the third argument. Passing 0
to the method's third
argument will insert the string at the specified position without replacing any of the existing characters in the
string:
Str.of('1300').substrReplace(':', 2);
// '13:'
Str.of('The Framework').substrReplace(' Laravel', 3, 0);
// 'The Laravel Framework'
swap
The swap
method replaces multiple values in the string:
Str.of('Tacos are great!').swap({ 'Tacos': 'Burritos', 'great': 'fantastic' });
// 'Burritos are fantastic!'
take
The take
method returns a specified number of characters from the beginning of the string:
Str.of('Build something amazing!').take(5);
// 'Build'
tap
The tap
method passes the string to the given closure, allowing you to examine and interact with the string while not
affecting the string itself. The original string is returned by the tap
method regardless of what is returned by the
closure:
Str.of('Laravel')
.append(' Framework')
.tap((string) => string.dump())
.upper();
// 'LARAVEL FRAMEWORK'
test
The test
method determines if a string matches the given regular expression pattern:
Str.of('Laravel Framework').test('/Laravel/');
// true
title
The title
method converts the given string to Title Case:
Str.of('a nice title uses the correct case').title();
// 'A Nice Title Uses The Correct Case'
toBase64
The toBase64
method converts the given string to Base64:
Str.of('Laravel').toBase64();
// 'TGFyYXZlbA=='
toHtmlString
The toHtmlString
method converts the string instance to an instance of HTMLElement, which may be displayed in HTML:
Str.of('<input type="text" placeholder="Hello">').toHtmlString();
<input type="text" placeholder="Hello">
If no valid HTML is provided to the method, the method returns an instance of string
:
Str.of('Hello').toHtmlString();
// 'Hello'
trim
The trim
method trims the given string:
Str.of(' Laravel ').trim();
// 'Laravel'
Str.of('/Laravel/').trim('/');
// 'Laravel'
ucfirst
The ucfirst
method returns the given string with the first character capitalized:
Str.of('foo bar').ucfirst();
// 'Foo bar'
ucsplit
The ucsplit
method splits the given string into an array by uppercase characters:
Str.of('Foo Bar').ucsplit();
// ['Foo', 'Bar']
unwrap
The unwrap
method removes the specified strings from the beginning and end of a given string:
Str.of('-Laravel-').unwrap('-');
// 'Laravel'
Str.of('{framework: "Laravel"}').unwrap('{', '}');
// 'framework: "Laravel"'
upper
The upper
method converts the given string to uppercase:
Str.of('laravel').upper();
// 'LARAVEL'
when
The when
method invokes the given closure if a given condition is true. The closure will receive the fluent string
instance:
Str.of('Taylor').when(true, (string) => string.append(' Otwell'));
// 'Taylor Otwell'
Or, if you are using TypeScript:
Str.of('Taylor').when(true, (string: Stringable) => string.append(' Otwell'));
// 'Taylor Otwell'
If necessary, you may pass another closure as the third parameter to the when
method. This closure will execute if the
condition parameter evaluates to false.
whenContains
The whenContains
method invokes the given closure if the string contains the given value. The closure will receive the
fluent string instance:
Str.of('tony stark').whenContains('tony', (string) => string.title());
// 'Tony Stark'
Or, if you are using TypeScript:
Str.of('tony stark').whenContains('tony', (string: Stringable) => string.title());
// 'Tony Stark'
If necessary, you may pass another closure as the third parameter to the when
method. This closure will execute if the
string does not contain the given value.
You may also pass an array of values to determine if the given string contains any of the values in the array:
Str.of('tony stark').whenContains(['tony', 'hulk'], (string) => string.title());
// Tony Stark
Or, if you are using TypeScript:
Str.of('tony stark').whenContains(['tony', 'hulk'], (string: Stringable) => string.title());
// Tony Stark
whenContainsAll
The whenContainsAll
method invokes the given closure if the string contains all the given sub-strings. The closure
will receive the fluent string instance:
Str.of('tony stark').whenContainsAll(['tony', 'stark'], (string) => string.title());
// 'Tony Stark'
Or, if you are using TypeScript:
Str.of('tony stark').whenContainsAll(['tony', 'stark'], (string: Stringable) => string.title());
// 'Tony Stark'
If necessary, you may pass another closure as the third parameter to the when
method. This closure will execute if the
condition parameter evaluates to false.
whenEmpty
The whenEmpty
method invokes the given closure if the string is empty. If the closure returns a value, that value will
also be returned by the whenEmpty method. If the closure does not return a value, the fluent string instance will be
returned:
Str.of(' ').whenEmpty((string) => string.trim().prepend('Laravel'));
// 'Laravel'
Or, if you are using TypeScript:
Str.of(' ').whenEmpty((string: Stringable) => string.trim().prepend('Laravel'));
// 'Laravel'
whenNotEmpty
The whenNotEmpty
method invokes the given closure if the string is not empty. If the closure returns a value, that value
will also be returned by the whenNotEmpty method. If the closure does not return a value, the fluent string instance
will be returned:
Str.of('Framework').whenNotEmpty((string) => string.prepend('Laravel '));
// 'Laravel Framework'
Or, if you are using TypeScript:
Str.of('Framework').whenNotEmpty((string: Stringable) => string.prepend('Laravel '));
// 'Laravel Framework'
whenStartsWith
The whenStartsWith
method invokes the given closure if the string starts with the given sub-string. The closure will
receive the fluent string instance:
Str.of('disney world').whenStartsWith('disney', (string) => string.title());
// 'Disney World'
Or, if you are using TypeScript:
Str.of('disney world').whenStartsWith('disney', (string: Stringable) => string.title());
// 'Disney World'
whenEndsWith
The whenEndsWith
method invokes the given closure if the string ends with the given sub-string. The closure will receive
the fluent string instance:
Str.of('disney world').whenEndsWith('world', (string) => string.title());
// 'Disney World'
Or, if you are using TypeScript:
Str.of('disney world').whenEndsWith('world', (string: Stringable) => string.title());
// 'Disney World'
whenExactly
The whenExactly
method invokes the given closure if the string exactly matches the given string. The closure will
receive the fluent string instance:
Str.of('laravel').whenExactly('laravel', (string) => string.title());
// 'Laravel'
Or, if you are using TypeScript:
Str.of('laravel').whenExactly('laravel', (string: Stringable) => string.title());
// 'Laravel'
whenNotExactly
The whenNotExactly
method invokes the given closure if the string does not exactly match the given string. The closure
will receive the fluent string instance:
Str.of('framework').whenNotExactly('laravel', (string) => string.title());
// 'Framework'
Or, if you are using TypeScript:
Str.of('framework').whenNotExactly('laravel', (string: Stringable) => string.title());
// 'Framework'
whenIs
The whenIs
method invokes the given closure if the string matches a given pattern. Asterisks may be used as wildcard
values. The closure will receive the fluent string instance:
Str.of('foo/bar').whenIs('foo/*', (string) => string.append('/baz'));
// 'foo/bar/baz'
Or, if you are using TypeScript:
Str.of('foo/bar').whenIs('foo/*', (string: Stringable) => string.append('/baz'));
// 'foo/bar/baz'
whenIsAscii
The whenIsAscii
method invokes the given closure if the string is 7-bit ASCII. The closure will receive the fluent
string instance:
Str.of('laravel').whenIsAscii((string) => string.title());
// 'Laravel'
Or, if you are using TypeScript:
Str.of('laravel').whenIsAscii((string: Stringable) => string.title());
// 'Laravel'
whenIsUlid
The whenIsUlid
method invokes the given closure if the string is a valid ULID. The closure will receive the fluent
string instance:
Str.of('01gd6r360bp37zj17nxb55yv40').whenIsUlid((string) => string.substr(0, 8));
// '01gd6r36'
Or, if you are using TypeScript:
Str.of('01gd6r360bp37zj17nxb55yv40').whenIsUlid((string: Stringable) => string.substr(0, 8));
// '01gd6r36'
whenIsUuid
The whenIsUuid
method invokes the given closure if the string is a valid UUID. The closure will receive the fluent
string instance:
Str.of('a0a2a2d2-0b87-4a18-83f2-2529882be2de').whenIsUuid((string) => string.substr(0, 8));
// 'a0a2a2d2'
Or, if you are using TypeScript:
Str.of('a0a2a2d2-0b87-4a18-83f2-2529882be2de').whenIsUuid((string: Stringable) => string.substr(0, 8));
// 'a0a2a2d2'
whenTest
The whenTest
method invokes the given closure if the string matches the given regular expression.
receive the fluent string instance:
Str.of('laravel framework').whenTest('/laravel/', (string) => string.title());
// 'Laravel Framework'
Or, if you are using TypeScript:
Str.of('laravel framework').whenTest('/laravel/', (string: Stringable) => string.title());
// 'Laravel Framework'
wordCount
The wordCount
method returns the number of words that a string contains:
Str.of('Hello, world!').wordCount();
// 2
words
The words
method limits the number of words in a string. If necessary, you may specify an additional string that will be
appended to the truncated string:
Str.of('Perfectly balanced, as all things should be.').words(3, ' >>>');
// 'Perfectly balanced, as >>>'
Miscellaneous
dd
The dd
method dumps the given string and end execution of the script:
Str.of('Laravel').dd();
// 'Laravel'
If you do not want to halt the execution of your script, use the dump
function instead.
dump
The dump
method dumps the given string to the console:
Str.of('Laravel').dump();
// 'Laravel'
toString
Get the raw string value.
Str.of('Laravel').toString();
// 'Laravel'
toInteger
The toInteger
method returns the underlying string value as an integer.
Str.of('1').toInteger();
// 1
Str.of('Laravel').toInteger();
// 0
In case the underlying string value is not a number, method will return 0.
toFloat
The toFloat
method returns underlying string value as a float.
Str.of('1.5').toFloat();
// 1.5
Str.of('Laravel').toFloat();
// 0
In case the underlying string value is not a number, method will return 0.
toBoolean
The toBoolean
method returns underlying string value as a boolean.
Str.of('true').toBoolean();
// true
Str.of('Laravel').toBoolean();
// false
The toBoolean
method returns true when value is 1
, true
, on
, and yes
. Otherwise, returns false
.
toDate
Get the underlying string value as a formatted Date string.
Str.of('13 September 2023, 12:00 PM').toDate();
// 9/13/2023, 12:00:00
You may provide a string as a second and/or third argument to the function in order to format the date and set the Timezone respectively:
Str.of('13 September 2023, 12:00 PM').toDate('Y-m-d H:i:s', 'Europe/London');
// '2023-09-13 11:00:00'
Str.of('13 September 2023, 12:00 PM').toDate('Y-m-d H:i:s', 'America/Toronto');
// '2023-09-13 06:00:00'
Table of all format options and their examples can be found below:
| Format character | Description | Example | |------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------| | d | Day of the month, 2 digits with leading zeros. | 01 to 31 | | D | A textual representation of a day, three letters. | Mon through Sun | | j | Day of the month without leading zeros. | 1 to 31 | | l | A full textual representation of the day of the week. | Sunday through Saturday | | N | ISO 8601 numeric representation of the day of the week. | 1 (for Monday) through 7 (for Sunday) | | S | English ordinal suffix for the day of the month, 2 characters. | st, nd, rd or th | | w | Numeric representation of the day of the week. | 0 (for Sunday) through 6 (for Saturday) | | z | Numeric representation of the day of the week. | The day of the year (starting from 0) | | W | ISO 8601 week number of year, weeks starting on Monday. | 42 (the 42nd week in the year) | | F | A full textual representation of a month, such as January or March. | January through December | | m | Numeric representation of a month, with leading zeros. | 01 through 12 | | M | A short textual representation of a month, three letters. | Jan through Dec | | n | Numeric representation of a month, without leading zeros. | 1 through 12 | | t | Number of days in the given month. | 28 through 31 | | L | Whether it's a leap year. | 1 if it is a leap year, 0 otherwise | | o | ISO 8601 week-numbering year. This has the same value as Y, except that if the ISO week number (W) belongs to the previous or next year, that year is used instead. | 1999 or 2003 | | X | An expanded full numeric representation of a year, at least 4 digits, with for years BCE, and + for years CE. | -0055, +0787, +1999, +10191 | | x | An expanded full numeric representation if required, or a standard full numeral representation if possible (like Y). At least four digits. Years BCE are prefixed with a -. Years beyond (and including) 10000 are prefixed by a +. | -0055, 0787, 1999, +10191 | | Y | A full numeric representation of a year, at least 4 digits, with for years BCE. | -0055, 0787, 1999, 2003, 10191 | | y | A two-digit representation of a year. | 99 or 03 | | a | Lowercase Ante meridiem and Post meridiem. | am or pm | | A | Uppercase Ante meridiem and Post meridiem. | AM or PM | | B | Swatch Internet time. | 000 through 999 | | g | 12-hour format of an hour without leading zeros. | 1 through 12 | | G | 24-hour format of an hour without leading zeros. | 0 through 23 | | h | 12-hour format of an hour with leading zeros. | 01 through 12 | | H | 24-hour format of an hour with leading zeros. | 00 through 23 | | i | Minutes with leading zeros. | 00 to 59 | | s | Seconds with leading zeros. | 00 to 59 | | u | Microseconds. | 654321 | | v | Milliseconds. | 654 | | e | Timezone identifier. | UTC, GMT, Atlantic/Azores | | I | Whether or not the date is in daylight saving time. | 1 if Daylight Saving Time, 0 otherwise | | O | Difference to Greenwich time (GMT) without colon between hours and minutes. | +0200 | | P | Difference to Greenwich time (GMT) with colon between hours and minutes | +02:00 | | p | The same as P, but returns Z instead of +00:00. | +02:00 | | T | Timezone abbreviation, if known; otherwise the GMT offset. | EST, MDT, +05 | | Z | Timezone offset in seconds. The offset for timezones west of UTC is always negative, and for those east of UTC is always positive. | -43200 through 50400 | | c | ISO 8601 date. | 2004-02-12T15:19:21+00:00 | | r | Seconds since the Unix Epoch. | January 1 1970 00:00:00 GMT | | U | RFC 2822/RFC 5322 formatted date. | Thu, 21 Dec 2000 16:01:07 +0200 |
Providing incorrect Date/Time string will result in an error:
Str.of('Laravel').toDate();
// 'Invalid Date'