Hi all,
Following the earlier pre-RFC discussion (
https://news-web.php.net/php.internals/131783), I've written this up as a
proper RFC: https://wiki.php.net/rfc/preg_throw_on_error
Short version:
a PREG_THROW_ON_ERROR flag you pass to any preg_*() call, so a PCRE
error throws a \PregException you can catch
instead of a warning plus a false / null you have to notice and then
chase through preg_last_error().
Same thing JSON_THROW_ON_ERROR and FILTER_THROW_ON_FAILURE already do
for their functions.
It's opt-in, so nothing changes without the flag.
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.
For array arguments that means the flag mirrors preg_last_error()...it
throws whatever error the same call leaves there,
which for preg_replace() over an array is the last-processed entry, not
the first. (In the pre-RFC I'd floated throwing on the first failing
element instead).
Whether the preg_*() functions should stop at the first failing entry is
a separate question about those functions, one that applies with or without
the flag, so it's out of scope here.
The exception name is settled from the pre-RFC as \PregException (thanks
Tim) and the flag as PREG_THROW_ON_ERROR.
Target is the next feature release after 8.6 since 8.6's beta1 is too close
for this to conclude discussion and a vote in time.
I also saw Larry's note asking to hold new business that isn't targeting
8.6 until the freeze rush is over.
This won't catch 8.6, so I'm not asking for any priority while the freeze
is on. But the pre-RFC discussion was already open before
Larry's note, so I'd rather keep it ticking over quietly than restart it in
September.
If someone prefers I park it until then, please say so and I will.
Implementation and tests: https://github.com/php/php-src/pull/22797
Thanks,
Osama
Hi all,
The exception name is settled from the pre-RFC as
\PregException
(thanks Tim) and the flag asPREG_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 all,
The exception name is settled from the pre-RFC as
\PregException
(thanks Tim) and the flag asPREG_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 asPREG_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 asPREG_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
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
messagepreg_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
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
messagepreg_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_WARNINGand 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
Hi all,
Following the earlier pre-RFC discussion (https://news-web.php.net/php.internals/131783), I've written this up as a proper RFC: https://wiki.php.net/rfc/preg_throw_on_error
Short version:
a
PREG_THROW_ON_ERRORflag you pass to anypreg_*()call, so a PCRE error throws a\PregExceptionyou can catch
instead of a warning plus afalse/nullyou have to notice and then chase throughpreg_last_error().
Same thingJSON_THROW_ON_ERRORandFILTER_THROW_ON_FAILUREalready do for their functions.
It's opt-in, so nothing changes without the flag.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
messagepreg_last_error()/preg_last_error_msg()would report.For array arguments that means the flag mirrors
preg_last_error()...it throws whatever error the same call leaves there,
which forpreg_replace()over an array is the last-processed entry, not the first. (In the pre-RFC I'd floated throwing on the first failing element instead).
Whether thepreg_*()functions should stop at the first failing entry is a separate question about those functions, one that applies with or without the flag, so it's out of scope here.The exception name is settled from the pre-RFC as
\PregException(thanks Tim) and the flag asPREG_THROW_ON_ERROR.Target is the next feature release after 8.6 since 8.6's beta1 is too close for this to conclude discussion and a vote in time.
I also saw Larry's note asking to hold new business that isn't targeting 8.6 until the freeze rush is over.
This won't catch 8.6, so I'm not asking for any priority while the freeze is on. But the pre-RFC discussion was already open before
Larry's note, so I'd rather keep it ticking over quietly than restart it in September.
If someone prefers I park it until then, please say so and I will.Implementation and tests: https://github.com/php/php-src/pull/22797
Thanks,
Osama
Hi all,
This has gone quiet, which I'm taking as the freeze crunch and people
being busy, not as everyone being fine with it as-is.
And it isn't targeting 8.6 anyway, so there's no rush on my side.
So I'll park it and bring it back early September just like Larry
asked, once the release dust has settled, to give anyone who hasn't
weighed in a clear window to do so.
The points raised so far (the exception hierarchy, the warning
behavior) are addressed in the RFC, so if it's still quiet after I
resurface it, the natural next step is to move toward a vote.
I'd rather that happen once everyone's had a fair chance than while
half the list is heads-down on the release.
If there's something you'd want settled before a vote, now or early
September both work for me.
I'll ping the thread again then.
Thanks,
Osama
Hi all,
Following the earlier pre-RFC discussion (https://news-web.php.net/php.internals/131783), I've written this up as a proper RFC: https://wiki.php.net/rfc/preg_throw_on_error
Short version:
a
PREG_THROW_ON_ERRORflag you pass to anypreg_*()call, so a PCRE error throws a\PregExceptionyou can catch
instead of a warning plus afalse/nullyou have to notice and then chase throughpreg_last_error().
Same thingJSON_THROW_ON_ERRORandFILTER_THROW_ON_FAILUREalready do for their functions.
It's opt-in, so nothing changes without the flag.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
messagepreg_last_error()/preg_last_error_msg()would report.For array arguments that means the flag mirrors
preg_last_error()...it throws whatever error the same call leaves there,
which forpreg_replace()over an array is the last-processed entry, not the first. (In the pre-RFC I'd floated throwing on the first failing element instead).
Whether thepreg_*()functions should stop at the first failing entry is a separate question about those functions, one that applies with or without the flag, so it's out of scope here.The exception name is settled from the pre-RFC as
\PregException(thanks Tim) and the flag asPREG_THROW_ON_ERROR.Target is the next feature release after 8.6 since 8.6's beta1 is too close for this to conclude discussion and a vote in time.
I also saw Larry's note asking to hold new business that isn't targeting 8.6 until the freeze rush is over.
This won't catch 8.6, so I'm not asking for any priority while the freeze is on. But the pre-RFC discussion was already open before
Larry's note, so I'd rather keep it ticking over quietly than restart it in September.
If someone prefers I park it until then, please say so and I will.Implementation and tests: https://github.com/php/php-src/pull/22797
Thanks,
Osama
Hi all,
Picking this back up...Quick recap first, since it's been quiet for a
couple of weeks.
PREG_THROW_ON_ERROR is an opt-in flag you pass to any preg_*() call.
With it, a PCRE error throws a \PregException you can catch, instead
of the current warning plus a false or null you have to notice and
then chase through preg_last_error().
Same thing JSON_THROW_ON_ERROR and FILTER_THROW_ON_FAILURE already
do for their functions.
Where things landed:
- Nothing changes without the flag, byte for byte. All it changes is
how an error is delivered. At the end of a call, any error it would
have recorded is thrown as well, carrying the same code and message
preg_last_error()/preg_last_error_msg()would report. - The exception is
\PregExceptionand the flag is
PREG_THROW_ON_ERROR, both settled back in the pre-RFC (thanks Tim). - For array arguments the flag mirrors
preg_last_error(). It throws
whatever error the call leaves there, which forpreg_replace()over
an array is the last-processed entry, not the first. Whether the
functions should stop at the first failing entry is a separate
question about those functions, so it's out of scope here.
The two points raised during discussion, the exception hierarchy and
the warning behavior, are addressed in the RFC as it stands.
RFC: https://wiki.php.net/rfc/preg_throw_on_error
PR: https://github.com/php/php-src/pull/22797
So consider this my intent to vote...
Unless something new comes up, I'll open the vote in about two days.
If there's anything you'd want settled first, please bring it up now.
Thanks,
Osama