php 8.6新增curlopt_seekfunction,可在libcurl需要重新定位上传流时,用回调把文件句柄移到指定位置。对于可寻址的本地文件,可把fseek()的成功或失败映射为curl_seekfunc_ok或curl_seekfunc_fail;不能回绕的流应返回curl_seekfunc_cantseek。这解决的是请求体如何重新读取,不会自动保证上传重试安全。

PHP回调接收CurlHandle、偏移量和起点,返回指定状态常量。
使用可定位的文件句柄
示例面向启用ext-curl的PHP 8.6,采用HTTP PUT上传整个本地文件。将地址换成有权限的HTTPS上传端点,先按服务端协议安排认证;示例域名不是可用上传服务。保持证书验证启用,不自动跟随重定向,避免把文件转交到未经确认的目标。
<?php
declare(strict_types=1);
if (!defined('CURLOPT_SEEKFUNCTION')) {
throw new RuntimeException('当前PHP cURL没有回绕回调支持');
}
$file = fopen(__DIR__ . '/payload.bin', 'rb');
if ($file === false) {
throw new RuntimeException('无法打开上传文件');
}
$ch = curl_init('https://upload.example.com/files/payload.bin');
if ($ch === false) {
fclose($file);
throw new RuntimeException('无法创建cURL句柄');
}
try {
$stat = fstat($file);
if ($stat === false || !stream_get_meta_data($file)['seekable']) {
throw new RuntimeException('需要大小已知且可寻址的文件');
}
if (!curl_setopt_array($ch, [
CURLOPT_UPLOAD => true,
CURLOPT_INFILE => $file,
CURLOPT_INFILESIZE => $stat['size'],
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_CONNECTTIMEOUT => 10,
CURLOPT_TIMEOUT => 120,
CURLOPT_SEEKFUNCTION => static function (
CurlHandle $handle, int $offset, int $origin
) use ($file): int {
return fseek($file, $offset, $origin) === 0
? CURL_SEEKFUNC_OK : CURL_SEEKFUNC_FAIL;
},
])) {
throw new RuntimeException('设置上传选项失败');
}
$response = curl_exec($ch);
if ($response === false) {
throw new RuntimeException(curl_error($ch));
}
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
if ($status < 200 || $status >= 300) {
throw new RuntimeException('上传端点返回HTTP ' . $status);
}
echo $response;
} finally {
fclose($file);
}
libcurl的C层示例用于解释返回码;PHP层参数签名以PHP手册为准。
不要把三种回调结果混为成功
OK表示已完成请求的位置移动;FAIL表示无法完成并使传输失败;CANTSEEK告诉libcurl不能定位,它可以尝试其他处理办法。管道、实时输入或一次性生成器通常无法像文件那样任意回绕,不能只返回OK来绕过错误。文件在传输期间也不应被其他进程改写。
使用官方Model Context Protocol PHP SDK将PHP应用程序功能暴露为MCP工具、资源和提示,用于代理工作流。
按接口语义验证重新发送
重定向、多轮认证或复用连接重试可能触发定位需求,但是否发生取决于协议和请求过程。测试时应在受控端点观察回调收到的偏移量及最终文件摘要,并按接口要求使用幂等键或覆盖语义。即使客户端收到网络错误,服务端也可能已经保存文件,不应无条件重新创建资源。迁移页旁边的size_delivered要求libcurl 8.20或更高版本,这个条件针对该统计项,不应直接套到回绕回调上。


















