Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:130171
Precedence: list
MIME-Version: 1.0
References: <CAEKnhAEO8w0GJXTVyH_nwK8nGQGdJcNNkGOPMnYDVrcsNGrm4A@mail.gmail.com>
 <CAEKnhAGCxHOTOmtU7c8rqm3MY8a4vvoJ3NH7BdR0SNp+7sFWHg@mail.gmail.com>
In-Reply-To: <CAEKnhAGCxHOTOmtU7c8rqm3MY8a4vvoJ3NH7BdR0SNp+7sFWHg@mail.gmail.com>
Date: Wed, 25 Feb 2026 19:11:14 +0100
Message-ID: <CAOWwgpk5wpyWo-qeVO4mGwKygTMFMeXDt3_1Cf4wLOK4ZgZaSw@mail.gmail.com>
Subject: Re: [PHP-DEV] Re: [RFC] Stream Error Handling Improvements
To: Jakub Zelenka <bukka@php.net>
Cc: PHP internals list <internals@lists.php.net>
Content-Type: multipart/alternative; boundary="000000000000a1524f064ba9eeeb"
From: nicolas.grekas+php@gmail.com (Nicolas Grekas)

--000000000000a1524f064ba9eeeb
Content-Type: text/plain; charset="UTF-8"
Content-Transfer-Encoding: quoted-printable

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 Tec=
h
>> 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 =E2=80=94 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

--000000000000a1524f064ba9eeeb
Content-Type: text/html; charset="UTF-8"
Content-Transfer-Encoding: quoted-printable

<div dir=3D"ltr"><div>Hi Jakub,</div><br><div class=3D"gmail_quote gmail_qu=
ote_container"><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"><div dir=
=3D"ltr"><div class=3D"gmail_quote"><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">I would like to introduce a new stream error ha=
ndling RFC that is part of my stream evolution work (PHP Foundation project=
 funded by Sovereign Tech Fund) :<br><br><a href=3D"https://wiki.php.net/rf=
c/stream_errors" target=3D"_blank">https://wiki.php.net/rfc/stream_errors</=
a><br><div><br></div></div></blockquote><div><br></div><div>As there has no=
t 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) mo=
rning unless some changes are required ofc.</div></div></div></blockquote><=
div><br></div><div>Thanks for the reminder! I discussed this with others an=
d we raised the following points:</div><div><br></div><div>1. StreamErrorCo=
de::None: do we need it?<br><br>Having an enum case representing &quot;no e=
rror&quot; feels a bit off to me. If an API needs to express the absence of=
 an error, would,&#39;t StreamErrorCode|null be more idiomatic? StreamError=
Code::None seems like a nullable value disguised as an enum case, and it me=
ans callers always have to guard against it, which somewhat defeats the pur=
pose of using an enum. Am I missing a use case where ::None is genuinely ne=
eded?<br><br>2. StreamError::$next =E2=80=94 is the naming intentional?<br>=
<br>Since stream_get_last_error() returns the most recent error and the cha=
in travels backwards through time, $next seems to point to the previous err=
or chronologically. Would something like $previous (echoing Throwable::getP=
revious()) work better, or is the current naming deliberate?<br><br>3. Shou=
ld StreamErrorCode really be an enum?<br><br>The RFC lists in its &quot;Fut=
ure Scope&quot; section: &quot;Extension-specific error ranges - Reserved r=
anges for extensions to define custom error codes.&quot;<br><br>This gave u=
s pause. Enums in PHP are intentionally a closed, finite type: their value =
is precisely that &quot;invalid states become unrepresentable.&quot; If ext=
ensions can define custom error codes at runtime, the set of possible value=
s would depend on which extensions are installed, and the type would no lon=
ger be truly enumerable.<br>Larry touches on this exact tension in this pos=
t: when the value space needs to be open or user-extensible, an enum is the=
 wrong tool.</div><div><a href=3D"https://www.garfieldtech.com/blog/on-the-=
use-of-enums#open-type">https://www.garfieldtech.com/blog/on-the-use-of-enu=
ms#open-type</a><br><br>I&#39;d also expect the built-in list of codes to k=
eep growing over time as more wrappers and edge cases are covered; which is=
 another hint the domain may not be fixed.<br><br>Would a set of integer co=
nstants (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 exh=
austiveness.<br><br>4. Using stream_context_set_default to change error_mod=
e looks hazardous<br><br>The RFC includes an example where stream_context_s=
et_default is used to set error_mode to StreamErrorMode::Exception globally=
. I&#39;m worried about the ecosystem impact here: if any library or applic=
ation bootstrap does use this,=C2=A0then existing packages using the common=
 @file_get_contents(&#39;maybe_existing_file&#39;) idiom could e.g. suddenl=
y throw uncaught exceptions, breaking behavior their authors had deliberate=
ly chosen. This feels like a significant compatibility hazard for code that=
 doesn&#39;t control its full execution environment.<br><br>Would it be wor=
th 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?=
<br><br>Thanks for working on this, we definitely need this!<br></div><div>=
<br></div><div>Cheers,</div><div>Nicolas</div></div></div>

--000000000000a1524f064ba9eeeb--