PHP 怎样为 HTTP 流请求设置超时

用 PHP 的 file_get_contents() 或 fopen() 访问 HTTP 接口时，如果对方迟迟没有返回，默认 socket 超时可能让当前请求等待过久。最小做法是在 stream_context_create() 的 http 选项中加入 timeout，单位是秒，也可以写成小数。

官方手册：https://www.php.net/manual/en/context.http.php

例如把读取超时限制为 3.5 秒：

 [
        'timeout' => 3.5,
    ],
]);

// 把上下文传给流函数，否则上面的 timeout 不会参与本次请求
$body = file_get_contents('https://example.com/health', false, $context);

if ($body === false) {
    // 网络失败、超时或 HTTP 流打开失败都可能得到 false
    throw new RuntimeException('HTTP 流请求失败');
}

echo $body;

这里的关键不是给 file_get_contents() 增加一个名为 timeout 的参数，而是先把选项放到 http 包装器下，再把返回的 context 传进去。

把 timeout 放进 http context

stream_context_create() 接收“包装器 => 选项”的关联数组。HTTP/HTTPS 请求使用的包装器键都是 http，不要因为 URL 写的是 HTTPS 就改成 https。timeout 是读取超时，官方定义为秒数浮点值；没有显式设置时，会使用 PHP 配置中的 default_socket_timeout。

常用字段可以这样理解：

为什么设置后仍然要判断 false

超时只规定等待边界，不会把失败自动转换成异常，也不保证返回内容一定是成功状态。流函数可能返回字符串，也可能返回 false；因此要使用严格比较。若还需要观察 HTTP 状态，可以用 fopen() 得到流，再读取 stream_get_meta_data() 中的 wrapper_data。

 [
        'method' => 'GET',
        'timeout' => 2.0,
        'ignore_errors' => true, // 即使是 4xx/5xx，也尝试读取响应体
    ],
]);

$stream = @fopen('https://example.com/status', 'r', false, $context);
if ($stream === false) {
    throw new RuntimeException('无法打开 HTTP 流，可能是网络错误或超时');
}

// 读取响应体与元数据，便于区分响应和打开失败
$body = stream_get_contents($stream);
$meta = stream_get_meta_data($stream);
fclose($stream); // 使用完毕后释放流资源

if ($body === false) {
    throw new RuntimeException('读取响应体失败');
}

var_dump($meta['wrapper_data'] ?? []);
echo $body;

ignore_errors 的含义是即使收到失败状态码，也尝试取得响应内容；它不等于忽略网络超时，也不等于把 500 当成业务成功。是否接受这个状态，仍然要由代码读取响应头后决定。

POST 请求只需再补 content

如果接口需要 JSON POST，可以在同一个 http context 中指定方法、请求头和内容。超时配置与请求体是不同维度：前者限制读取等待，后者描述发送给服务端的数据。

 'demo'],
    JSON_UNESCAPED_UNICODE | JSON_THROW_ON_ERROR
);

$context = stream_context_create([
    'http' => [
        'method' => 'POST',
        'timeout' => 4.0,
        'header' => [
            'Content-Type: application/json',
            'Content-Length: ' . strlen($payload),
        ],
        'content' => $payload, // 请求体必须放在 http 选项中
    ],
]);

// 使用严格 false 判断，避免把合法的空响应误判成网络异常
$result = file_get_contents('https://example.com/api/items', false, $context);
if ($result === false) {
    throw new RuntimeException('POST 请求失败或读取超时');
}

echo $result;

timeout 不是整个业务流程的总耗时

这个字段解决的是 HTTP 流的读取等待，不应被当成完整业务超时方案。DNS、代理、TLS、服务端处理、重试、后续 JSON 解析和数据库写入，都可能让一次业务调用继续消耗时间。若业务必须有总截止时间，应在应用层记录开始时间、限制重试次数，并为后续步骤分别设置边界。

还要注意三点：

• 不要把 timeout 放在顶层；它必须位于 http 选项之内。
• 不要只判断返回值是否为空；正确判断是 $result === false。
• 需要读取 4xx/5xx 响应体时可以使用 ignore_errors，但仍要依据状态行做业务判断。

常见问题

timeout 可以写小数吗？

可以。它是以秒为单位的浮点数，例如 0.5 或 3.5。具体可用精度仍会受到底层网络环境影响。

HTTPS 要使用 https context 键吗？

不用。HTTP 和 HTTPS 的流请求都使用 http 这一组 HTTP context 选项；HTTPS 专属的证书或加密参数再按 SSL context 规则配置。

超时后能自动重试吗？

不能。timeout 只提供读取时间边界，重试需要由应用代码决定，并且要限制次数、记录原因，避免把慢服务进一步压垮。

因此，PHP HTTP 流请求的最小可靠写法就是：在 http context 中设置 timeout，把 context 传入流函数，严格判断 false，并在需要时读取响应元数据。这样既能控制等待时间，也不会把超时设置误当成完整的请求治理方案。