[RFC] [Discussion] PREG_THROW_ON_ERROR

Hi all,

The exception name is settled from the pre-RFC as \PregException
(thanks Tim) and the flag as PREG_THROW_ON_ERROR.

From the RFC:

The flag covers both classes of PCRE failure.

have you considered throwing different Exception types for the two failure types? (e.g. PregExecutionException and PregCompilationException)

You could have both be child classes of PregException, but in actual fact, the second should probably be a child of LogicException, while the former really is a RuntimeException...

Hi,

We actually have an agreed policy for this: https://github.com/php/policies/blob/main/coding-standards-and-naming.rst#throwables

According to that, there has to be a single base extension, which extends directly from \Exception.

Having more specific extensions is definitely encouraged, but these must all extend the extension's base exception (or each other), not any of the SPL classes like RuntimeException.

If it was a new extension the base exception name would be \Pcre\PcreException but there's flexibility when adding to existing extensions.

Thanks for bringing up this point,

Rowan Tommins
[IMSoP]

On Thu, Jul 30, 2026 at 3:22 AM B.J.Scharp
php.list.internals@bitwise-operators.com wrote:

Hi all,

The exception name is settled from the pre-RFC as \PregException
(thanks Tim) and the flag as PREG_THROW_ON_ERROR.

From the RFC:

The flag covers both classes of PCRE failure.

have you considered throwing different Exception types for the two
failure types? (e.g. PregExecutionException and PregCompilationException)

You could have both be child classes of PregException, but in actual
fact, the second should probably be a child of LogicException, while the
former really is a RuntimeException...

Regards,
Bernard

Hi Bernard,

Thanks for bringing this up.

As Rowan pointed out, the throwables policy settles half of it:
additional exceptions must extend the extension's base or each other,
not the SPL classes.
So the LogicException / RuntimeException parents are out regardless.

That leaves one PregException versus two under it (like your
suggested PregCompilationException / PregExecutionException),
which is a judgment call.
My starting point for the whole flag is that it only changes how an
error is delivered and nothing more.
That is the code and the message are exactly what preg_last_error()
and preg_last_error_msg() already give you.
A single exception sits most naturally on top of that.

There's a concrete nudge the same way....A compile failure only
carries the generic
PREG_INTERNAL_ERROR / "Internal error" through the error functions.
The real detail ("Compilation failed: ... at offset N") is in a
warning, not preg_last_error_msg().
So a PregCompilationException would carry "Internal error" and
little else until that detail is surfaced properly, which I've left as
future scope.

The upside of two types is letting people catch the two failure modes
separately.
I'm not sure how often that's needed in practice (given that
pre_last_error() already does not differentiate between them), but I
don't object if people feel
it's the better design. For now I'd still favor the single
PregException, with the door open.

Thanks,
Osama

On Thu, Jul 30, 2026 at 3:22 AM B.J.Scharp <
php.list.internals@bitwise-operators.com> wrote:

Hi all,

The exception name is settled from the pre-RFC as \PregException
(thanks Tim) and the flag as PREG_THROW_ON_ERROR.

From the RFC:

The flag covers both classes of PCRE failure.

have you considered throwing different Exception types for the two
failure types? (e.g. PregExecutionException and PregCompilationException)

You could have both be child classes of PregException, but in actual
fact, the second should probably be a child of LogicException, while the
former really is a RuntimeException...

Regards,
Bernard

Hi Bernard,

Sorry, my last message got misformatted, so I am sending it again.

Thanks again for bringing this up.

As Rowan pointed out, the throwables policy settles half of it: additional
exceptions must extend the extension's base or each other, not the SPL
classes.
So the LogicException / RuntimeException parents are out regardless.

That leaves one PregException versus two under it (like your suggested
PregCompilationException / PregExecutionException), which is a judgment
call.
My starting point for the whole flag is that it only changes how an error
is delivered and nothing more.
That is the code and the message are exactly what preg_last_error() and
preg_last_error_msg() already give you.
A single exception sits most naturally on top of that.

There's a concrete nudge the same way....A compile failure only carries the
generic PREG_INTERNAL_ERROR / "Internal error" through the error
functions.
The real detail ("Compilation failed: ... at offset N") is in a warning,
not preg_last_error_msg().
So a PregCompilationException would carry "Internal error" and little
else until that detail is surfaced properly, which I've left as future
scope.

The upside of two types is letting people catch the two failure modes
separately.
I'm not sure how often that's needed in practice (given that
pre_last_error() already does not differentiate between them), but I
don't object if people feel
it's the better design.
For now I'd still favor the single PregException, with the door open.

Thanks,
Osama

On Thu, Jul 30, 2026 at 6:09 PM Christian Schneider
cschneid@cschneid.com wrote:

Am 28.07.2026 um 02:56 schrieb Osama Aldemeery aldemeery@gmail.com:

The flag only changes how an error is delivered. A call does exactly the same thing with it or without it, byte for byte.
The only difference is that at the end, any error the call would have recorded is additionally thrown, carrying the same code and
message preg_last_error()/preg_last_error_msg() would report.

Reading the RFC and specifically the line

// The detailed "Compilation failed: ..." warning is still emitted, as always.

I assume compilation (and other?) failures will then trigger BOTH the E_WARNING and an Exception?

This sounds weird to me, do we have a precedent for this behavior?
I would have expected the Exception to replace the E_WARNING.

Regards,

• Chris

Hi Chris,

Good question, and you're reading it right: under the flag, a compile
failure emits both the E_WARNING and the exception.
One clarification though...That doubling only happens for compile
errors, which warn today.
Execution errors on the other hand (e.g. bad UTF-8, backtrack limit,
and so on) don't emit a warning at all, so those just throw.

On precedent, as far as I know there isn't a precedent for somethig like this.
But the reason it's currently warning-plus-exception rather than
exception-instead-of-warning is because the useful detail only lives
in the warning.
A compile failure sets the generic PREG_INTERNAL_ERROR / "Internal error" in the error functions, while the actual "Compilation failed: ... at offset N" text is only in the warning.
So if the exception replaced the warning today, you'd get an exception
saying "Internal error" and nothing about where or why.
Keeping the warning is what preserves that detail for now.

It's worth mentioning though that I do think
exception-instead-of-warning is the cleaner end state.
But it becomes the right move once the exception can carry that detail
itself, and that requires changing the message preg_last_message()
reports, which is the richer
compile-error reporting I've put under future scope.
Until then, dropping the warning would make the flag strictly worse
for debugging a bad pattern.

Happy to hear if you or others see it differently.

Thanks,
Osama