PHP 8.6 的 Stream 错误模型：用 error_mode 把 warning 变成 StreamException
PHP 的流操作过去报错方式不统一：同一个失败，可能得到 warning、notice、false 返回值，或者只得到一个没有上下文的空结果。PHP 8.6 给 streams 加了一套统一的错误 API，由 StreamError、StreamException 类，StreamErrorStore、StreamErrorMode、StreamErrorCode 枚举，以及 stream_last_errors()、stream_clear_errors() 两个函数组成，通过 stream context 中的 error_mode、error_store、error_handler 三个选项控制。
项目与规范：php-src，RFC: Stream Error Handling Improvements。
三种 error_mode
StreamErrorMode::Error：保持原样，走普通的 PHP warning 和 notice。StreamErrorMode::Exception：终止性错误抛出StreamException。StreamErrorMode::Silent：抑制错误输出。
$context = stream_context_create([
'stream' => ['error_mode' => StreamErrorMode::Exception],
]);
try {
$stream = fopen('/nonexistent/file.txt', 'r', false, $context);
} catch (StreamException $e) {
foreach ($e->getErrors() as $error) {
echo $error->code->name . ': ' . $error->message;
}
}
注意这个开关必须显式挂在传给单次调用的 context 上。它不能通过默认 stream context 全局生效——这是有意的设计，下面单独说。
结构化错误：error_store 与 stream_last_errors()
打开 error_store 后，最近一次流操作的错误会以 StreamError 对象的形式保留下来，即使当前是 Silent 模式也能读到：
$context = stream_context_create([
'stream' => [
'error_mode' => StreamErrorMode::Silent,
'error_store' => true,
],
]);
$body = file_get_contents('https://example.com/api', false, $context);
if ($body === false) {
foreach (stream_last_errors() as $error) {
error_log($error->code->name . ': ' . $error->message);
}
}
stream_clear_errors();
stream_clear_errors() 负责清空存储，避免读到上一次残留的错误。这套组合适合包在重试逻辑或 HTTP 客户端封装里，替代过去「@ + 返回值 + error_get_last()」的写法。
StreamErrorCode：50 多个语义错误码
RFC 在 StreamErrorCode 枚举里定义了 50 多个语义错误码，不再是笼统的「打开失败」，而是能区分具体原因。上游代码因此可以按 $error->code 做分支判断，而不是靠匹配 warning 文本。
自定义 error_handler
不想抛异常、也不想读存储时，可以挂一个回调，错误产生时直接交给你：
$context = stream_context_create([
'stream' => [
'error_mode' => StreamErrorMode::Silent,
'error_handler' => function (StreamError $error) {
error_log($error->code->name . ': ' . $error->message);
},
],
]);
php://filter 的链长限制
同一版本还加了 filter.max_filter_count context 选项，用于 php://filter URL。设置后，如果该 URL 添加的过滤器数量超过配置值，打开流会失败并给出 warning；负值则关闭这项校验。
$context = stream_context_create([
'filter' => ['max_filter_count' => 3],
]);
// 过滤器链超过 3 个时，这里会失败
$fp = fopen('php://filter/read=string.toupper|string.rot13|string.strip_tags/resource=file.txt', 'r', false, $context);
对接受外部可控 filter 链的代码来说，这是防止过滤器堆叠拖垮进程的一道限制。
实践取舍
值得改造的：自己维护的 I/O 封装层，尤其是那些已经用 @ 静默 + error_get_last() 猜原因的地方。改成 Exception 模式后，错误码是结构化的，catch 里能直接判断是权限、路径还是网络问题，日志也更干净。上传下载、图片处理、模板缓存这类失败路径本来就少的模块，改造收益明显。
别动的：大量遗留的 fopen/file_get_contents 调用，以及那些靠 PHP warning 触发自身 error handler（比如把 warning 转成 ErrorException 的框架）的代码。默认行为没变，这些代码零迁移成本；强行切到异常模式，反而会让没人 catch 的 StreamException 变成致命错误。
为什么「全局生效」被故意排除：如果允许在默认 stream context 上设置 error_mode，等于让一次配置改变整个应用内所有第三方库和依赖的流错误语义。那些库假定拿到的是 warning 或 false，异常会穿透它们的错误处理边界。把开关限制在显式 context 上，意味着每一处行为变更都是调用方自己选择的，升级 PHP 8.6 不会悄悄改变既有应用的运行时行为。