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 as toPlural() or toSlug() 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 and MemoizedCombinedRegexp is a decorator that caches results of CombinedRegexp to speed up matching.

Requirements

PHP 8.0 or higher.
mbstring PHP extension.

Installation

composer require yiisoft/strings

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
findBetween
findBetweenFirst
findBetweenLast

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 with Infection Static Analysis Plugin. To run it:

./vendor/bin/roave-infection-static-analysis-plugin

Static analysis

The code is statically analyzed with Psalm. To run static analysis:

./vendor/bin/psalm

Code style

Use Rector to make codebase follow some specific rules or use either newest or any specific version of PHP:

./vendor/bin/rector

Dependencies

Use ComposerRequireChecker to detect transitive Composer dependencies.

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.

yiisoft / strings

Maintainers

Details