Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:130414
Precedence: list
MIME-Version: 1.0
References: <CAEKnhAEO8w0GJXTVyH_nwK8nGQGdJcNNkGOPMnYDVrcsNGrm4A@mail.gmail.com>
 <CAEZPtU73vLhdYu6Ppj84B3sSCCk+p7C4didxsYSu-z9MNFD_2g@mail.gmail.com>
In-Reply-To: <CAEZPtU73vLhdYu6Ppj84B3sSCCk+p7C4didxsYSu-z9MNFD_2g@mail.gmail.com>
Date: Sun, 22 Mar 2026 20:26:43 +0100
Message-ID: <CAEKnhAHVzCTiamf-xXJSj18EvQfhB5Uf9NGA490x5a2qrGAu=Q@mail.gmail.com>
Subject: Re: [PHP-DEV] [RFC] Stream Error Handling Improvements
To: Pierre Joye <pierre.php@gmail.com>
Cc: PHP internals list <internals@lists.php.net>
Content-Type: multipart/alternative; boundary="000000000000aab844064da1e693"
From: bukka@php.net (Jakub Zelenka)

--000000000000aab844064da1e693
Content-Type: text/plain; charset="UTF-8"
Content-Transfer-Encoding: quoted-printable

Hi,

Sorry for slightly late reply. I wanted to think about it and was also busy
with other stuff.

On Sun, Mar 1, 2026 at 4:09=E2=80=AFPM Pierre Joye <pierre.php@gmail.com> w=
rote:

> Hi Jakub,
>
> On Tue, Dec 23, 2025 at 6:10=E2=80=AFAM Jakub Zelenka <bukka@php.net> wro=
te:
> >
> > 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 =3D=3D=3D 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
> =E2=94=9C StreamIoException
> =E2=94=9C StreamFileSystemException
> =E2=94=9C StreamNetworkException
> =E2=94=9C StreamWrapperException
> =E2=94=94 ...
>
>
> This allows the more natural and idiomatic:
>
> catch (StreamNetworkException $e) {
>     // retry =E2=80=94 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

--000000000000aab844064da1e693
Content-Type: text/html; charset="UTF-8"
Content-Transfer-Encoding: quoted-printable

<div dir=3D"ltr"><div dir=3D"ltr">Hi,<div><br></div><div>Sorry for slightly=
 late reply. I wanted to think about it and was also busy with other stuff.=
</div></div><br><div class=3D"gmail_quote gmail_quote_container"><div dir=
=3D"ltr" class=3D"gmail_attr">On Sun, Mar 1, 2026 at 4:09=E2=80=AFPM Pierre=
 Joye &lt;<a href=3D"mailto:pierre.php@gmail.com">pierre.php@gmail.com</a>&=
gt; wrote:<br></div><blockquote class=3D"gmail_quote" style=3D"margin:0px 0=
px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">Hi Ja=
kub,<br>
<br>
On Tue, Dec 23, 2025 at 6:10=E2=80=AFAM Jakub Zelenka &lt;<a href=3D"mailto=
:bukka@php.net" target=3D"_blank">bukka@php.net</a>&gt; wrote:<br>
&gt;<br>
&gt; Hello,<br>
&gt;<br>
&gt; 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 Te=
ch Fund) :<br>
&gt;<br>
&gt; <a href=3D"https://wiki.php.net/rfc/stream_errors" rel=3D"noreferrer" =
target=3D"_blank">https://wiki.php.net/rfc/stream_errors</a><br>
<br>
Thank you for this RFC! . It=C2=A0 is clearly needed and the error chaining=
<br>
design is great. There are a few points I&#39;d like to raise, the last<br>
two being slightly off topic specifically to that rfc but however very<br>
related to. So a slightly long reply.<br>
<br>
1. New exceptions<br>
<br>
The current design has a single flat StreamException. This means the<br>
exception path requires inspecting the error object to branch on<br>
category:<br>
<br>
catch (StreamException $e) {<br>
=C2=A0 =C2=A0 if ($e-&gt;getError()-&gt;isNetworkError()) {<br>
=C2=A0 =C2=A0 =C2=A0 =C2=A0 // retry<br>
=C2=A0 =C2=A0 } elseif ($e-&gt;getError()-&gt;code =3D=3D=3D StreamError::C=
ODE_NOT_FOUND) {<br>
=C2=A0 =C2=A0 =C2=A0 =C2=A0 // fallback<br>
=C2=A0 =C2=A0 }<br>
}<br>
<br>
The current design introduces StreamException, which is good. But as a<br>
single flat class it doesn&#39;t actually allow to use exceptions the way<b=
r>
exceptions are meant to be used. One still has to inspect the error<br>
object inside the catch block to know what happened. It introduces the<br>
syntax of exception handling without the benefit of it.<br>
<br>
Since the error categories are already well-defined and stable in this<br>
RFC, StreamException could be a base class with typed subclasses<br>
mirroring those categories:<br>
<br>
StreamException<br>
=E2=94=9C StreamIoException<br>
=E2=94=9C StreamFileSystemException<br>
=E2=94=9C StreamNetworkException<br>
=E2=94=9C StreamWrapperException<br>
=E2=94=94 ...<br>
<br>
<br>
This allows the more natural and idiomatic:<br>
<br>
catch (StreamNetworkException $e) {<br>
=C2=A0 =C2=A0 // retry =E2=80=94 type alone tells you what happened<br>
} catch (StreamNotFoundException $e) {<br>
=C2=A0 =C2=A0 // fallback<br>
} catch (StreamException $e) {<br>
=C2=A0 =C2=A0 // generic<br>
}<br>
<br>
The StreamError value object can stay as in the RFC (and keep &quot;BC&quot=
; for<br>
the error const&#39;s bag), it&#39;s appropriate for the inspection/silent<=
br>
mode use case. I see the typed exception hierarchy and the flat value<br>
object serve different purposes and complement each other:<br>
$e-&gt;getError() still gives you full detail when you need it. These are<b=
r>
separable concerns currently merged into one class.<br></blockquote><div><b=
r></div><div>I thought about this a lot and I&#39;m not sure this would be =
that useful as I don&#39;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 use=
rs will care that much if the error is an Io or FileSystem category. It see=
ms also slightly messe to have the exception class dependent on the error c=
ategory that it holds as a property. I would possibly reconsider it if I sa=
w a big use case for categorization but I see it more as a nice to have uti=
lity which doesn&#39;t need to propagate in this way.</div><div>=C2=A0</div=
><blockquote class=3D"gmail_quote" style=3D"margin:0px 0px 0px 0.8ex;border=
-left:1px solid rgb(204,204,204);padding-left:1ex">
Since StreamException doesn&#39;t exist in any current PHP version, there<b=
r>
is no existing userland code catching it. This is a clean state.<br>
Adding a typed hierarchy now costs nothing in BC terms, and<br>
retrofitting it later would be a BC break.<br></blockquote><div><br></div><=
div>I don&#39;t think it would be an unacceptable BC break to split it late=
r if there was a really need for that. The parent would still stay=C2=A0Str=
eamException and all code that catches it would still work. I don&#39;t thi=
nk any reasonable code would relay on the exception to be exactly StreamExc=
eption and not it&#39;s subclass so I wouldn&#39;t see that as an issue for=
m the BC point of view.=C2=A0</div><div>=C2=A0</div><blockquote class=3D"gm=
ail_quote" style=3D"margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,=
204,204);padding-left:1ex">
It is more than just syntactic sugar, it allows very clean logic.<br>
static analysis tools can reason about which exceptions a function<br>
throws, IDEs can suggest catch blocks, and retry wrappers can target<br>
network errors specifically without accidentally swallowing filesystem<br>
errors. The cost of adding the hierarchy now is low; retrofitting it<br>
later is a BC break.<br></blockquote><div><br></div><div>As I said above I =
really don&#39;t see much use case in just targeting network errors. That&#=
39;s really niche use case IMHO and for that it can just get it from the St=
reamError. My main issue with this is that dependency between StreamExcepti=
on subclass and StreamError.</div><div>=C2=A0</div><blockquote class=3D"gma=
il_quote" style=3D"margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,2=
04,204);padding-left:1ex">
<br>
2. Custom stream wrapper and errors<br>
<br>
How does custom wrappers, be in ext/, or out of core wrappers, exts or<br>
user land, can emit errors? Or is it out of the scope of this RFC?<br>
<br></blockquote><div><br></div><div>The wrapper needs to be adapted and ca=
ll 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 mi=
ght be use case to add more).</div><div>=C2=A0</div><blockquote class=3D"gm=
ail_quote" style=3D"margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,=
204,204);padding-left:1ex">
For wrappers authors, f.e. in zip, php_error_docref(NULL, E_WARNING,<br>
&quot;Zip stream error: %s&quot;, zip_error_strerror(err));, or<br>
php_stream_wrapper_log_error() it is the classic php error. Both were<br>
acceptable and the only way available, without relying on custom<br>
methods, but if the stream&#39;s error handling is being improved, or made<=
br>
future proof (when possible), together with the typed exception, we<br>
could get something good. The typed exceptions give callers a clean<br>
API. Adding an emit function gives wrapper authors a clean API. They<br>
close the loop. Either one without the other leaves the whole thing<br>
incomplete.</blockquote><blockquote class=3D"gmail_quote" style=3D"margin:0=
px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
<br>
If typed exceptions exist and stream_emit_error in userland and<br>
php_stream_emit_error internally exist, wrappers can emit errors that<br>
integrate cleanly with the catch hierarchy, and have better error<br>
reporting.<br>
<br></blockquote><div><br></div><div>The internal API is working just with =
types that fall into some categories. I don&#39;t see any relation to typed=
 exception here. The API is just about emitting typed errors through.</div>=
<div>=C2=A0</div><blockquote class=3D"gmail_quote" style=3D"margin:0px 0px =
0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
Some of the future scopes seem foundational to stream error handling<br>
improvements, and risky to delay rather than allowing them now.<br>
<br></blockquote><div><br></div><div>Covering all existing wrappers from th=
e start is just not realistic. I actually started with generic type registr=
ation but it got quite complex and it would require some unstable type regi=
stration which couldn&#39;t be exposed as constants. I also realised that t=
he actually types are repeating between wrappers so it was just better to s=
witch to global types.=C2=A0</div><div><br></div><div>That extension type r=
anges in future scope was actually a left over when I was still considering=
 this dynamic registration. I just removed it.</div><div>=C2=A0</div><block=
quote class=3D"gmail_quote" style=3D"margin:0px 0px 0px 0.8ex;border-left:1=
px solid rgb(204,204,204);padding-left:1ex">
the slightly off topic ones:<br>
<br>
Is there a published overall design document for the stream evolution<br>
project? The foundation blog post outlines four pillars at a (very)<br>
high level, but the relationship between the RFCs, their<br>
sequencing/order rationale to be added already, and the intended end<br>
state of the streams API are not spelled out anywhere I can find.<br>
Having that available would make it much easier to give a more<br>
informed feedback on each RFC as it arrives, and to flag conflicts or<br>
gaps early.<br>
<br></blockquote><div><br></div><div>I got some future improvements in my h=
ead but the short term plan is just what was published and what we have fun=
ding 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.</div><div=
>=C2=A0</div><blockquote class=3D"gmail_quote" style=3D"margin:0px 0px 0px =
0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
Streams were introduced over two decades ago (afair it was in the<br>
early 2000s, by Wez. we aren&#39;t younger :), and much has changed since.<=
br>
Async runtimes (swoole, reactphp, FrankenPhp to some extent, etc),<br>
fibers, modern TLS, io_uring, and very different application patterns.<br>
The error RFC itself acknowledges the BC constraints that shape its<br>
design. My concern is that modernizing streams incrementally in 8.x,<br>
under those constraints, risks producing something that is improved<br>
but still not fit for where PHP needs to go, or ideally should go,<br>
particularly around async I/O, where error handling, stream selection,<br>
and the overall API surface will need to work together in a coherent<br>
manner.<br>
<br>
Is there a published async I/O architecture that these RFCs are<br>
building toward?=C2=A0 The other stream related RFCs or the phpf&#39;s blog=
<br>
post mention future work about async IO, and related stream topics,<br>
which suggests the async design exists internally but hasn&#39;t been<br>
shared publicly. If that&#39;s the case, it would be fantastic to share it<=
br>
(even as a draft design doc),=C2=A0 so it can be assessed whether the<br>
current incremental steps are pointing in the right direction, or<br>
whether some decisions being made now will need to be undone later (or<br>
will be impossible to undo without breaking BC). Especially if authors<br>
of Swoole (made io uring into their php 8.5 version it seems :),<br>
reactphp, etc would surely provide extremely good feedback too.<br><br></bl=
ockquote><div><br></div><div>The polling RFC is the first step that also in=
troduces new IO handle abstraction. I&#39;m building on that internally in =
new copy API that also uses those new handles. What I plan to look after po=
lling is the notification API that would all IO notifications before the ac=
tual IO with future possibility of taking over the IO operation. Then I&#39=
;m also experiment with new IO ring API (basically io_uring with fallbacks =
for other platforms) that would allow async IO handling. I don&#39;t have m=
ore details at this stage but there should be RFC&#39;s coming in the secon=
d half of this year where more details will be shared.</div><div><br></div>=
<div>Kind regards,</div><div><br></div><div>Jakub</div></div></div>

--000000000000aab844064da1e693--