PHP 8.4 非 POST 表单解析实战：request_parse_body 的 PUT 文件接收与 10M 边界

后台编辑器把附件上传从 POST 改成 PUT 后，最容易遇到的不是文件权限，而是 PHP 端的 $_POST 和 $_FILES 变成空数组。PHP 8.4 增加的 request_parse_body() 正好处理这个边界：它能按 Content-Type 解析非 POST 请求里的表单字段和文件。

先做一个 PUT 文件接收接口

先准备一个只有两个入口文件的小项目。客户端用 multipart/form-data 发送 title 和 attachment，服务端把文件临时落到 storage/inbox，返回一个 JSON 结果。目录结构保持简单，方便用 curl 复现每个分支。

mkdir -p php-put-upload/storage/inbox
cd php-put-upload
touch upload.php

把下面的代码放入 upload.php。示例没有依赖框架，重点只放在请求体解析、文件边界和错误响应上。

 false, 'message' => '仅接受 PUT'], JSON_UNESCAPED_UNICODE);
    exit;
}

try {
    [$fields, $files] = request_parse_body([
        'post_max_size' => '12M',
        'upload_max_filesize' => '10M',
        'max_input_vars' => 20,
    ]);
} catch (RequestParseBodyException $error) {
    http_response_code(400);
    echo json_encode(['ok' => false, 'message' => '请求体无法解析'], JSON_UNESCAPED_UNICODE);
    exit;
}

$title = trim((string) ($fields['title'] ?? ''));
$file = $files['attachment'] ?? null;

if ($title === '' || !is_array($file)) {
    http_response_code(422);
    echo json_encode(['ok' => false, 'message' => '标题和附件不能为空'], JSON_UNESCAPED_UNICODE);
    exit;
}

if (($file['error'] ?? UPLOAD_ERR_NO_FILE) !== UPLOAD_ERR_OK) {
    http_response_code(422);
    echo json_encode(['ok' => false, 'message' => '附件上传失败'], JSON_UNESCAPED_UNICODE);
    exit;
}

$allowed = ['image/jpeg', 'image/png', 'application/pdf'];
$mime = (new finfo(FILEINFO_MIME_TYPE))->file($file['tmp_name']);
$size = (int) $file['size'];

if ($size > 10 * 1024 * 1024 || !in_array($mime, $allowed, true)) {
    http_response_code(415);
    echo json_encode(['ok' => false, 'message' => '文件类型或大小不符合要求'], JSON_UNESCAPED_UNICODE);
    exit;
}

$target = __DIR__ . '/storage/inbox/' . bin2hex(random_bytes(12));
if (!move_uploaded_file($file['tmp_name'], $target)) {
    http_response_code(500);
    echo json_encode(['ok' => false, 'message' => '文件保存失败'], JSON_UNESCAPED_UNICODE);
    exit;
}

echo json_encode([
    'ok' => true,
    'title' => $title,
    'mime' => $mime,
    'bytes' => $size,
], JSON_UNESCAPED_UNICODE);

这里特意没有使用客户端传来的原始文件名拼接保存路径。文件名只作为展示信息，实际落盘名由服务端随机生成，能够避开路径穿越和同名覆盖。生产项目还应把业务编号、操作者和目标存储键写入数据库。

request_parse_body() 返回的两组数据怎么对应

函数返回一个二元数组，可以直接解构为 [$fields, $files]。字段数组承担普通表单值，文件数组的结构与熟悉的上传超全局变量相近，包含临时路径、错误码、大小和客户端名称等信息。

如果客户端把请求发送成 application/json，这个函数不会把 JSON 当作表单解析。JSON 接口应继续使用 php://input 配合 json_decode()；不要把两条读取链混在同一个请求里。

用 curl 验收成功、空字段和超限三条路径

启动 PHP 内置服务器：

php -S 127.0.0.1:8080 -t .

准备一个测试文件后，先发送成功请求：

printf 'demo attachment\n' > sample.txt
curl -i -X PUT http://127.0.0.1:8080/upload.php \
  -F 'title=月报附件' \
  -F 'attachment=@sample.txt;type=application/pdf'

这个命令会故意把文本文件声明成 PDF，服务端仍然通过 finfo 检查真实 MIME 类型，因此应该返回 415。换成真实的 PNG、JPEG 或 PDF，再观察响应中的 ok、mime 和 bytes。

再验证两个失败分支：

curl -i -X PUT http://127.0.0.1:8080/upload.php -F 'attachment=@sample.txt'
dd if=/dev/zero of=large.bin bs=1m count=11
curl -i -X PUT http://127.0.0.1:8080/upload.php \
  -F 'title=过大文件' \
  -F 'attachment=@large.bin;type=application/octet-stream'

第一条缺少标题，应得到 422；第二条会经过上传限制和业务大小检查。验收时不要只看 HTTP 状态，还要确认 storage/inbox 没有留下失败请求的临时文件。

一次读取和大小限制，最容易踩的四个坑

先读 php://input 再调用解析函数

请求体是一次性输入流。调试中如果先把它读出来记录日志，后面的 request_parse_body() 可能只能拿到空数据。需要记录调试信息时，记录请求头、请求编号和解析结果摘要，不要提前消费原始正文。

把客户端 MIME 当成真实类型

$_FILES 风格的 MIME 字段可能来自客户端声明，不能单独作为白名单依据。示例使用 finfo 对临时文件重新判断，再叠加文件大小和业务后缀策略。

只改局部限制就以为服务器没有上限

函数的 options 可以针对当前解析动作覆盖部分配置，但反向代理、Web 服务器、PHP-FPM 和磁盘仍可能有自己的上限。上传失败时按“客户端 → 代理 → PHP → 业务校验 → 存储”顺序排查。

异常信息直接返回给调用方

RequestParseBodyException 适合记录在服务端日志里，客户端只需要得到稳定的错误类别和重试建议。不要把内部路径、配置值或堆栈直接放进 JSON。

上线前保留一组最小检查

1. 请求方法检查：只允许业务需要的 PUT 或 PATCH。
2. 解析前检查：确认 Content-Type 与客户端约定一致，并确保没有代码提前读取请求体。
3. 字段检查：标题、业务编号和文件字段分别验证，不把空字符串当成有效输入。
4. 文件检查：重新判断 MIME、大小、扩展名和存储位置，拒绝客户端路径。
5. 结果检查：成功和失败都返回稳定 JSON，失败请求不留下可访问的临时文件。

常见问题

PHP 8.3 能直接使用 request_parse_body() 吗？

不能把它当作 PHP 8.3 的内置函数。官方手册将它标记为 PHP 8.4 起可用，旧版本需要继续使用适合请求类型的现有解析方式，或先升级运行时。

request_parse_body() 能解析 JSON 吗？

它的用途是解析表单编码和 multipart 表单，不是通用 JSON 解析器。JSON 请求应读取正文后交给 json_decode()，并保持两套入口的校验规则分开。

为什么 PUT 请求里的 $_FILES 是空的？

PHP 不会像 POST 文件表单那样自动为所有 HTTP 方法填充这两个超全局变量。PHP 8.4 项目可以在没有提前读取正文的前提下调用 request_parse_body() 获得字段和文件数组。

局部设置 upload_max_filesize 后就能上传任意大文件吗？

不能。局部选项只影响这次请求的解析边界，仍需同时检查服务器链路和业务自身的文件大小、类型、存储与权限策略。

把非 POST 表单请求接稳

PHP 8.4 的这个新增函数解决的是一个明确的入口缺口：非 POST 的表单请求也能得到结构化字段和文件数据。真正可靠的上传接口，还要把“一次读取、真实类型、大小边界、随机落盘名和失败清理”一起验收。先用上面的三条 curl 路径跑通，再接入框架控制器或对象存储，定位问题会清楚很多。