README

What is it

PhpSimpleRegex is an object oriented regular expressions library for PHP.

This library allows to execute preg_* functions in PHP and use the results as objects, making the use of preg_* functions testeable. PhpSimpleRegex is integrated with VerbalExpressions\PHPVerbalExpressions\VerbalExpressions, SelvinOrtiz\Utils\Flux\Flux and also MarkWilson\VerbalExpression to allow a full Object Oriented approach to Regular Expressions in PHP.

Installation

Composer:

If you want to access directly to this repo, adding this to your composer.json should be enough:

{
    "require": {
        "mcustiel/php-simple-regex": "*"
    }
}

Or just download the release and include it in your path.

How to use it?

This library provides a facade class that wraps most of the preg_* functions from PHP. All you need to do is to create an instance of this class and call the methods you need.

use Mcustiel\PhpSimpleRegex\Executor as RegexExecutor;

$regexFacade = new RegexExecutor();

List of methods:

• MatchResult getAllMatches(mixed $pattern, string $subject, integer $offset = 0)
• Match getOneMatch(mixed $pattern, string $subject, integer $offset = 0)
• boolean match(mixed $pattern, string $subject, integer $offset = 0)
• ReplaceResult replaceAndCount(mixed $pattern, string $replacement, mixed $subject, integer $limit = -1)
• mixed replace(mixed $pattern, string $replacement, mixed $subject, integer $limit = -1)
• mixed replaceCallback(mixed $pattern, callable $callback, mixed $subject, integer $limit = -1)
• ReplaceResult replaceCallbackAndCount(mixed $pattern, callable $callback, mixed $subject, integer $limit = -1)
• array split(mixed $pattern, string $string, integer $limit = -1, bool $returnOnlyNotEmpty = false, bool $captureOffset = false, bool $captureSubpatterns = false)
• array grep(mixed $pattern, array $input)
• array grepNotMatching(mixed $pattern, array $input)

For each method, the pattern can be a string, a Flux object, or a PhpVerbalExpression object.

Examples:

getAllMatches:

try {
    $result = $regexFacade->getAllMatches('/\d+/', 'ab12cd34ef56');
    echo 'Number of matches: ' . $result->getMatchesCount() . PHP_EOL; // Prints 3
    echo 'First match: ' . $result->getMatchAt(0)->getFullMatch() . PHP_EOL; // Prints 12
    
    // Iterate over results
    foreach ($result as $index => $match) {
        echo "Match at index {$index} is " . $match->getFullMatch() . PHP_EOL; 
    }
} catch (\Exception $e) {
    echo 'An error occurred executing getAllMatches';
}

getOneMatch:

try {
    $result = $regexFacade->getOneMatch('/\d+/', 'ab12cd34ef56');
    if (!empty($result)) {
        echo 'Match: ' . $result->getFullMatch() . PHP_EOL; // Prints 12
    }
} catch (\Exception $e) {
    echo 'An error occurred executing getOneMatch';
}

match:

try {
    if ($regexFacade->match('/\d+/', 'ab12cd34ef56')) {
        echo 'String matches pattern.'. PHP_EOL;
    } else {
        echo 'String does not match pattern.'. PHP_EOL;
    }
} catch (\Exception $e) {
    echo 'An error occurred executing match';
}

replaceAndCount:

try {
    // Subject can also be an array.
    $result = $this->executor->replaceAndCount('/\d+/', 'potato', 'ab12cd34ef56');
    echo 'Number of replacements: ' . $result->getReplacements() . PHP_EOL;
    echo 'Replaced string: ' . $result->getResult() . PHP_EOL;
} catch (\Exception $e) {
    echo 'An error occurred executing replaceAndCount';
}

replace:

try {
    // Subject can also be a string.
    $result = $this->executor->replaceAndCount('/\d+/', 'potato', ['ab12cd34ef56', 'ab12cd78ef90']);
    echo 'Replaced strings: ' . print_r($result->getResult(), true) . PHP_EOL;
} catch (\Exception $e) {
    echo 'An error occurred executing replace';
}

replaceCallback:

try {
    // Subject can also be an array.
    $result = $this->executor->replaceCallback('/\d+/', function () { return 'potato'; }, 'ab12cd34ef56');
    echo 'Replaced string: ' . $result->getResult() . PHP_EOL;
} catch (\Exception $e) {
    echo 'An error occurred executing replaceCallback';
}

replaceCallbackAndCount:

try {
    // Subject can also be an array.
    $result = $this->executor->replaceCallback('/\d+/', function () { return 'potato'; }, 'ab12cd34ef56');
    echo 'Number of replacements: ' . $result->getReplacements() . PHP_EOL;
    echo 'Replaced string: ' . $result->getResult() . PHP_EOL;
} catch (\Exception $e) {
    echo 'An error occurred executing replaceCallbackAndCount';
}