spatie/regex

You can install the package using composer to get a cleaner interface for PHP's built-in preg_* functions.

composer require spatie/regex

Instead of checking preg_last_error(), spatie/regex throws a RegexFailed exception whenever a regex operation fails. This allows you to use standard PHP try/catch blocks for error handling.

try {
    Regex::match('/(unclosed-group/', 'abc');
} catch (\Spatie\Regex\RegexFailed $exception) {
    // Handle error
}

Use Regex::matchAll() to find all occurrences of a pattern in a subject. It returns a MatchAllResult object.

MatchAllResult Methods

• hasMatch(): bool: Returns true if at least one match was found.
• results(): array: Returns an array of MatchResult objects, allowing you to iterate through every match and access groups via group() or the full match via result().

use Spatie\Regex\Regex;

$allMatches = Regex::matchAll('/ab([a-z])/', 'abcabd');

if ($allMatches->hasMatch()) {
    foreach ($allMatches->results() as $match) {
        echo $match->result(); // 'abc', then 'abd'
        echo $match->group(1); // 'c', then 'd'
    }
}

When using a matchAll operation, the MatchAllResult object contains the aggregate result. You can call the results() method to transform the raw matches into an array of individual MatchResult objects. This allows you to iterate over each specific match found in the subject string and access its specific capture groups.

/** @var MatchAllResult $matchAllResult */
$individualResults = $matchAllResult->results();

foreach ($individualResults as $result) {
    // Each $result is an instance of Spatie\Regex\MatchResult
    if ($result->hasMatch()) {
        // Access specific match data
    }
}

To perform a single regex match and obtain a MatchResult object, use the static for() method. This method executes the pattern against the subject using preg_match with the PREG_UNMATCHED_AS_NULL flag. If the regex pattern is invalid or fails, it throws a Spatie\Regex\Exceptions\RegexFailed exception.

use Spatie\Regex\MatchResult;

$matchResult = MatchResult::for('/pattern/', 'subject string');

Once you have a MatchResult instance, you can inspect the match status and extract the matched content using the following methods:

• hasMatch(): Returns true if the pattern matched the subject, false otherwise.
• result(): Returns the full match (the first element of the matches array) as a string, or null if no match was found.
• resultOr(string $default): Returns the full match as a string, or the provided $default value if no match was found.

$matchResult = MatchResult::for('/(\d+)/', 'ID: 123');

if ($matchResult->hasMatch()) {
    $fullMatch = $matchResult->result(); // '123'
    $fallback = $matchResult->resultOr('none');
}

Once you have a ReplaceResult instance, you can access the outcome of the operation using the following methods:

• result(): Returns the transformed string or array (depending on the input subject).
• count(): Returns the int number of replacements that were actually performed.

$result = ReplaceResult::for('/pattern/', 'replacement', 'subject', -1);

$transformed = $result->result();
$numReplacements = $result->count();

Use ReplaceResult::for() to perform a regex replacement and receive a result object containing both the transformed string (or array) and the number of replacements made.

This method supports both static string replacements and dynamic replacements using a callable. If the replacement is a callable, the callback receives a MatchResult object instead of a raw matches array, allowing for more expressive replacement logic.

If the replacement fails, it throws a Spatie\Regex\Exceptions\RegexFailed exception.

use Spatie\Regex\ReplaceResult;

$result = ReplaceResult::for(
    '/foo/i',           // pattern
    'bar',               // replacement
    'foo bar foo',       // subject
    -1                   // limit (-1 for all)
);

echo $result->result(); // "bar bar bar"
echo $result->count(); // 2