stream_context_create 怎样设置 HTTP 超时

我在 PHP 里用 file_get_contents() 访问一个偶尔响应很慢的 HTTP 接口时，最容易踩的坑不是函数不会调用，而是把超时写错位置，或者把“读超时”和“HTTP 返回 500”混成一件事。stream_context_create() 的正确用法是把 timeout 放进 http 上下文，再把返回值、响应头和错误日志分开判断。

最小可用配置就是 ['http' => ['timeout' => 5.0]]，但上线前还要明确错误日志、重定向次数和响应体大小。

我先把 timeout 放进 http 上下文

stream_context_create() 接收“包装器名 → 选项”的嵌套数组。HTTP 和 HTTPS 都由 http 这一层描述；不要把它写成 https，否则配置不会按预期生效。下面这个例子只演示一次 GET，代码里的超时值是示例，不代表所有接口都适合 5 秒。

 [
        'method' => 'GET',
        'timeout' => 5.0,
        'max_redirects' => 3,
        'ignore_errors' => true,
    ],
]);

// 传入上下文资源；读取失败时保留 false，便于后面严格判断。
$body = file_get_contents('https://api.example.test/health', false, $context);
if ($body === false) {
    error_log('HTTP stream read failed');
    exit;
}
echo $body;

官方手册将 timeout 定义为读取超时，类型是浮点秒数；不设置时会使用 PHP 配置里的 default_socket_timeout。因此 0.5 与 5 表示不同的等待边界，不能把毫秒数直接填进去。

超时、网络失败和 HTTP 错误要分开看

超时通常表现为读取失败并产生告警，file_get_contents() 返回 false。但服务器返回 404 或 500 时，是否还能拿到响应体取决于 ignore_errors；它不是“忽略所有异常”，而是允许在失败状态码下继续取内容。生产代码应同时记录状态行和耗时，不要只看 body 是否为空。

 [
        'timeout' => 5.0,
        'ignore_errors' => true,
        'max_redirects' => 2,
    ],
]);

// 用错误处理器把本次告警收集到日志，避免吞掉真实原因。
$warning = null;
set_error_handler(function (int $level, string $message) use (&$warning): bool {
    $warning = $message;
    return true;
});
$body = file_get_contents('https://api.example.test/report', false, $context);
restore_error_handler(); // 请求结束后恢复调用方原有的错误处理器。

if ($body === false) {
    error_log($warning ?? 'HTTP stream failed');
} else {
    $statusLine = $http_response_header[0] ?? 'unknown status';
    error_log('HTTP result: ' . $statusLine);
}

我会在这几个边界上停手

第一，timeout 不是完整的连接池或请求级总耗时模型；它解决的是流读取阶段的等待边界。第二，设置了 ignore_errors 后仍要检查状态行，不能因为拿到了字符串就认为接口成功。第三，跟随重定向会引入新的目标，最好给 max_redirects 一个小于默认值的明确上限。第四，大响应不应无条件交给 file_get_contents() 全量装入内存，必要时改用流读取并自行控制长度。

相关问题

timeout 可以写成毫秒吗？

不可以。HTTP 上下文的单位是秒，允许浮点数，例如 0.5 表示半秒。

为什么设置了 ignore_errors 还要检查状态码？

它只决定失败状态码的响应体是否继续读取，不会把 4xx 或 5xx 变成成功。

HTTPS 要把键名改成 https 吗？

这里的上下文选项仍使用 http 层；目标 URL 可以是 HTTPS，具体 TLS 选项另按官方上下文文档配置。

这套写法适合轻量、低并发的 HTTP 读取任务。真正需要连接复用、细粒度连接超时、取消和复杂重试时，应把边界写进更完整的 HTTP 客户端方案，而不是继续堆叠流上下文参数。