[2.x/3.x] Add matchNotNull and other *NotNull implementations

[Seldaek]

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

[naderman]

@glaubinix probably something you want to take a look at too.

[stof]

should have a int parameter type

[Seldaek]

Ah yes, looks like I forgot the result classes when working on the initial 2.0 changes. Will fix this.

[johnstevenson]

is the NotNull name clear/confusing?

While it seems clear in isolation, in practice it starts getting a bit nightmarish (to me, anyway).

For example, when reading isMatchAllWithOffsetsNotNull and I start losing the will to live after WithOffsets. How about appending Strict to these function names instead.

Now isMatchAllWithOffsetsStrict immediately appears to my brain as the isMatchAllWithOffsets function with stricter requirements.

[Seldaek]

I start losing the will to live after WithOffsets

😆 hence why I asked.

Strict sounds ok too. But to be honest I think we also could omit a few, like the WithOffsets ones, because they are less commonly needed and so it's not that bad if you have to check for nulls sometimes. But the isMatch and other common ones trigger 150 errors in the Composer codebase alone..

[johnstevenson]

I think we also could omit a few, like the WithOffsets ones

Yes, that seems reasonable. It would also make the NotNull suffixes not quite so mentally draining. However, I'm still not sure because isMatchNotNull and matchNotNull return truth(y) values and it doesn't seem immediately obvious that the NotNull is refering to a missing sub-pattern. Your WithoutNull suggestion is closer (but only if you know what is going on).

Perhaps isMatchStrictGroups would be better, or perhaps I'm over-thinking this!

[Seldaek]

Yeah I think I like StrictGroups, it's descriptive at least. For sure it'll confuse at first but that's probably the case no matter the name here given it's kind of a small distinction.