Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:129291
Message-ID:
 <AM8P250MB0170998214C5628937E7AAF7E2D7A@AM8P250MB0170.EURP250.PROD.OUTLOOK.COM>
Date: Wed, 19 Nov 2025 06:14:18 +0100
User-Agent: Mozilla Thunderbird
Subject: Re: [PHP-DEV] [RFC] Stream Error Handling Improvements
To: Jakub Zelenka <bukka@php.net>,
 PHP internals list <internals@lists.php.net>
References: <CAEKnhAEO8w0GJXTVyH_nwK8nGQGdJcNNkGOPMnYDVrcsNGrm4A@mail.gmail.com>
Content-Language: en-US
In-Reply-To: <CAEKnhAEO8w0GJXTVyH_nwK8nGQGdJcNNkGOPMnYDVrcsNGrm4A@mail.gmail.com>
Content-Type: text/plain; charset=UTF-8; format=flowed
Content-Transfer-Encoding: 7bit
Precedence: list
MIME-Version: 1.0
X-MS-Exchange-MessageSentRepresentingType: 1
X-MS-PublicTrafficType: Email
X-MS-TrafficTypeDiagnostic: AM8P250MB0170:EE_|DU7PPFD5367DB8B:EE_
X-MS-Office365-Filtering-Correlation-Id: a165b109-99b2-498f-abcb-08de272a7f90
X-MS-Exchange-SLBlob-MailProps:
	YfhX3sd/0TWnHr2aTc7oye/bilYJDP7y6Pkr6c0lmQZEiboxDpYWrU/NhOoJwLAzMPwmwtHOEtIRd9RJClWZZSQiqT//oIY/fdV79BWzkJrCIAFf0xvQBpTLqE7l2valjVqD8DnJIhcxMQrj+zw+TvidsdnzYBjYqO4RQdfv9EgDiD+7eXQlrceK/dIaN+DH+2G87CcHSf9vRtnmCvvQnS5m67P8GPt0F/IY6zjb0hz8tuLU1X9qXjdYw4XRawhF79zh2YeEAmfeVavqaMK33r9q0bQJ3ufgt4R7vqIyyDhDBxgepkdf/VASFj7QoWYnd3/MsB8X3O9K5BSCm7FGRwCK8fk71TGRHie95VXDPKTlFfhD08X4LOrgTlswNKcga3Y676fE3/O+Vp7OO2mhNWMFjOnvyP6iZRCca+f/PWBBWW1sgu53RPnBHotHCFoAwAOHbdgRxgltPXe1vDf9jidvk+Bo3EGlnyPHHtofL7wyz2jcNEMuPjgeIcrWmCi8hOK9ULrOfj8exTVx3ZDzOXWiBLK3JmMW1c6SEZHBLzfGzskPgLtn4qGwlEipBkbWtGE13I8/Q031O5P9xjmkFtjByVR7oWqpAUSlaslNirhGYX8sIgNAE2K8DN4gcranMHjmiWzGHkVt9tI2WQz03t0fyJphCrcJbd/IlTVcfbW+swzrLJfnoQe6EJW4/3d8Mq6i0Sx0ghR2LcUGX89ciUZRqUNXkGrruSjOWMDJIW8KydbEz99XC2nF9a0G06+FpBunz5B5KXTUn7NOGMFZVMexP8Fj3PFAQ82Nls+4SX4=
X-Microsoft-Antispam:
	BCL:0;ARA:14566002|461199028|6090799003|12121999013|19110799012|15080799012|23021999003|8060799015|41001999006|51005399006|5072599009|440099028|26104999006|3412199025|4302099013|40105399003|10035399007|1602099012;
X-Microsoft-Antispam-Message-Info:
	=?utf-8?B?cHFUcE5kUmYxTzhydWg3djJiMmthVUdIZ0UzclpxbXUvTlgvdHlQeC9lUkN1?=
 =?utf-8?B?dEp5SEJ4aEpRbjg2WVhqQ05tVGprZHNRUmdnb2JaNDUvWC8yZDRSQ0FNK0Fr?=
 =?utf-8?B?eWhjemxobXNNTnlFdnFlK2JnOGhlSTVpSXR5MzdNQ3pIWFJoRk5FcUxGL21l?=
 =?utf-8?B?RUlsaCt2ZGtOc2pHVFpWRS9ZSkM0aWhkTVN2czlxT3dRZWpEQmI1TmIrNDE3?=
 =?utf-8?B?TDhLT1gzaThYdmY0WmpRSW1vZjlZOVdwL2RHOTRhUW5Wam9qdGR6ellZdExu?=
 =?utf-8?B?ZEorUDFkZ29jSUNKV3NXZ28rQnRpWnI0aFl0VGNjOTdQL2Z5ckNTaGZzSmNB?=
 =?utf-8?B?YjhaQmUvQ2s3RGdFTi9oeGpScXk5U01YbFh5VTMrUU1jNi8vK3NoNUgwcGRD?=
 =?utf-8?B?eDVPSWxYVytWNUlZWGtXR2dNbCthdE5zT25tM2VVajJwTE5IVm1TbXMzSjlB?=
 =?utf-8?B?M0Y4KzJ6cmtZUGt3R0YweTdpUytVRk5YNk81YWN4eE81TzJjb3Qyd1pYRE4x?=
 =?utf-8?B?N0xGY3pKajZTQnBwRDBXRk0rdHljUmZ2d2JvdnIwbi9vb1BxU0NveGxUL3Yz?=
 =?utf-8?B?TlpNS21ZS0lQcEtyOW5ZR24waEVEWmt1RGd3N1dZWUdlUmk0Tk5FR0RzY2tU?=
 =?utf-8?B?UUplZkd1U2hSVHNOVmppZTZ2K1RlMUZkYjVMOHd2d2R6S0kxQ25HWHhKRENQ?=
 =?utf-8?B?UkNCNUZITHd3RGF5Z0tVak83M0tXYWZzTFNhVFpIbG9UWXNSem12cVhjNHgv?=
 =?utf-8?B?OUJMajVhMURhcTQrcWg1eWtNSlFqN0dxWGxxREJNYlJJWHlLODR1ZGw5WWI1?=
 =?utf-8?B?VU91WUt0ZmVOUS9jbGVZN0c5N0lHUkNOYXhEbmQzZytiTThobWZCbzU1NW90?=
 =?utf-8?B?cGZ4Yy90dFNMOEltdzNsZ3kzZ1VKR0NEU2N3ODBUazYrSnIxK1F2dmNFa1p2?=
 =?utf-8?B?bnFsVW11ZVZvbUlFZGNLN3hDcDNiamRJRTNLL3RDMGVXZGpkdTFDdktKU0JT?=
 =?utf-8?B?VjdZZ20rUElxSWpOa2NQV2ZvZFE5NTVqUE1KYTBPUVFYZlFxdGdYU25UVUsx?=
 =?utf-8?B?N1hLcjNOQ2x4RTNZWEhXeEFuKzlFdDlNUGVMVnl6SS9EenVzdFM2cVltWEFR?=
 =?utf-8?B?dm5HVHFLQTV2dENOcTFobFVvL1dDZGp1eGtUa1llMlN0YU1WK3UwTFJjN1hH?=
 =?utf-8?B?dWw3TTNxNjQrRHJhR2VrTHl4NHdvR3NvMkxtZEZXbUdUZnNEQVpta0pFakJQ?=
 =?utf-8?B?eGVxU3UxNVZOWS9SR3lvdFVicnVFcXFuN1drS1lUN2ZUdEVZNERNTFp0WTRk?=
 =?utf-8?B?N1pwTkhiSFMxZHZsVWVqamROcjdmQWc1dVVucDhWRnhRbHJ0K1VxQWV0elUw?=
 =?utf-8?B?UGtiV3k1TTFpTWgyTVdLTnBJMFcvM0hTS3VUODFoTVNNUWt5cHgrdGIrbFZG?=
 =?utf-8?B?U2I5TDFYVmI3SElaY2NkaDltUEZTNDVJOFcrZHBkNERLcURXdzNyYkNEdGZs?=
 =?utf-8?B?ckJXa1o0YSt5cXViV1dzbVUvNFF1cUdkYW5sZG5MQWxnOWozdVRGcVRNQmdR?=
 =?utf-8?B?T041aWRuc0xpbytlbHBpRXNhZmZ3ZlBVdnZOYmozVm50VTF0KzhWVWpBa2ll?=
 =?utf-8?B?b0xuQjJCRmhxclhQNUluZ0dOdzFNMmc3VWpTWi93NVZsZnZMeHR5UXFrVmU3?=
 =?utf-8?B?ZHBqK3VkaVJpUVc1VFY5UGdNRjFUdEFjS0RGM211eTVsTUdzT3VUQUdUVUt6?=
 =?utf-8?B?dWxGSFFmK3BoNS9HMXZrcUpzTEhWWVpZQlVzWGZDY1B5aklrUHhSYXNUKzRK?=
 =?utf-8?B?TlFDdHY1R3J6ZjBobHdkM3QrcElpVkJ6TlYvRmoydnZ1WnhubzhEVkhpVmw0?=
 =?utf-8?B?YW9UL1dGcGR0WXdtRnNVWFdYdk4wVnlLSVQyLzZUL3JjMjc3NHNwZm9sYkY3?=
 =?utf-8?Q?7mEa/0PDWJLPkXItMQjkTlPFRup57fui?=
X-MS-Exchange-AntiSpam-MessageData-ChunkCount: 1
X-MS-Exchange-AntiSpam-MessageData-0:
	=?utf-8?B?Z2VXdkh4Mi8rcGtzMXY2TjhCanM3TXdjbFVIU3Flb2NQY0hlbDEzamNISXd3?=
 =?utf-8?B?NkNIczJkZEcxR0wxVzZaRzFKZlcwOVFpbUNHKzIyRGxFU3E5eUJ1TEhmckhl?=
 =?utf-8?B?VGRMSE9IVWM3VjI2OTlDYkNqR215dzk3cnc1OS9GaWxTOGZ2MWhzOHcxUEFM?=
 =?utf-8?B?bDhCY1pMaytkSE5IVW5aUjRDK0k3NjhOK3VZUW93VTVLQm5NV2VWWGtzZ2VN?=
 =?utf-8?B?aDlpU25IRis1eTRLM0xEaHpacUtoWk5CVDZqTC9tL2dpbzlVbUhvb21rT1lE?=
 =?utf-8?B?SU9RbFRCOVpTUmJrTTFuWk5WYld2VUtiQTduNGFkMzdZWVZHZEtlaHpJT05W?=
 =?utf-8?B?SUllTVNncjFnWnRLWjNZak9qQk42QlhSeGRuYkJHclVZTGN5Mk1jT2xOakFk?=
 =?utf-8?B?bEMzb0t0U0JWcFJwOXUyQXcwOVEveWRia2tlZzRmK1Mvd0M3SVBZRk9JQ0lY?=
 =?utf-8?B?UWc1bm5Kd1JUdWtBVzU1VVZuWDhXYVpVZTRIQTZ6TzllS3ltMG91dTgzQlMx?=
 =?utf-8?B?VXpZMktwUU05ZmFsenFLaGZVZHZFVFRBaXNsMVViMnRGMGdYZVNjTk1Sc1V4?=
 =?utf-8?B?b2RkL253YVUwVDVmQ2hUN3NRdXVLUURJcnl5SkxDUDM5dXRuc1BvSDlnc3pJ?=
 =?utf-8?B?T1JUS1NxVm5meitQdHBTejJKT1dIbGJMdGl4RVBZemhCMTk1R3FVWDJIcDR5?=
 =?utf-8?B?SmJpWXQwK21GTG1DNXB1dTErLzdzT2txY2hKZFd4bHFFN040dllPODBZOGFt?=
 =?utf-8?B?S1dMbVgzRjFKL001VC9mTUlkd2wza1YwK3RQSzFVaWZiZTBQOGdSYUxVNkxE?=
 =?utf-8?B?WGxHMWdQdU40a1BpSW9EK1MycXhrRGtiMzZoT3FEd1Q4UU5wOWxjQ2hYRk55?=
 =?utf-8?B?V2RJVkd3ZFBFT2I0b1ErTWxBVCtOQ245UlFEcTBMcFhSdHBzTllSUElFNEh0?=
 =?utf-8?B?d082Qlg5c21TbDYvQVZGSHZZR3BSREV4cWpHQkVhYjFxamhiSUpqL2RmTFhi?=
 =?utf-8?B?RVpHNGpBM2NkSjBRZVovYXU4YUwrTGFSSStydm5Pa3lvb2FxU0RlM04xSzIr?=
 =?utf-8?B?N1Q2UDh3RjJacHQ4RzB3QUE2TGxpS050elJScklZVW01Qjl5NExkWjJkZndH?=
 =?utf-8?B?ZkI3T3g2WWtEei9NUEZxMmxHWDYvR2NrVGFUemhPanhtQXRRODh1ek1DRmd0?=
 =?utf-8?B?bVV1Rld0RlVCdCtUOFBEODJnWXNXS0xuZm8rSkJ6NXZidFpJMnIwRjJTSEIy?=
 =?utf-8?B?RmNUSkI0dlN0RTAxVmhXZmY1ektmcmdkd2lTUTBhK3RxZ0doVUxOQ3dNT3py?=
 =?utf-8?B?NG5uR3prVEJzYTlyaDBhc0swMGVxd1A3ZzdXQzczSHdTdDBaOXpSK09VZUZZ?=
 =?utf-8?B?Q2dEVUFuOHBDeC8veThnQ1lQR1FDZUFydGpmQ0MvRyt6aW1BRjhybTZBSjYy?=
 =?utf-8?B?M21DLzFsZHBTK0Y4ellXd2ZaaS9pUjVwQkRTNTZkN0xYVWxQQU96WXpTVnJJ?=
 =?utf-8?B?VTJNTW45K0NJR3lEN2M3N1dJU056OXFTYzNnZVh0Z0ljWVNVMjZxOFJjT2hZ?=
 =?utf-8?B?Nk1TNzlVT3lZV0dhdjFtZWNJL1B4NmhGYjNscXpLVS9OTGJtaHJJaUQ3bHdp?=
 =?utf-8?B?cnhSYlNhaXI0NHV1QWJRU1RNa3lucHBGMUdMd3FrTllnQXFZSUhad3gvN200?=
 =?utf-8?B?NlhtaktxT0l3anFQZXdOMU0xck9FTlpRdWt2b2E3YWpGOU5GSWhweTVROWtS?=
 =?utf-8?Q?Lj7+igOGA34Y9cahg8=3D?=
X-OriginatorOrg: sct-15-20-8534-15-msonline-outlook-5f066.templateTenant
X-MS-Exchange-CrossTenant-Network-Message-Id: a165b109-99b2-498f-abcb-08de272a7f90
X-MS-Exchange-CrossTenant-AuthSource: AM8P250MB0170.EURP250.PROD.OUTLOOK.COM
X-MS-Exchange-CrossTenant-AuthAs: Internal
X-MS-Exchange-CrossTenant-OriginalArrivalTime: 19 Nov 2025 05:14:22.1093
 (UTC)
X-MS-Exchange-CrossTenant-FromEntityHeader: Hosted
X-MS-Exchange-CrossTenant-Id: 84df9e7f-e9f6-40af-b435-aaaaaaaaaaaa
X-MS-Exchange-CrossTenant-RMS-PersistedConsumerOrg:
	00000000-0000-0000-0000-000000000000
X-MS-Exchange-Transport-CrossTenantHeadersStamped: DU7PPFD5367DB8B
From: bobwei9@hotmail.com (Bob Weinand)

Hey Jakub,

On 18.11.2025 19:38:37, Jakub Zelenka 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


I super appreciate that you've tackled this. This has been a big wart in 
PHP's stream handling for a long time.


I have a couple questions:

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.

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.

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.

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?

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.
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.

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.
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.

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.

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.


Overall, I like the direction of the RFC, but I'd like to see improved 
handling for "terminal error inside non-terminal operation having its 
own error" in particular. Enums are rather a suggestion, not a 
requirement, but they would be in my opinion very fitting here.


Thanks,

Bob