I appreciate that you are already working on this, but since I was already testing various API ideas it seemed quicker to knock up a POC to show how this library could provide safe wrappers for the full range of preg_* function usage (plus its own API), rather than discussing it all. So no worries if you don't want this.

• Union types in the preg_* functions are supported (even though Composer may not use them itself)
• The $subject param from PcreException::fromFunction has been removed because it was not used
• ReplaceResult::result is now a string|string[]
• Regex::isMatch has been introduced as syntax sugar for Regex::match(...)->matched

Tests are needed for:

• Preg::filter
• Preg::grep
• Preg::replaceCallbackArray
• Preg::split

There is an inconsistency between the preg_ functions that emit warnings (in that Preg::filter is the only one to suppress them) because I don't know what is best to do.

Hi,

thank you for the package, this is what I was looking for (I do like that you are using "result" objects).

• Anyway I often need to match first group or - matchFirst
• Also sometimes I need to try multiple regexes on the subject - matchFirstOf

Checklist

• [X] PHP CS Fixer
• [X] Add tests
• [X] PHPStan
• [X] Explanation in commit messages (long message)
• [ ] Documentation

Are you OK with the changes?

Thank you,

FYI

PHPStan

There are 2 phpstan errors. Not sure how to fix it (I used PHP 8.1).

> phpstan analyse
Note: Using configuration file /Users/pion/Work/OpenSource/pcre/phpstan.neon.dist.
  0/33 [░░░░░░░░░░░░░░░░░░░░░░░░░░░░]   0% 33/33 [▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓] 100%

 ------ ---------------------------------------------------------------------- 
  Line   src/Preg.php                                                          
 ------ ---------------------------------------------------------------------- 
  78     Strict comparison using === between int<0, max> and null will always  
         evaluate to false.                                                    
  98     Strict comparison using === between int<0, max> and null will always  
         evaluate to false.                                                    
 ------ ---------------------------------------------------------------------- 


 [ERROR] Found 2 errors        

Linting

In contribution we are instructed to use PHP CS fixer. Maybe would be great to require as dev dependency and add config + composer script? (I personally use ECS package

This is going to be a very useful library. And because it's in the Composer family it will likely become huge and invoke all sorts of feaure requests.

In my view it primarily needs to be a drop-in replacement to make existing code safe. Using some Composer examples we can see how painless this could be:

<?php
    if (preg_match($pattern, $line)) { ... }
    if (Regex::match($pattern, $line, $unused)) { ... }

    if (preg_match_all('{'.self::$DEFINES.'"'.$keyRegex.'"\s*:\s*(?:(?&json))}x', $children, $matches)) { ... }
    if (Regex::matchAll('{'.self::$DEFINES.'"'.$keyRegex.'"\s*:\s*(?:(?&json))}x', $children, $matches)) { ... }

    $childrenClean = preg_replace('{,\s*'.preg_quote($bestMatch).'}i', '', $children, -1, $count);
    $childrenClean = Regex::replace('{,\s*'.preg_quote($bestMatch).'}i', '', $children, -1, $count);

We can cover everyone's needs with Regex::filter, Regex::grep, Regex::match, Regex::matchAll, Regex::replace, Regex::replaceCallback and Regex::replaceCallbackArray in not much code that wraps the native PHP functions and throws a nice PcreException on regex errors, without emitting any warnings. The only downside for users would be having to add the optional params if they are not being used.

The decorator methods that return result objects could be simply named by appending Ex:

<?php
$result = Regex::matchEx('{fo+}', $string);
if ($result->matched) { something($result->matches); }

What do you think? (I can PR any of this you like, if you don't have the time).

I'd be happy for a sanity check here before proceeding and adding the rest of them (matchWithOffsetsNotNull, matchAllNotNull, matchAllWithOffsetsNotNull, replaceCallbackNotNull, replaceCallbackArrayNotNull, isMatchNotNull, isMatchAllNotNull, isMatchWithOffsetsNotNull, isMatchAllWithOffsetsNotNull 😅 ).

The issue is that due to the improvements in PHPStan and https://github.com/composer/pcre/releases/tag/3.0.2 you now get errors everywhere because $match[1] for ex is string|null even tho in many cases the null will never happen. This is however dependent on the pattern and thus cannot really be asserted easily in the types.

So adding these NotNull variants for all functions outputting nullable matches solves this by letting you opt in to stricter non-nullable types, and if you messed up and your pattern does have null/unmatched-subpatterns you get an exception.

The main problems I see and where I'd love feedback are:

• is the NotNull name clear/confusing?
• is it polluting the interface too much? It adds lots of "duplicate" methods but they are technically different and kinda similar to the WithOffset ones we already have. This makes me think perhaps the name should be WithoutNull tho.

/cc @johnstevenson @naderman @stof

More syntax sugar, returning bool from preg_match and preg_match_all whilst allowing the use of all parameters. These methods make the Preg class a complete drop-in replacement for the native functions.

What do you think?

This is a workaround for the discrepancy between 7.2/7.3 and above versions (https://3v4l.org/eU2di) using something along the lines of https://3v4l.org/D1vN2

/cc @johnstevenson FYI because it's a fun one 🙈