Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:130535
Precedence: list
MIME-Version: 1.0
References: <CAEKnhAEO8w0GJXTVyH_nwK8nGQGdJcNNkGOPMnYDVrcsNGrm4A@mail.gmail.com>
 <CAEKnhAGCxHOTOmtU7c8rqm3MY8a4vvoJ3NH7BdR0SNp+7sFWHg@mail.gmail.com>
 <CAOWwgpk5wpyWo-qeVO4mGwKygTMFMeXDt3_1Cf4wLOK4ZgZaSw@mail.gmail.com>
 <CAEKnhAHFKYbXMm7LU+-yexLgwRmw=fPx8b5vUVNOQUg5AjRbaw@mail.gmail.com>
 <f49931e8334d6c745d5daa5afd4ebcd8@bastelstu.be> <CAEKnhAGPUowhK8z1MKGqkU3otk0oi0pqMu4=UO_V3JGQK9LscQ@mail.gmail.com>
 <1597c99a0ad7dc1e55a40f952d7536c5@bastelstu.be> <CAEZPtU68T9m-ddM15vrtsCcwNuEW9=Pe3m89nv9vjq3mffei8Q@mail.gmail.com>
In-Reply-To: <CAEZPtU68T9m-ddM15vrtsCcwNuEW9=Pe3m89nv9vjq3mffei8Q@mail.gmail.com>
Date: Thu, 2 Apr 2026 19:36:14 +0200
Message-ID: <CAEKnhAFaUbias8kzJ9tTbwpUQxFrmgiBfRUqVqoWtwx6QS2T-w@mail.gmail.com>
Subject: Re: [PHP-DEV] Re: [RFC] Stream Error Handling Improvements
To: Pierre Joye <pierre.php@gmail.com>
Cc: =?UTF-8?Q?Tim_D=C3=BCsterhus?= <tim@bastelstu.be>, 
	Nicolas Grekas <nicolas.grekas+php@gmail.com>, PHP internals list <internals@lists.php.net>
Content-Type: multipart/alternative; boundary="000000000000cca472064e7da368"
From: bukka@php.net (Jakub Zelenka)

--000000000000cca472064e7da368
Content-Type: text/plain; charset="UTF-8"
Content-Transfer-Encoding: quoted-printable

Hi,

On Thu, Apr 2, 2026 at 11:18=E2=80=AFAM Pierre Joye <pierre.php@gmail.com> =
wrote:

> Hi Tim, Jakub,
>
> On Tue, Mar 31, 2026 at 5:52=E2=80=AFPM Tim D=C3=BCsterhus <tim@bastelstu=
.be> wrote:
> >
> > Hi
> >
> > Am 2026-03-29 20:25, schrieb Jakub Zelenka:
> > >> For the naming of `stream_get_last_error()`: Within PHP we have both
> > >> `X_get_last_error()` and `X_last_error()`. The latter seems to be mo=
re
> > >> common and also what I would prefer here, because the `stream_get_`
> > >> prefix sounds to me like we would get something from a stream, but t=
he
> > >> returned value is not related to a specific stream, but rather a
> > >> global.
> > >>
> > >>
> > > Good point, I changed it but because it now returns array (no linked
> > > list),
> > > it's called stream_last_errors(). I also added  stream_clear_errors f=
or
> > > explicit clearing which might be useful in some situations.
> >
> > That both makes sense to me.
> >
> > > The RFC and the implementation is updated so please take a look!
> >
> ...
> > 3. For "StreamErrorCode::is*()"
> >
> > Can error codes fall into multiple categories or is it always a single
> > one? If it's guaranteed to be a single category, then perhaps a
> > `->getErrorCategory()` method returning a StreamErrorCodeCategory enum
> > makes more sense and allow for simpler / more efficient code when folks
> > are interested in checking for multiple different categories. Instead o=
f
> > `$code->isNetworkError() || $code->isFileSystemError()` they can do
> > `\in_array($code->getErrorCategory(),
> > [StreamErrorCodeCategory::NetworkError,
> > StreamErrorCodeCategory::FileSystemError], true)` or use a `match()`
>
> These points actually are on the spot about what I've been trying to
> raise earlier in this thread, or they demonstrate it nicely.
>
> Suggesting a getErrorCategory() method or a StreamErrorCodeCategory
> enum to make category checks cleaner. That's a reasonable API
> improvement, in the context of what the RFC proposes in the current
> state. But it also highlights the underlying design issue: we're
> building a parallel categorization system on top of error codes, when
> the type system already provides exactly this, through exception
> subclasses, for free. That reminds a bit of the early OO's time in php
> when all we did was to wrap the legacy procedural implementation in
> dumb OO wrapper, saving, if lucky, user's keystrokes. That's not even
> the case here.
>
> The point is that a stream operation can produce errors of different
> categories and therefore the exception "cannot be reasonably
> categorised": this is how exceptions have always worked. One throws
> the primary exception, the one that caused the operation to fail, and
> chain additional context via $previous or attach it as metadata. The
> caller catches what they care about:
>
> catch (StreamNetworkException $e) {...}
>
> The exception type answers "what do I do about this?" The error chain
> answers exactly what happens, where in detail. These are different
> questions for different uses, and conflating them is what leads to the
> current design where it catches a flat StreamException and then has to
> inspect its contents to find out what kind of failure it was.
>
> getErrorCategory() suggestion would give us
> match($e->getErrors()[0]->getErrorCategory()) { ... } inside a catch
> block. That's essentially reimplementing what catch
> (StreamNetworkException $e) already does, except the type system can't
> help, static analysis can't reason about it, and it can't compose it
> with other exception handling in a codebase.
>
> The current RFC introduces exception syntax without exception
> semantics. The isFileSystemError(), isNetworkError() methods, and now
> potentially getErrorCategory(). are workarounds for the absence of a
> typed hierarchy, not features we should need in the 1st place.
>
>
Thanks for the thorough feedback. After some considering I decided not to
expose those helpers at this stage. The reason is that the current
classification is a bit uncertain and I want to have more final set of
error codes before anything like this is introduced. The current setup was
a bit random and sometimes it could go to multiple categories so there are
some decisions to be made. Also the is* methods were not the best design as
pointed out and other option should be considered. I'm also not too sure
about usefulness of categories. All of this should be decided on its own
and later.



> Since StreamException does not exist in any current PHP version, there
> is zero BC cost to making it a proper base class now. It takes more
> effort to design such additions correctly, however it would be a
> significant improvement in the long run for php's stream, beyond a
> current internal refactoring and long due cleaning :).
>
>
I don't see how it takes more effort later. There is also pretty much no BC
break even if we went if subclassing exceptions as I noted before. I think
actually exactly opposite here. If we rush it and use incorrect categories
for some errors, it will be a BC break to correct so this needs a proper
considering and this feature should be added later.

Kind regards,

Jakub

--000000000000cca472064e7da368
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 Thu, Apr 2, 2026 at 11:18=
=E2=80=AFAM 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" sty=
le=3D"margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);paddi=
ng-left:1ex">Hi Tim, Jakub,<br>
<br>
On Tue, Mar 31, 2026 at 5:52=E2=80=AFPM Tim D=C3=BCsterhus &lt;<a href=3D"m=
ailto:tim@bastelstu.be" target=3D"_blank">tim@bastelstu.be</a>&gt; wrote:<b=
r>
&gt;<br>
&gt; Hi<br>
&gt;<br>
&gt; Am 2026-03-29 20:25, schrieb Jakub Zelenka:<br>
&gt; &gt;&gt; For the naming of `stream_get_last_error()`: Within PHP we ha=
ve both<br>
&gt; &gt;&gt; `X_get_last_error()` and `X_last_error()`. The latter seems t=
o be more<br>
&gt; &gt;&gt; common and also what I would prefer here, because the `stream=
_get_`<br>
&gt; &gt;&gt; prefix sounds to me like we would get something from a stream=
, but the<br>
&gt; &gt;&gt; returned value is not related to a specific stream, but rathe=
r a<br>
&gt; &gt;&gt; global.<br>
&gt; &gt;&gt;<br>
&gt; &gt;&gt;<br>
&gt; &gt; Good point, I changed it but because it now returns array (no lin=
ked<br>
&gt; &gt; list),<br>
&gt; &gt; it&#39;s called stream_last_errors(). I also added=C2=A0 stream_c=
lear_errors for<br>
&gt; &gt; explicit clearing which might be useful in some situations.<br>
&gt;<br>
&gt; That both makes sense to me.<br>
&gt;<br>
&gt; &gt; The RFC and the implementation is updated so please take a look!<=
br>
&gt;<br>
...<br>
&gt; 3. For &quot;StreamErrorCode::is*()&quot;<br>
&gt;<br>
&gt; Can error codes fall into multiple categories or is it always a single=
<br>
&gt; one? If it&#39;s guaranteed to be a single category, then perhaps a<br=
>
&gt; `-&gt;getErrorCategory()` method returning a StreamErrorCodeCategory e=
num<br>
&gt; makes more sense and allow for simpler / more efficient code when folk=
s<br>
&gt; are interested in checking for multiple different categories. Instead =
of<br>
&gt; `$code-&gt;isNetworkError() || $code-&gt;isFileSystemError()` they can=
 do<br>
&gt; `\in_array($code-&gt;getErrorCategory(),<br>
&gt; [StreamErrorCodeCategory::NetworkError,<br>
&gt; StreamErrorCodeCategory::FileSystemError], true)` or use a `match()`<b=
r>
<br>
These points actually are on the spot about what I&#39;ve been trying to<br=
>
raise earlier in this thread, or they demonstrate it nicely.<br>
<br>
Suggesting a getErrorCategory() method or a StreamErrorCodeCategory<br>
enum to make category checks cleaner. That&#39;s a reasonable API<br>
improvement, in the context of what the RFC proposes in the current<br>
state. But it also highlights the underlying design issue: we&#39;re<br>
building a parallel categorization system on top of error codes, when<br>
the type system already provides exactly this, through exception<br>
subclasses, for free. That reminds a bit of the early OO&#39;s time in php<=
br>
when all we did was to wrap the legacy procedural implementation in<br>
dumb OO wrapper, saving, if lucky, user&#39;s keystrokes. That&#39;s not ev=
en<br>
the case here.<br>
<br>
The point is that a stream operation can produce errors of different<br>
categories and therefore the exception &quot;cannot be reasonably<br>
categorised&quot;: this is how exceptions have always worked. One throws<br=
>
the primary exception, the one that caused the operation to fail, and<br>
chain additional context via $previous or attach it as metadata. The<br>
caller catches what they care about:<br>
<br>
catch (StreamNetworkException $e) {...}<br>
<br>
The exception type answers &quot;what do I do about this?&quot; The error c=
hain<br>
answers exactly what happens, where in detail. These are different<br>
questions for different uses, and conflating them is what leads to the<br>
current design where it catches a flat StreamException and then has to<br>
inspect its contents to find out what kind of failure it was.<br>
<br>
getErrorCategory() suggestion would give us<br>
match($e-&gt;getErrors()[0]-&gt;getErrorCategory()) { ... } inside a catch<=
br>
block. That&#39;s essentially reimplementing what catch<br>
(StreamNetworkException $e) already does, except the type system can&#39;t<=
br>
help, static analysis can&#39;t reason about it, and it can&#39;t compose i=
t<br>
with other exception handling in a codebase.<br>
<br>
The current RFC introduces exception syntax without exception<br>
semantics. The isFileSystemError(), isNetworkError() methods, and now<br>
potentially getErrorCategory(). are workarounds for the absence of a<br>
typed hierarchy, not features we should need in the 1st place.<br>
<br></blockquote><div><br></div><div>Thanks for the thorough feedback. Afte=
r some considering I decided not to expose those helpers at this stage. The=
 reason is that the current classification is a bit uncertain and I want to=
 have more final set of error codes before anything like this is introduced=
. The current setup was a bit random and sometimes it could go to multiple =
categories so there are some decisions to be made. Also the is* methods wer=
e not the best design as pointed out and other option should be considered.=
 I&#39;m also not too sure about usefulness of categories. All of this shou=
ld be decided on its own and later.</div><div><br></div><div>=C2=A0</div><b=
lockquote class=3D"gmail_quote" style=3D"margin:0px 0px 0px 0.8ex;border-le=
ft:1px solid rgb(204,204,204);padding-left:1ex">
Since StreamException does not exist in any current PHP version, there<br>
is zero BC cost to making it a proper base class now. It takes more<br>
effort to design such additions correctly, however it would be a<br>
significant improvement in the long run for php&#39;s stream, beyond a<br>
current internal refactoring and long due cleaning :).<br><br></blockquote>=
<div><br></div><div>I don&#39;t see how it takes more effort later. There i=
s also pretty much no BC break even if we went if subclassing exceptions as=
 I noted before. I think actually exactly opposite here. If we rush it and =
use incorrect categories for some errors, it will be a BC break to correct =
so this needs a proper considering and this feature should be added later.<=
/div><div><br></div><div>Kind regards,</div><div><br></div><div>Jakub=C2=A0=
</div></div></div>

--000000000000cca472064e7da368--