Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:130481
Precedence: list
MIME-Version: 1.0
References: <CAEKnhAEO8w0GJXTVyH_nwK8nGQGdJcNNkGOPMnYDVrcsNGrm4A@mail.gmail.com>
 <CAEZPtU73vLhdYu6Ppj84B3sSCCk+p7C4didxsYSu-z9MNFD_2g@mail.gmail.com> <CAEKnhAHVzCTiamf-xXJSj18EvQfhB5Uf9NGA490x5a2qrGAu=Q@mail.gmail.com>
In-Reply-To: <CAEKnhAHVzCTiamf-xXJSj18EvQfhB5Uf9NGA490x5a2qrGAu=Q@mail.gmail.com>
Date: Sun, 29 Mar 2026 20:31:07 +0200
Message-ID: <CAEKnhAE85hurL-cBDOh4M5X1sVrp+AfMm1rwcPPqt4Mnhy6M-g@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="000000000000ba807b064e2df085"
From: bukka@php.net (Jakub Zelenka)

--000000000000ba807b064e2df085
Content-Type: text/plain; charset="UTF-8"
Content-Transfer-Encoding: quoted-printable

Hi,

On Sun, Mar 22, 2026 at 8:26=E2=80=AFPM Jakub Zelenka <bukka@php.net> wrote=
:

> 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>=
 wrote:
>
>> Hi Jakub,
>>
>> On Tue, Dec 23, 2025 at 6:10=E2=80=AFAM Jakub Zelenka <bukka@php.net> wr=
ote:
>> >
>> > 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 ca=
se
> for categorization but I see it more as a nice to have utility which
> doesn't need to propagate in this way.
>
>

When implementing the recent changes I actually realised that introducing
this exception hierarchy does not make any sense because there can be
multiple errors in an exception and they can have different categories so
the exception cannot be reasonably categorised to a single category. This
became more obvious with getErrors() - previously I didn't realised it
because it was linked list and somehow forgot that they can have different
categories.

Kind regards,

Jakub

--000000000000ba807b064e2df085
Content-Type: text/html; charset="UTF-8"
Content-Transfer-Encoding: quoted-printable

<div dir=3D"ltr"><div>Hi,</div><br><div class=3D"gmail_quote gmail_quote_co=
ntainer"><div dir=3D"ltr" class=3D"gmail_attr">On Sun, Mar 22, 2026 at 8:26=
=E2=80=AFPM Jakub Zelenka &lt;<a href=3D"mailto:bukka@php.net">bukka@php.ne=
t</a>&gt; wrote:<br></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"=
><div dir=3D"ltr"><div dir=3D"ltr">Hi,<div><br></div><div>Sorry for slightl=
y late reply. I wanted to think about it and was also busy with other stuff=
.</div></div><br><div class=3D"gmail_quote"><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"ma=
ilto:pierre.php@gmail.com" target=3D"_blank">pierre.php@gmail.com</a>&gt; w=
rote:<br></div><blockquote class=3D"gmail_quote" style=3D"margin:0px 0px 0p=
x 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">Hi Jakub,<=
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=
></div></div></blockquote><div><br></div><div>When implementing the recent =
changes I actually realised that introducing this exception hierarchy does =
not make any sense because there can be multiple errors in an exception and=
 they can have different categories so the exception cannot be reasonably c=
ategorised to a single category. This became more obvious with getErrors() =
- previously I didn&#39;t realised it because it was linked list and someho=
w forgot that they can have different categories.</div><div><br></div><div>=
Kind regards,</div><div><br></div><div>Jakub</div></div></div>

--000000000000ba807b064e2df085--