PHP 8.5 request_parse_body怎样读取原始请求体

PHP 8.5 的 request_parse_body() 解决的是一个很具体的问题：当请求方法是 PUT、PATCH 等非 POST 方法时，表单字段和上传文件不会像普通 POST 那样自动进入 $_POST 与 $_FILES。这时可以让 PHP 按请求的 Content-Type 解析请求体，再一次性取得两个数组。

官方地址：https://www.php.net/manual/en/function.request-parse-body.php

先记住范围：当前支持 application/x-www-form-urlencoded 和 multipart/form-data。如果发送的是 application/json，仍应读取 php://input，不要把两条路径混成一个函数。

request_parse_body 和 php://input 不是一回事

request_parse_body() 是“按表单协议解析”的入口，特别适合非 POST 请求携带表单字段或文件的场景；php://input 则是“读取原始字节”的入口，适合 JSON、XML 或自定义文本协议。选择哪一个，先看请求的 Content-Type，再看应用是否需要 PHP 帮你拆分字段和文件。

这个区分也解释了为什么直接读取 $_POST 会得到空值：$_POST 的自动填充面向 HTTP POST 方法和两种表单 Content-Type，并不是所有请求体的通用解析器。

按返回数组接收字段和文件

函数返回一个二元数组：下标 0 对应 $_POST 等价的字段数组，下标 1 对应 $_FILES 等价的文件数组。最小写法如下：

这里的 [$fields, $files] 是 PHP 的数组解包写法。若只需要普通字段，也可以写成 $parsed = request_parse_body(); $fields = $parsed[0];，但不要把下标 1 当成另一个字段集合；它表示文件上传结果。

用 options 控制一次请求的解析边界

第二个参数允许针对当前请求覆盖部分 php.ini 限制，包括 max_file_uploads、max_input_vars、max_multipart_body_parts、post_max_size 和 upload_max_filesize。这适合单个接口确实需要更大文件或更多字段的情况，但不应把它当成绕过全局资源治理的开关。

 '10M',
    'upload_max_filesize' => '10M',
];

// 返回结构仍然是字段数组和文件数组，不会因为 options 改变下标含义。
[$fields, $files] = request_parse_body($options);
?>

选项名或选项值不合法时会抛出 ValueError。所以配置应使用手册列出的键，不要把 Nginx、应用框架或自定义字段名直接塞进这个数组。

请求体只能消费一次，空结果不一定是函数失效

请求体是一次性输入。request_parse_body() 会消费请求体，而且不会把内容缓冲到 php://input；如果代码此前已经读取过 php://input，再调用它就可能只能得到空数据。反过来，先调用解析函数后再期待从 php://input 读到同一份内容，也是不可靠的设计。

因此，入口层应先确定协议，再选择一条读取路径：

如果 Content-Type 与请求体不匹配，PHP 会抛出 RequestParseBodyException；如果 options 有非法键或值，则是 ValueError。这两个错误都应在接口边界统一转换为清晰的客户端错误或服务器日志，避免把原始异常直接回显给用户。

怎么快速判断该用哪条路径

• 请求是 PUT 或 PATCH，Content-Type 是两种表单类型之一：用 request_parse_body()。
• 请求包含上传文件：接收返回数组的下标 0 和 1，不要只看字段数组。
• 请求是 JSON、XML 或自定义文本：用 php://input，再按协议解码。
• 解析结果为空：先检查是否已有代码读取过请求体，再检查 Content-Type 和方法。
• 出现异常：区分请求体格式无效的 RequestParseBodyException 与 options 错误的 ValueError。

一句话总结：request_parse_body() 不是“读取任意原始请求体”的新别名，而是 PHP 8.5 中面向表单格式、尤其是非 POST 表单请求的解析入口。把协议判断放在读取之前，并保证一次请求只选择一条消费路径，后续的字段、文件和错误处理就会清楚很多。

相关问题

request_parse_body() 能直接解析 application/json 吗？

不能按当前手册支持范围这样使用。JSON 应通过 php://input 读取原始内容，再调用 JSON 解码函数。

为什么调用 request_parse_body() 后返回空数组？

常见原因是请求体已经被其他代码消费，或者 Content-Type 不是支持的表单类型。先检查读取顺序和请求头。

返回数组的两个下标分别是什么？

下标 0 是表单字段，下标 1 是上传文件，语义对应 $_POST 和 $_FILES。