yiisoft / strings
Yii Strings Helper
Fund package maintenance!
Open Collective
yiisoft
Installs: 1 082 594
Dependents: 48
Suggesters: 0
Security: 0
Stars: 38
Watchers: 20
Forks: 14
Open Issues: 7
Requires
- php: ^8.0
- ext-mbstring: *
Requires (Dev)
- maglnet/composer-require-checker: ^4.2
- phpunit/phpunit: ^9.5
- rector/rector: ^0.18.3
- roave/infection-static-analysis-plugin: ^1.16
- spatie/phpunit-watcher: ^1.23
- vimeo/psalm: ^4.30|^5.8
README
Yii Strings
The package provides:
StringHelper
that has static methods to work with strings;NumericHelper
that has static methods to work with numeric strings;Inflector
provides methods such astoPlural()
ortoSlug()
that derive a new string based on the string given;WildcardPattern
is a shell wildcard pattern to match strings against;CombinedRegexp
is a wrapper that optimizes multiple regular expressions matching andMemoizedCombinedRegexp
is a decorator that caches results ofCombinedRegexp
to speed up matching.
Requirements
- PHP 8.0 or higher.
Installation
composer require yiisoft/strings --prefer-dist
StringHelper usage
String helper methods are static so usage is like the following:
echo \Yiisoft\Strings\StringHelper::countWords('Strings are cool!'); // 3
Overall the helper has the following method groups.
Bytes
- byteLength
- byteSubstring
File paths
- baseName
- directoryName
Substrings
- substring
- replaceSubstring
- startsWith
- startsWithIgnoringCase
- endsWith
- endsWithIgnoringCase
Truncation
- truncateBegin
- truncateMiddle
- truncateEnd
- truncateWords
- trim
- ltrim
- rtrim
Counting
- length
- countWords
Lowercase and uppercase
- lowercase
- uppercase
- uppercaseFirstCharacter
- uppercaseFirstCharacterInEachWord
URL friendly base64
- base64UrlEncode
- base64UrlDecode
Other
- parsePath
- split
NumericHelper usage
Numeric helper methods are static so usage is like the following:
echo \Yiisoft\Strings\NumericHelper::toOrdinal(3); // 3rd
The following methods are available:
- toOrdinal
- normalize
- isInteger
Inflector usage
echo (new \Yiisoft\Strings\Inflector()) ->withoutIntl() ->toSlug('Strings are cool!'); // strings-are-cool
Overall the inflector has the following method groups.
Plurals and singulars
- toPlural
- toSingular
Transliteration
- toTransliterated
Case conversion
- pascalCaseToId
- toPascalCase
- toCamelCase
Words and sentences
- toSentence
- toWords
- toHumanReadable
Classes and database tables
- classToTable
- tableToClass
URLs
- toSlug
WildcardPattern usage
WildcardPattern
allows a simple POSIX-style string matching.
use \Yiisoft\Strings\WildcardPattern; $startsWithTest = new WildcardPattern('test*'); if ($startsWithTest->match('testIfThisIsTrue')) { echo 'It starts with "test"!'; }
The following characters are special in the pattern:
\
escapes other special characters if usage of escape character is not turned off.*
matches any string, including the empty string, except delimiters (/
and\
by default).**
matches any string, including the empty string and delimiters.?
matches any single character.[seq]
matches any character in seq.[a-z]
matches any character from a to z.[!seq]
matches any character not in seq.[[:alnum:]]
matches POSIX style character classes.
ignoreCase()
could be called before doing a match()
to get a case-insensitive match:
use \Yiisoft\Strings\WildcardPattern; $startsWithTest = new WildcardPattern('test*'); if ($startsWithTest ->ignoreCase() ->match('tEStIfThisIsTrue')) { echo 'It starts with "test"!'; }
CombinedRegexp usage
CombinedRegexp
optimizes matching multiple regular expressions.
use \Yiisoft\Strings\CombinedRegexp; $patterns = [ 'first', 'second', '^a\d$', ]; $regexp = new CombinedRegexp($patterns, 'i'); $regexp->matches('a5'); // true – matches the third pattern $regexp->matches('A5'); // true – matches the third pattern because of `i` flag that is applied to all regular expressions $regexp->getMatchingPattern('a5'); // '^a\d$' – the pattern that matched $regexp->getMatchingPatternPosition('a5'); // 2 – the index of the pattern in the array $regexp->getCompiledPattern(); // '~(?|first|second()|^a\d$()())~'
MemoizedCombinedRegexp usage
MemoizedCombinedRegexp
caches results of CombinedRegexp
in memory.
It is useful when the same incoming string are matching multiple times or different methods of CombinedRegexp
are called.
use \Yiisoft\Strings\CombinedRegexp; use \Yiisoft\Strings\MemoizedCombinedRegexp; $patterns = [ 'first', 'second', '^a\d$', ]; $regexp = new MemoizedCombinedRegexp(new CombinedRegexp($patterns, 'i')); $regexp->matches('a5'); // Fires `preg_match` inside the `CombinedRegexp`. $regexp->matches('first'); // Fires `preg_match` inside the `CombinedRegexp`. $regexp->matches('a5'); // Does not fire `preg_match` inside the `CombinedRegexp` because the result is cached. $regexp->getMatchingPattern('a5'); // The result is cached so no `preg_match` is fired. $regexp->getMatchingPatternPosition('a5'); // The result is cached so no `preg_match` is fired. // The following code fires only once matching mechanism. if ($regexp->matches('second')) { echo sprintf( 'Matched the pattern "%s" which is on the position "%s" in the expressions list.', $regexp->getMatchingPattern('second'), $regexp->getMatchingPatternPosition('second'), ); }
Testing
Unit testing
The package is tested with PHPUnit. To run tests:
./vendor/bin/phpunit
Mutation testing
The package tests are checked with Infection mutation framework. To run it:
./vendor/bin/infection
Static analysis
The code is statically analyzed with Psalm. To run static analysis:
./vendor/bin/psalm
License
The Yii Strings is free software. It is released under the terms of the BSD License.
Please see LICENSE
for more information.
Maintained by Yii Software.