Pre-RFC: adding a Regex\CompiledRegex class for compiling regular expressions

This class could lay the foundation on which to build a new nice OO API

Nice. I am in favor of improving the API, instead of slapping more flags onto the existing one.

the pattern must be a UTF-8 pattern

Does this also apply to the subject? I recently had a reason to remove the u modifier from a regex: if the input is not valid UTF8, preg_match silently fails without a match. I think I was scraping web pages and discovered that some webpages don't contain valid UTF8, and that made it impossible to use preg_match with UTF8 on it.

returning a bool type

Would it make more sense to return a Match object, with captured groups?

The proposed API would result in calls like this:
new CompiledRegex(".*", false, false, false, true, true, true, false, true)
where it is hard to determine what all the true/false parameters mean. Would it be better to pass enums instead? Or is this solved by editor hints nowadays?

Regards,

Sjoerd Langkemper

Hello internals,

I spent the day prototyping an alternative to the PREG_THROW_ON_ERROR RFC as I'm not fully a fan of the approach.
Hi Gina,

Thank you for sharing this idea. As this would get rid of the ugly
delimiters, which means that I can finally copy-paste regexes from the
Regex app I use on a regular basis without having to consider slashes,
pipes or anything what comes to mind.

I initially thought of something like this:
public function __construct(string $pattern, int $modifiers = 0) {}

with all the different PCRE2_* modifiers exposed as class constants but it felt clunky and seems hard to pre-validate the flag combinations.

Agreed, but having a constructor that takes 9 parameters doesn't feel
great as well IMHO. To the eye of a developer, who usually doesn't fully
understand PCRE2 most of these parameters will be unfamiliar to them. If
we do add these to the constructor, could we at least try to match the
PRCE constants? E.g greedy would then become ungreedy (PCRE_UNGREEDY).

For the prototype I've only added support to use this new class to the preg_split() and preg_grep() functions as they were easy to tweak.

Is it by design that this class does not have a __toString() method.
And would you consider adding it? It would potentially allow the stubs
for the exiting functions to stay unchanged. This would be similar to
what the Uri API is doing, however it would require some sort delimiter
generation I suppose.

And if we are going that direction, how about we add a ::fromString(),
to make it easier to migrate to this new API? And make use of it's
Validation ability.

--
Regards,

Jordi Kroon

to add a new Regex\CompiledRegex class that takes a pattern, and some boolean modifiers, to compile a regular expression

Very nice. Don't like the name though. From my perspective as a user, I don't care if the regexp is compiled or not. I don't fully understand what compiled means in this context. But I know it's a regular expression into a value object doing some magic to ensure it is valid, same as all my user-space value objects.

Please consider something like:
Regexp\Expression
Regexp\Pattern

Greetings, Casper

I've currently landed on the following concept design:

namespace Regex {
	class CompilationError extends Exception {}

	/**
	 * @strict-properties
	 * @not-serializable
	 */
	final class CompiledRegex {
		public function __construct(
			string $pattern,
			bool $caseSensitive = true,
			bool $greedy = true,
			bool $anchor = false,
			bool $multiLine = false,
			bool $dotMatchesNewLine = false,
			bool $ignoreWhitespace = false,
			bool $captureOnlyNamedGroups = false,
			bool $allowDuplicateSubPatternNames = false,
		) {}
	}
}

Hi!

Great idea!

I've got some stupid questions though:

• Why final? Let me add methods while there's nothing in the core.
• Why @not-serializable? Serialization would seem as straightforward
  as for a plain DTO.
• Why not readonly public for all params? Inspecting the setup would
  be useful to build onto this in userland.

Regarding points brought up by otters

• +1 for the Regex name. And in that case Pcre\Regex might be nicer
  to avoid duplication and mixups.
• I would also need fromString or similar, but no problem to add it
  myself for now, as long as it's not fainal.
• I don't buy the objections about the number of the args. These days
  there's no problem to write new Regex($pattern, multiline: true).
  Fluent builders, enums, constants — those are just workarounds in the
  absence of such syntax.

BR,
Juris

Hi Gina,

Hello internals,

I spent the day prototyping an alternative to the PREG_THROW_ON_ERROR RFC as I'm not fully a fan of the approach.
It can be found as the following PR: https://github.com/php/php-src/pull/23868

The basic idea is to add a new Regex\CompiledRegex class that takes a pattern, and some boolean modifiers, to compile a regular expression before passing it to the preg_* functions.

I really like the idea, but I am not quite sure it fully replaces the
PREG_THROW_ON_ERROR flag.

Compilation errors are only half of the error story...the other half
happens at match time, on patterns that compiled just fine.

Consider this:

$r = preg_match('/(a+)+$/', str_repeat('a', 20) . '!');

var_dump($r); // bool(false)
var_dump(preg_last_error_msg()); // string(25) "Backtrack limit exhausted"

As far as I understand, this class of errors
(PREG_BACKTRACK_LIMIT_ERROR, PREG_RECURSION_LIMIT_ERROR,
PREG_JIT_STACKLIMIT_ERROR, ...etc) depends on the subject, not the
pattern, so no amount of validation at construction time can catch it.

I think the proposal, though, removes a good part of the motivation
for PREG_THROW_ON_ERROR, so now whether PHP should have a regex
object that fails on compilation errors only and works with preg_*
functions, or have a flag that guarantees the next line after a
preg_* call only executes if the call left no error behind (or
both?), is up to you and the people on this list to decide. I
personally see the two as complementary rather than alternatives.

That said, I really like and am in support of having a class that
represents a compiled regex (for what my entirely non-voting opinion
is worth), whether it replaces the flag or not.

Best,
Osama

Hi

  public function __construct(
  	string $pattern,
  	bool $caseSensitive = true,
  	bool $greedy = true,
  	bool $anchor = false,
  	bool $multiLine = false,
  	bool $dotMatchesNewLine = false,
  	bool $ignoreWhitespace = false,
  	bool $captureOnlyNamedGroups = false,
  	bool $allowDuplicateSubPatternNames = false,
  ) {}

Similar to what the others mentioned, I'm not happy with the
constructor, for two reasons:

1. I feel that named constructors work much better if there are multiple
   equally valid ways of constructing a value object, which likely is the
   case here with “undelimited pattern” and “delimited pattern including
   modifiers” and possible future additions. Some of the flags could
   potentially even be built into the constructors name (switching between
   Unicode / Bytestring support).

2. The order of the flags is pretty much arbitrary, making
   discoverability hard because IDEs typically suggest parameters in the
   order they appear in.

We likely want the most common flags first, which then would become ugly
if later adding additional flags which are expected to be commonly used.

Since the parameters are intended to be used as “named parameter only”,
we should likely first have some mechanism to prevent parameters from
being used positionally, similarly to what I think Python supports.

Best regards
Tim Düsterhus

namespace Regex {
        class CompilationError extends Exception {}

        /**
         * @strict-properties
         * @not-serializable
         */
        final class CompiledRegex {
                public function __construct(
                        string $pattern,
                        bool $caseSensitive = true,
                        bool $greedy = true,
                        bool $anchor = false,
                        bool $multiLine = false,
                        bool $dotMatchesNewLine = false,
                        bool $ignoreWhitespace = false,
                        bool $captureOnlyNamedGroups = false,
                        bool $allowDuplicateSubPatternNames = false,
                ) {}
        }
}

The $pattern parameter removes the need to use a delimiter, and a potential call to preg_quote(), and modifiers that would be specified after the ending delimiter are boolean flags.
I've made a few opinionated choices in the prototype in the sense that the pattern must be a UTF-8 pattern, and the PCRE2_DOLLAR_ENDONLY compilation option is always on (i.e. the 'D' modifier) as those seem to be sensible starting conditions.

I initially thought of something like this:
public function __construct(string $pattern, int $modifiers = 0) {}

with all the different PCRE2_* modifiers exposed as class constants but it felt clunky and seems hard to pre-validate the flag combinations.

Hi Gina,

Do you plan to add a CompiledRegex::fromRegexp(string $pattern)
method that can accept a delimited regex with flags? It can
significantly improve the migration path from existing code bases.
Libraries that build regexes from a user input (like a router
accepting a route with a regex pattern, for example) can easily pass a
user-provided regex and validate it immediately.

Echoing what others mentioned, I think the constructor is not that
intuitive without IDE parameter hints. This is still PCRE library's
domain, so when we update the PCRE2 library, we will have to change
the class signature to add new flags. If PCRE were to remove any of
the flags, we would essentially have a no-op that parameter. None of
which is ideal. It is also possible to configure the build with a
different PCRE2 library version, so the signature depends not only on
the PHP version but also on the PCRE version.

I'm definitely in favor of having compiled valid Regexps as class
objects, but I wish it would be a thin wrapper (similar to classes
that replace legacy resource objects), with a lot of logic and
validation handled at PCRE layer.

Thank you,
Ayesh.