[RFC] Stream Error Handling Improvements

Hi Bob,

Thanks for the feedback, the replies here also cover the feedback from
Jordi and Ignace.

Why have you chosen a big list of constants rather than enums?
I think we should push for enums where applicable, meaning enum
StreamErrorMode, enum StreamErrorStore, enum StreamError.

Ok I will change it. StreamErrorMode and StreamErrorStore should be
straightforward. The code one should be probably named StreamErrorCode (to
not interact with what Jordi proposed) and think it will need to be backed
as there should be a straightforward way how to compare it with exception
code. I might need to extend the gen stub as I'm not sure it allows macro
import for enum value like for constants or I will need to come up with
some mapping. I just don't wan to duplicate the numbers. I will figure
something out.

You define what a terminal error is, but does it correlate to specific
error codes? Like, is a given error code always terminal or not
terminal? Or can some error codes sometimes be terminal or not terminal
depending on context?
I've tried to look at the code, but I don't quite understand it, e.g.
php_plain_files_rename: When chown or chmod fail, the error is terminal.
When the copying fails (did you forget to adapt php_copy_file_ctx?),
that's non-terminal, though. Reading through the code, I have the
feeling that operations which do not call out to other operations, which
can error, are terminal. And all others are non-terminal. E.g. failing
to open a file is terminal. That the copying where the file opening is
part of, failed, is non-terminal.
And then additionally some operations, which don't prevent success are
also marked non-terminal - squeezing it into the boolean for the purpose
of not erroring.
Which makes some sense to me, but the description in the RFC is really
confusing here. And the meanings are muddied.

So currently the terminal / non terminal does not attach to code but it
could be done. The current logic is really just supposed to reflect what is
there already so the exception can be thrown in places where the function
would fail. So the errors after which the function fails are terminal and
the errors where the function still returns success are non terminal.

Thus, if I understand that correctly, there should be an unique mapping

from error code to terminal. If we were to go with enums, we could make
it trivially a property of the individual enum values instead.

I think making it property of enum make more sense. Then I can drop that
boolean property.

Should StreamException be attached the non-terminal errors which are
caused by the terminal errors? I.e. StreamException clearly is
STREAM_ERROR_CODE_PERMISSION_DENIED for example, but it happens during a
copy, so, should the information that a STREAM_ERROR_CODE_COPY_FAILED
was caused by that, also be present on the StreamException?

I think I get what you mean from the user point of view but I'm not sure
how could this be reasonably linked.

I could maybe check during stream error if there is EG(exception) it's a
StreamException and if so, I could the update it with this error (e.g. some
property that would hold those error can could be retrieved). I guess it
could be potentially extended for terminal errors as well so it could have
method like getAllErrors which would return all errors because sometimes
there can be more terminal errors and some of them might get lost (last one
will be added). However this would work just for exception so maybe more
generic solution is needed here (see below).

Are stream errors which happen as part of a fully wrapped functionality
marked as wrapper error as well? Like if the server sent an invalid TLS
response to a file_get_contents("https://...") operation, making the
whole operation fail? You obviously don't have access to the
intermediary internal stream resource there, where the stream error is
attached.

I actually thought about this yesterday that it's not ideal that some
errors might get lost in this way so I think it should go to wrapper errors
as well.

Is this what the logged errors section is about? Is that section talking
about "php_stream_display_wrapper_errors", which can concat some errors?
I see that this logic is mostly retained.

Yeah the logged errors is an existing mechanism for grouping errors to a
single one (concatenating message). The display is a bit messy because it
separated them by new line or <br/> (if html errors enabled) but I just
kept it to limit BC impact.

Do I understand the implementation correctly, that user error handlers
can be called multiple times for a same operation? E.g. when copying a
file, you'll get first a PERMISSION_DENIED then a COPY_FAILED? Should
these not be somehow merged? Especially with global user_error handlers,
these cannot be aware of the fact that the permission denied is part of
anything else - at least not until possibly a second user_error
invocation happens.

This is somehow related to the exception error grouping as it requires some
sort of linking between the errors.

I guess to make this work we would need some top level wrapping similar to
what logged errors do but instead of concatenating, it would group the
errors in a better way which could then be used in exception or handler.
This would, however, increase the complexity significantly as it is
possible to nest the stream calls (e.g. stream calls in notification
callback or in the new error handler) so there would probably need to be
some stack. Also I'm not sure about the API. Should we pass always array of
errors to the callback (which would mostly have just one element anyway or
somehow chain the StreamError object (something like previousError()) and
what message should be used in exception (e.g. last error and then helper
function to get all errors)?

I'm willing to look into this but would like to know if this is something
important for user space and what is the usual flow how could this be used
in frameworks and so on. In other words I would like to get more input to
make sure that this is really needed as it requires quite a bit of effort
to do.

Also, is the internal resource used for e.g. file_get_contents() leaked
into user error handlers? I'm not sure whether that's desirable. If
that's intended, that's fine too, I think.

Currently yes. I need to actually double check the consequences of that as
I didn't really think about internal resources.

Further suggestion on stream_get_errors() - why not return a proper
object instead of a loosely typed array? Proper typing, and creation is
actually faster. Also "docref" is so... antiquated? maybe just
"function" and have it contain the function name of the current operation.

Yeah I will go for it and introduce StreamError as Jordi suggested with
slight modification to use enum and dropping terminal and docref.

Does stream_get_errors() ever reset? Looking at the code it doesn't seem
so. It will just forever grow. E.g. fwrite() will report an error every
single time when the buffer is full and a write is attempted. If errors
aren't freed, that's just a memory leak (as long as the socket lives).
This is a serious flaw.

Lastly, stream_get_errors() is overkill in a lot of cases (especially
when using fread()/fwrite() on simple sockets). I just care about the
last error code (there's just going to be one anyway). I'd love having a
stream_get_last_error() returning just the code.

I guess this makes more sense but it kind of also implies the top level
wrapping as it should contain all errors in the call. Or alternatively it
could be just a ring with limited number of errors be behave in the same
way like openssl_error_string. I guess it depends if we go with that top
level wrapping.

Cheers,

Jakub

Hello,

I would like to introduce a new stream error handling RFC that is part of
my stream evolution work (PHP Foundation project funded by Sovereign Tech
Fund) :

https://wiki.php.net/rfc/stream_errors

Kind regards,

Jakub

The naming of "terminal" is a little confusing to me. Reading the name
with a bool made me think it was whether or not the CLI was being used,
which made little sense in the context of stream errors. After reading the
explanation "Terminal errors are those that prevent an operation from
completing (e.g., file not found, permission denied). Non-terminal errors
are warnings or notices that don't stop execution (e.g., buffer
truncation).", I feel like it might be more clear if this property was
named after what the result is, perhaps something like "operationBlocked"
or "operationPrevented".

I believe these types of issues can be resolved by replacing boolean values
by Enums, hence my suggestion. Enum would be more self explanatory and
would provide better insight on the outcome. I also like Jordi's
suggestion, anything that can help static analysis is the way to go IMHO.

Best regards,
Ignace

Hi Gina,

On Tuesday, 18 November 2025 at 18:41, Jakub Zelenka bukka@php.net
wrote:

Hello,

I would like to introduce a new stream error handling RFC that is part of
my stream evolution work (PHP Foundation project funded by Sovereign Tech
Fund) :

https://wiki.php.net/rfc/stream_errors

Hi Jakub,

Thank you for working on this, this has been a long-standing pain point of
our stream layer.
However, I do have various comments about the design of this.

Echoing multiple voices, please use enums rather than constants where
applicable, and use an object rather than an associative array for
individual stream errors.
As others have pointed out, the notion of (non-)"terminal" errors is not
clear, and I'm struggling to understand what is the point of it?

I just answered this in replay to Bob. The non terminating errors are those
that don't change return value of the function (it means not returning
failure). Some of those errors are still useful and users should be
notified but they are not critical for correct result. This was mainly
introduced for exceptions as those cases should not throw but it still
makes sense to somehow notify users (e.g. store the error).

How does this interact with the stream notification stuff?
(I guess surrounding PHP_STREAM_NOTIFY_SEVERITY_INFO and
PHP_STREAM_NOTIFY_SEVERITY_ERR)

It doesn't interact with it. Although PHP_STREAM_NOTIFY_SEVERITY_ERR
somehow overlaps with it but it's limited in use (currently used only in
ftp and http wrapper). Obviously I couldn't just use notifications and I
needed to keep them working so the only possibility was to introduce a new
API that handles just errors. Going forward I'm not
sure PHP_STREAM_NOTIFY_SEVERITY_ERR should be kept but that's more a future
scope I guess.

Regarding "docref" what is the point of including this in the error?
This is mainly used with php_docref to generate links to INI settings by
referencing an XML ID that exists in doc-en, this does not seem applicable
here.
I guess you added this due to the two usages of "streams.crypto" as a
docref in main/streams/transports.c, but this ID doesn't exist, and I
fear this might never have worked properly.
As such, I would recommend just getting rid of this.

Agreed I'm not going to expose it. I will keep it just for error mode to
keep it the same but I guess it might be better to drop it completely in
the future.

The last thing that I feel very strongly about is that there should only
be 3 modes:

• Silent
• Warnings
• Exceptions

As such, the cases where we currently emit a notice should either be
promoted to warnings (which for some of them I don't even understand why
they are just notices) or removed (mainly looking at the one in
main/streams/userspace.c)

And the singular case which bailouts using E_ERROR should be converted to

always throw an exception.
Bailouts cause all sorts of issues due to the lack of unwinding, things
that exceptions solve.
This would also simplify both the internal, and userland API and get rid
of the confusing notion of "errors" meaning "diagnostics/warnings".

My aim is really not to touch the current logic and the error
classification except one case where reporting was done accidentally. I
think that non terminating errors make some sense as they give some hint
that something could be improved but it's not necessarily preventing the
functioning. This is something that has been already there and I don't
think it needs to be changed as part of this proposal.

Cheers,

Jakub

Hi,

On Wed, Nov 19, 2025 at 5:35 PM Larry Garfield larry@garfieldtech.com
wrote:

Hello,

I would like to introduce a new stream error handling RFC that is part
of my stream evolution work (PHP Foundation project funded by Sovereign
Tech Fund) :

https://wiki.php.net/rfc/stream_errors

Kind regards,

Jakub

HI Jakub.

I agree with what others have said so far. I'm going to ask a little bit
further, though.

AIUI, there's two main issues with the stream API:

1. It's very inconsistent.
2. It's very clunky, non-obvious, and hard to use if you don't know
   exactly what you're doing.

This RFC seems to be addressing the first point, which is fine. However,
should we be trying to smooth out the current unpleasant API, or should the
effort be put toward a more intuitive API that is smoother from the start?
This RFC could be a stepping stone toward that, I'm not sure, but if so
that's not clear to me.

Are there any longer term plans here for a more complete stream overhaul?

This RFC is part of the bigger effort to address various stream issues and
provide other stream related improvements that I selected based on my TODO
list. You can see more detailed description of the whole scope in this
foundation blog:
https://thephp.foundation/blog/2025/10/30/php-streams-evolution/ .

The overhaul of the whole API is out of scope as there are lots of unknowns
and would require longer migration. It is thus harder to deliver in the
selected time frame. It doesn't mean that it won't happen. It's just out of
scope for this block of work and I don't have specific plans for it.

Kind regards,

Jakub

 Hi, I just published version 2.0 which is a significant redesign
including:

• Introducing ... StreamErrorCode
  enums.... The
  code is backed (int) because I need to keep the number to easily match
  the category and simplify the mapping. I think that in this case a
  backed enum is better.

Just spitballing here, but perhaps a StreamErrorCategory enum? The Code
could have a method/property that matches it to the corresponding
Category; categorising errors of different kinds can be done by
branching on the Category, rather than (possibly multiple) is*Error() tests.

Am 29.12.2025 um 19:52 schrieb Jakub Zelenka bukka@php.net:

• The storing of errors is done at the end of the operation grouping and contains only the last grouped errors. So the function name was changed to stream_get_last_error(). It returns just a single StreamError which has a next property pointing to the next error if there is any.

I assume the chaining was based on Exception chaining but the example code under
https://wiki.php.net/rfc/stream_errors#error_chaining
looks a bit clunky to me and I was wondering if returning an array of StreamError would not be more straightforward, i.e. one could then use foreach, empty(), count(), array_first(), array_last(), array_find() etc. instead of methods like while, $e->count(), $e->hasCode() which would make it feel more idiomatic to me.

But then again it might be a matter of taste and/or I might have missed something.

Regards,

• Chris

Hi Jakub,

I would like to introduce a new stream error handling RFC that is part of

my stream evolution work (PHP Foundation project funded by Sovereign Tech
Fund) :

https://wiki.php.net/rfc/stream_errors

As there has not been much discussion and keeping the patch up to date is
a slight pain, I plan to open voting on Friday (27/02/26) evening or
Saturday (28/02/26) morning unless some changes are required ofc.

Thanks for the reminder! I discussed this with others and we raised the
following points:

1. StreamErrorCode::None: do we need it?

Having an enum case representing "no error" feels a bit off to me. If an
API needs to express the absence of an error, would,'t StreamErrorCode|null
be more idiomatic? StreamErrorCode::None seems like a nullable value
disguised as an enum case, and it means callers always have to guard
against it, which somewhat defeats the purpose of using an enum. Am I
missing a use case where ::None is genuinely needed?

2. StreamError::$next — is the naming intentional?

Since stream_get_last_error() returns the most recent error and the chain
travels backwards through time, $next seems to point to the previous error
chronologically. Would something like $previous (echoing
Throwable::getPrevious()) work better, or is the current naming deliberate?

3. Should StreamErrorCode really be an enum?

The RFC lists in its "Future Scope" section: "Extension-specific error
ranges - Reserved ranges for extensions to define custom error codes."

This gave us pause. Enums in PHP are intentionally a closed, finite type:
their value is precisely that "invalid states become unrepresentable." If
extensions can define custom error codes at runtime, the set of possible
values would depend on which extensions are installed, and the type would
no longer be truly enumerable.
Larry touches on this exact tension in this post: when the value space
needs to be open or user-extensible, an enum is the wrong tool.
https://www.garfieldtech.com/blog/on-the-use-of-enums#open-type

I'd also expect the built-in list of codes to keep growing over time as
more wrappers and edge cases are covered; which is another hint the domain
may not be fixed.

Would a set of integer constants (possibly grouped in a class or interface)
be appropriate? It would be more honest about the open-ended nature of the
value space while still allowing meaningful comparisons, without creating
false expectations of exhaustiveness.

4. Using stream_context_set_default to change error_mode looks hazardous

The RFC includes an example where stream_context_set_default is used to set
error_mode to StreamErrorMode::Exception globally. I'm worried about the
ecosystem impact here: if any library or application bootstrap does use
this, then existing packages using the common
@file_get_contents('maybe_existing_file') idiom could e.g. suddenly throw
uncaught exceptions, breaking behavior their authors had deliberately
chosen. This feels like a significant compatibility hazard for code that
doesn't control its full execution environment.

Would it be worth restricting error_mode (and possibly the other new
options) so that they can only be set via per-call contexts, not via
stream_context_set_default?

Thanks for working on this, we definitely need this!

Cheers,
Nicolas

Hi,

Sorry for slightly late reply. I wanted to think about it and was also busy
with other stuff.

Hi Jakub,

Hello,

I would like to introduce a new stream error handling RFC that is part
of my stream evolution work (PHP Foundation project funded by Sovereign
Tech Fund) :

https://wiki.php.net/rfc/stream_errors

Thank you for this RFC! . It is clearly needed and the error chaining
design is great. There are a few points I'd like to raise, the last
two being slightly off topic specifically to that rfc but however very
related to. So a slightly long reply.

1. New exceptions

The current design has a single flat StreamException. This means the
exception path requires inspecting the error object to branch on
category:

catch (StreamException $e) {
if ($e->getError()->isNetworkError()) {
// retry
} elseif ($e->getError()->code === StreamError::CODE_NOT_FOUND) {
// fallback
}
}

The current design introduces StreamException, which is good. But as a
single flat class it doesn't actually allow to use exceptions the way
exceptions are meant to be used. One still has to inspect the error
object inside the catch block to know what happened. It introduces the
syntax of exception handling without the benefit of it.

Since the error categories are already well-defined and stable in this
RFC, StreamException could be a base class with typed subclasses
mirroring those categories:

StreamException
├ StreamIoException
├ StreamFileSystemException
├ StreamNetworkException
├ StreamWrapperException
└ ...

This allows the more natural and idiomatic:

catch (StreamNetworkException $e) {
// retry — type alone tells you what happened
} catch (StreamNotFoundException $e) {
// fallback
} catch (StreamException $e) {
// generic
}

The StreamError value object can stay as in the RFC (and keep "BC" for
the error const's bag), it's appropriate for the inspection/silent
mode use case. I see the typed exception hierarchy and the flat value
object serve different purposes and complement each other:
$e->getError() still gives you full detail when you need it. These are
separable concerns currently merged into one class.

I thought about this a lot and I'm not sure this would be that useful as I
don't see a big enough use case for cetegorization on exception level. It
was exposed more as a nice to have but I doubt that users will care that
much if the error is an Io or FileSystem category. It seems also slightly
messe to have the exception class dependent on the error category that it
holds as a property. I would possibly reconsider it if I saw a big use case
for categorization but I see it more as a nice to have utility which
doesn't need to propagate in this way.

Since StreamException doesn't exist in any current PHP version, there
is no existing userland code catching it. This is a clean state.
Adding a typed hierarchy now costs nothing in BC terms, and
retrofitting it later would be a BC break.

I don't think it would be an unacceptable BC break to split it later if
there was a really need for that. The parent would still
stay StreamException and all code that catches it would still work. I don't
think any reasonable code would relay on the exception to be exactly
StreamException and not it's subclass so I wouldn't see that as an issue
form the BC point of view.

It is more than just syntactic sugar, it allows very clean logic.
static analysis tools can reason about which exceptions a function
throws, IDEs can suggest catch blocks, and retry wrappers can target
network errors specifically without accidentally swallowing filesystem
errors. The cost of adding the hierarchy now is low; retrofitting it
later is a BC break.

As I said above I really don't see much use case in just targeting network
errors. That's really niche use case IMHO and for that it can just get it
from the StreamError. My main issue with this is that dependency between
StreamException subclass and StreamError.

2. Custom stream wrapper and errors

How does custom wrappers, be in ext/, or out of core wrappers, exts or
user land, can emit errors? Or is it out of the scope of this RFC?

The wrapper needs to be adapted and call the new API functions. It might
also require additional global types if needed (most of the wrappers should
be fine with existing ones but there might be use case to add more).

For wrappers authors, f.e. in zip, php_error_docref(NULL, E_WARNING,
"Zip stream error: %s", zip_error_strerror(err));, or
php_stream_wrapper_log_error() it is the classic php error. Both were
acceptable and the only way available, without relying on custom
methods, but if the stream's error handling is being improved, or made
future proof (when possible), together with the typed exception, we
could get something good. The typed exceptions give callers a clean
API. Adding an emit function gives wrapper authors a clean API. They
close the loop. Either one without the other leaves the whole thing
incomplete.

If typed exceptions exist and stream_emit_error in userland and
php_stream_emit_error internally exist, wrappers can emit errors that
integrate cleanly with the catch hierarchy, and have better error
reporting.

The internal API is working just with types that fall into some categories.
I don't see any relation to typed exception here. The API is just about
emitting typed errors through.

Some of the future scopes seem foundational to stream error handling
improvements, and risky to delay rather than allowing them now.

Covering all existing wrappers from the start is just not realistic. I
actually started with generic type registration but it got quite complex
and it would require some unstable type registration which couldn't be
exposed as constants. I also realised that the actually types are repeating
between wrappers so it was just better to switch to global types.

That extension type ranges in future scope was actually a left over when I
was still considering this dynamic registration. I just removed it.

the slightly off topic ones:

Is there a published overall design document for the stream evolution
project? The foundation blog post outlines four pillars at a (very)
high level, but the relationship between the RFCs, their
sequencing/order rationale to be added already, and the intended end
state of the streams API are not spelled out anywhere I can find.
Having that available would make it much easier to give a more
informed feedback on each RFC as it arrives, and to flag conflicts or
gaps early.

I got some future improvements in my head but the short term plan is just
what was published and what we have funding for. The rest depends on
further funding and available resources to do the actual work so there is
not much point in too detailed plan.

Streams were introduced over two decades ago (afair it was in the
early 2000s, by Wez. we aren't younger :), and much has changed since.
Async runtimes (swoole, reactphp, FrankenPhp to some extent, etc),
fibers, modern TLS, io_uring, and very different application patterns.
The error RFC itself acknowledges the BC constraints that shape its
design. My concern is that modernizing streams incrementally in 8.x,
under those constraints, risks producing something that is improved
but still not fit for where PHP needs to go, or ideally should go,
particularly around async I/O, where error handling, stream selection,
and the overall API surface will need to work together in a coherent
manner.

Is there a published async I/O architecture that these RFCs are
building toward? The other stream related RFCs or the phpf's blog
post mention future work about async IO, and related stream topics,
which suggests the async design exists internally but hasn't been
shared publicly. If that's the case, it would be fantastic to share it
(even as a draft design doc), so it can be assessed whether the
current incremental steps are pointing in the right direction, or
whether some decisions being made now will need to be undone later (or
will be impossible to undo without breaking BC). Especially if authors
of Swoole (made io uring into their php 8.5 version it seems :),
reactphp, etc would surely provide extremely good feedback too.

The polling RFC is the first step that also introduces new IO handle
abstraction. I'm building on that internally in new copy API that also uses
those new handles. What I plan to look after polling is the notification
API that would all IO notifications before the actual IO with future
possibility of taking over the IO operation. Then I'm also experiment with
new IO ring API (basically io_uring with fallbacks for other platforms)
that would allow async IO handling. I don't have more details at this stage
but there should be RFC's coming in the second half of this year where more
details will be shared.

Kind regards,

Jakub