[RFC] [VOTE] PREG_THROW_ON_ERROR

Hi

Now what I would suggest instead of breaking that guarantee, is to pull
enriching the anemic preg_last_error_msg() error message forward into
this RFC instead of leaving it for later, store the real reason in the
error state, and the exception inherits it through the very same channel,
with the guarantee intact.

That would also work for me. But the E_WARNING should remain when the
PREG_THROW_ON_ERROR flag is not set, because some users might rely on
the warning being emitted to turn it into an Exception themselves by
means of an error handler.

What is important to me is that the new flag cleanly results in an
Exception and only an Exception for all possible errors, because this is
what users will expect from it.

On your second point, if this is a violation of a policy, then there isn't
much to argue. I will just retract the vote and fix that.

But I think I got confused here, and I would appreciate you explaining how
that violates the policy.

To make sure we're on the same ground, this is what I understood from your
statement about wrapping exceptions thrown in user callbacks:

preg_replace_callback(
     $pattern,
     fn () => throw new CustomException(), // <- You want this wrapped in
PregException?
     $subject,
     flags: PREG_THROW_ON_ERROR,
);

Yes. I expect a PregException where $e->getPrevious() instanceof
CustomException().

If I got it right (and I suspect I did), then how does that violate the
policy?
A user callback isn't external functionality, is it? Because as far as I
understand, external functionality is something the extension itself
depends on as part of its own implementation.

Arguably this specific case is a bit debatable, but as the author of the
throwable policy RFC, I believe that it is at least violated in spirit.

The goal of the throwable policy generally, and also with regard to that
specific paragraph is to allow reliably handling groups of errors
without needing to wrap every individual statement into its own
try-catch block. Consider this:

 try {
     $contents = get_from_api('http://example.com');

     // sanitize credit card numbers
     $contents = preg_replace_callback(
         '/[0-9]{4}-[0-9]{4}-[0-9]{4}-[0-9]{4}/',
         function ($matches) {
             return mask_credit_card($matches[0]);
         },
         $contents,
         falgs: PREG_THROW_ON_ERROR,
     );

     echo $contents;
 } catch (PregException $e) {
     echo "Sanitization failed\n";
 } catch (HttpException $e) {
     echo "Download failed\n";
 }

I am catching the PregException to handle failures during the credit
card sanitization step. If mask_credit_card() throws its own exception
that is not wrapped, my catch blocks are insufficient and I would
instead need to write it something like this:

 try {
     $contents = get_from_api('http://example.com');
 } catch (HttpException $e) {
     echo "Download failed\n";
     return;
 }
 try {
     // sanitize credit card numbers
     $contents = preg_replace_callback(
         '/[0-9]{4}-[0-9]{4}-[0-9]{4}-[0-9]{4}/',
         function ($matches) {
             return mask_credit_card($matches[0]);
         },
         $contents,
         falgs: PREG_THROW_ON_ERROR,
     );
 } catch (Exception $e) {
     echo "Sanitization failed\n";
     return;
 }
 echo $contents;

To reliably handle just the exceptions that happen during sanitization
and nothing else. This is a lot of extra boilerplate code and noise.

Now if I am still interested in the inner exception for the callback
failure, something like this would work:

 } catch (PregException $e) {
     if ($e->getCode() === PregException::CALLBACK_FAILURE) {
         echo "Sanitization callback failed: ",

$e->getPrevious()->getMessage();
} else {
echo "Sanitization failed\n";
}
}

Because if the error code is callback failure, I know that there is a
previous Exception. So I don't lose any functionality / information.

I am also unaware of any functions that behave like that (wraps exceptions
thrown in user callbacks in its own exception).

There are a few cases where the CSPRNG (which throws RandomException on
failure) is used internally and the exception on CSPRNG failure is
wrapped. However much of the standard library predates the throwable
policy (which was accepted in May 2025;
https://wiki.php.net/rfc/extension_exceptions), that's why it doesn't
follow it.

In fact, the opposite is the case for one of the precedents this RFC
follows (json_encode() with JSON_THROW_ON_ERROR - although it doesn't
accept a user callback): https://3v4l.org/CtHYH#v8.5.10

Yes, that flag and JsonSerializable itself is much older than the policy.

Best regards
Tim Düsterhus

Hi Tim,

Thank you for the elaboration.

The first thing that came to my mind reading your example is that
without wrapping, an extra catch block would be enough:

try {
    $contents = get_from_api('http://example.com');

    $contents = preg_replace_callback(
        '/[0-9]{4}-[0-9]{4}-[0-9]{4}-[0-9]{4}/',
        function ($matches) {
            return mask_credit_card($matches[0]); // throws MaskException
        },
        $contents,
        flags: PREG_THROW_ON_ERROR,
    );

    echo $contents;
} catch (MaskException $e) {
    echo "Sanitization failed\n";
} catch (PregException $e) {
    echo "Regex failed\n";
} catch (HttpException $e) {
    echo "Download failed\n";
}

The caveat of course is that this only works when you know the
exception a callback can throw...which you don't always control.

But since you've made clear this is a violation of the throwable
policy, I've retracted the vote until we get it resolved.

Following the idea of wrapping the callback's exception, I see two problems...
One is a footgun I'd want explicitly addressed.
The other, I'm afraid, forces an exception hierarchy in place of a
single PregException.

First...wrapping couples the exception you catch to the flag.
Without it, preg_replace_callback() throws whatever the callback throws.
With it, the same call always throws a PregException.
So the flag silently changes which exception a caller has to handle,
and the two have to move together:

try {
    preg_replace_callback(
        '/[0-9]{4}-[0-9]{4}-[0-9]{4}-[0-9]{4}/',
        function ($matches) {
            return mask_credit_card($matches[0]); // throws MaskException
        },
        $contents,
    );
} catch (MaskException $e) {
    // becomes dead the moment the flag is added, and comes back the
moment it's removed
}

Second...wrapping a callback's exception in a PregException produces
a PregException that maps to no preg error.
You can be holding a PregException while preg_last_error() and
preg_last_error_msg() report no error at all. That is an exception
whose type says a regex error happened when, by preg's own state, none
did.
This is separate from the $e->getMessage() === preg_last_error_msg()``
guarantee I raised before. Even setting that aside, it's incoherent on
its own terms, because the flag is PREG_THROW_ON_ERROR and
preg_last_error() is what an error is.

So keeping that honest means a bare PregException can no longer
stand for two different things at once.
So it has to split into a PregPcreException (or a better name)
carrying the real preg error and mirroring preg_last_error()...and
PregCallbackException wrapping the callback's exception. And then to
satisfy the single catch both would need to extend a shared
PregException parent.
That's a whole hierarchy to carry a case an extra catch would have handled.

So the cost of wrapping comes out as a silent footgun plus a
three-class hierarchy, for what one more catch could do.
Both look intrinsic to wrapping, though. The footgun is the flip side
of the single catch you want, and the hierarchy is what keeps that
catch honest, so neither can really be designed away.

That is if I didn't miss anything along the way...

So my question now is: is that price worth paying over the extra
catch...or is the extra catch acceptable after all?
That's where I'd hope your "Arguably this specific case is a bit
debatable" leaves some room.

In any case...I'll be working on how the preg_last_error_msg()
change impacts the RFC, and meanwhile looking for opinions on the
wrapping points I've raised above.

Regards,
Osama

Arguably this specific case is a bit debatable, but as the author of the
throwable policy RFC, I believe that it is at least violated in spirit.
The goal of the throwable policy generally, and also with regard to that
specific paragraph is to allow reliably handling groups of errors
without needing to wrap every individual statement into its own
try-catch block.

Obviously you wrote the policy and so are best placed to interpret it
(and I am not a core developer / person with voting rights); however I
agree with the angle Osama is coming from here - I wouldn't say this
is an error that is (always) part of the same group. There wasn't any
error in the call to preg_replace_callback itself (or any of its
functionality) - the error was in a way during the processing of the
result of the function. Taking your example - what if instead of
CustomException you had InvalidLengthException,
IncorrectFormatException, NotKnownBIN, etc. Instead of being able
to catch say InvalidLengthException & IncorrectFormatException to
return a validation error asking the user to check their input;
NotKnownBIN to return that the user can not use that particular card
with you, and PregException to note a system failure occurred then
you have to catch PregException (or Exception) and then use
switch / match on $previous.

If I have understood the other example correctly, this contradicts
quite significantly with the CSPRNG throwing an Exception that
RandomException contains - as the failure is a core issue within the
function call itself as opposed to logic that occurs in userland.

If anything, I would argue that under the policy this should go the
other way and become PregError:

The Error hierarchy MUST NOT be used for errors that are expected to be thrown (and caught) during normal operation of a PHP program.
In terms of the possible errors that could occur, I would expect at
least PREG_INTERNAL_ERROR, PREG_BAD_UTF8_ERROR &
PREG_JIT_STACKLIMIT_ERROR to be code errors that require a developer
to need to correct their code (as my understanding of these would be
that the pattern is invalid, or not quoted correctly, etc. Although
PREG_BACKTRACK_LIMIT_ERROR & PREG_RECURSION_LIMIT_ERROR are more
likely to occur based on user input, then the limit for both is
controlled by an ini setting - so again, this likely isn't something I
would say is expected to be thrown and caught during normal operation
of a PHP program. The final error (PREG_BAD_UTF8_OFFSET_ERROR) I
think would still likely need a code change to fix it occurring -
although I have only done a quick Google to see when it may occur.

I do admit that overall - my only real experience with the preg_*
functions erroring is where the pattern itself is not valid in some
way; so there may be more common use-cases that fit the exception path

• but hopefully explaining why my viewpoint is to treat it as an
  Error hierarchy Throwable as opposed to Exception covers why not
  wrapping any throws from the userland callbacks makes sense.

Hi

Now what I would suggest instead of breaking that guarantee, is to pull
enriching the anemic preg_last_error_msg() error message forward into
this RFC instead of leaving it for later, store the real reason in the
error state, and the exception inherits it through the very same channel,
with the guarantee intact.

That would also work for me. But the E_WARNING should remain when the
PREG_THROW_ON_ERROR flag is not set, because some users might rely on
the warning being emitted to turn it into an Exception themselves by
means of an error handler.

What is important to me is that the new flag cleanly results in an
Exception and only an Exception for all possible errors, because this is
what users will expect from it.

On your second point, if this is a violation of a policy, then there isn't
much to argue. I will just retract the vote and fix that.

But I think I got confused here, and I would appreciate you explaining how
that violates the policy.

To make sure we're on the same ground, this is what I understood from your
statement about wrapping exceptions thrown in user callbacks:

preg_replace_callback(
     $pattern,
     fn () => throw new CustomException(), // <- You want this wrapped in
PregException?
     $subject,
     flags: PREG_THROW_ON_ERROR,
);

Yes. I expect a PregException where $e->getPrevious() instanceof
CustomException().

If I got it right (and I suspect I did), then how does that violate the
policy?
A user callback isn't external functionality, is it? Because as far as I
understand, external functionality is something the extension itself
depends on as part of its own implementation.

Arguably this specific case is a bit debatable, but as the author of the
throwable policy RFC, I believe that it is at least violated in spirit.

The goal of the throwable policy generally, and also with regard to that
specific paragraph is to allow reliably handling groups of errors
without needing to wrap every individual statement into its own
try-catch block. Consider this:

 try {
     $contents = get_from_api('http://example.com');

     // sanitize credit card numbers
     $contents = preg_replace_callback(
         '/[0-9]{4}-[0-9]{4}-[0-9]{4}-[0-9]{4}/',
         function ($matches) {
             return mask_credit_card($matches[0]);
         },
         $contents,
         falgs: PREG_THROW_ON_ERROR,
     );

     echo $contents;
 } catch (PregException $e) {
     echo "Sanitization failed\n";
 } catch (HttpException $e) {
     echo "Download failed\n";
 }

I am catching the PregException to handle failures during the credit
card sanitization step. If mask_credit_card() throws its own exception
that is not wrapped, my catch blocks are insufficient and I would
instead need to write it something like this:

 try {
     $contents = get_from_api('http://example.com');
 } catch (HttpException $e) {
     echo "Download failed\n";
     return;
 }
 try {
     // sanitize credit card numbers
     $contents = preg_replace_callback(
         '/[0-9]{4}-[0-9]{4}-[0-9]{4}-[0-9]{4}/',
         function ($matches) {
             return mask_credit_card($matches[0]);
         },
         $contents,
         falgs: PREG_THROW_ON_ERROR,
     );
 } catch (Exception $e) {
     echo "Sanitization failed\n";
     return;
 }
 echo $contents;

To reliably handle just the exceptions that happen during sanitization
and nothing else. This is a lot of extra boilerplate code and noise.

Now if I am still interested in the inner exception for the callback
failure, something like this would work:

 } catch (PregException $e) {
     if ($e->getCode() === PregException::CALLBACK_FAILURE) {
         echo "Sanitization callback failed: ",

$e->getPrevious()->getMessage();
} else {
echo "Sanitization failed\n";
}
}

Because if the error code is callback failure, I know that there is a
previous Exception. So I don't lose any functionality / information.

I am also unaware of any functions that behave like that (wraps exceptions
thrown in user callbacks in its own exception).

There are a few cases where the CSPRNG (which throws RandomException on
failure) is used internally and the exception on CSPRNG failure is
wrapped. However much of the standard library predates the throwable
policy (which was accepted in May 2025;
https://wiki.php.net/rfc/extension_exceptions), that's why it doesn't
follow it.

In fact, the opposite is the case for one of the precedents this RFC
follows (json_encode() with JSON_THROW_ON_ERROR - although it doesn't
accept a user callback): https://3v4l.org/CtHYH#v8.5.10

Yes, that flag and JsonSerializable itself is much older than the policy.

Best regards
Tim Düsterhus