PHP MVC 如何拒绝非上传 POST 的 multipart/form-data?
建议使用 route-aware ContentTypeMiddleware:匹配 route 后,从 route 元数据读取是否允许 multipart/form-data,再在调用 controller 前统一检查。普通 route 默认禁止 multipart,唯一的上传 route 显式允许。这样可以覆盖全部 POST handler,也无需维护另一份 URI allowlist。
如果当前 routing 完全封装在 Dispatcher::dispatch() 内,可以在它完成 route 匹配后调用独立的检查组件。Dispatcher 安排执行顺序,Content-Type 策略由检查组件维护。
$_POST 与 multipart 请求
PHP 通常会自动解析合法的 multipart/form-data POST 请求,将普通表单字段放入 $_POST,将上传文件信息放入 $_FILES。这个过程与 controller 是否引用 $_FILES、route 是否用于上传无关。
因此,非上传 handler 收到 multipart 请求时,$_POST 不一定为空。数据为空可能与 boundary 缺失或错误、请求体格式、PHP 配置或大小限制有关,需要检查实际请求才能确定原因。
接受 multipart 本身不足以证明存在上传漏洞。可以将此检查作为接口约束:普通表单端点拒绝不支持的请求格式,返回 415 Unsupported Media Type。
将上传权限写入 route 定义
在现有 route 配置中增加元数据,例如 allows_multipart。只有上传 route 将其设为 true,其余 route 省略该字段,默认值为 false。
以下配置仅作示例,method、pattern、handler 等键名需要适配现有 router:
[
'method' => 'POST',
'pattern' => '#^/admin/posts/upload-image$#',
'handler' => [PostController::class, 'uploadImage'],
'allows_multipart' => true,
]
检查组件读取已匹配的 route 信息,无需自行匹配 URI。query string、路径规范化、regex 匹配和 HTTP method 都由现有 router 处理。上传地址变动时,权限配置也随 route 定义一起变动。
在 route 匹配后执行检查
执行顺序应为:
创建 Request
↓
外层 middleware
↓
匹配 route 和 HTTP method
↓
读取 route 元数据
↓
ContentTypeMiddleware
↓
controller
外层 middleware 可以包含 SecurityHeadersMiddleware、CorsMiddleware 等,让提前返回的 415 响应也能经过相应的响应处理。认证检查放在 Content-Type 检查之前还是之后,应根据现有接口的错误响应约定决定。
如果 routing 已经可以作为独立阶段执行,就将匹配结果写入共享 Request,再进入 ContentTypeMiddleware。如果只有进入 Dispatcher 后才能确定 route,则在 Dispatcher 内匹配 route 之后、实例化或调用 controller 之前执行检查。
仅在提取 $requestMethod 后检查还不够:如果此时尚未匹配 route,就无法可靠识别上传例外。未匹配的路径和不支持的 method 应继续交给现有 routing 逻辑处理。
PHP 7.4+ middleware 示例
下面的实现仅拒绝未获允许的 multipart/form-data POST,不改变 application/json 或其他 Content-Type 的现有处理行为。
示例沿用 handle(callable $next) 签名,假定 pipeline 会逐层返回 Response,入口最终统一发送响应。接入时需要遵循现有 MiddlewareInterface 的响应约定。
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
final class ContentTypeMiddleware implements MiddlewareInterface
{
private Request $request;
public function __construct(Request $request)
{
$this->request = $request;
}
public function handle(callable $next)
{
if ($this->request->getRealMethod() !== 'POST') {
return $next();
}
$contentType = (string) $this->request->headers->get(
'Content-Type',
''
);
$mediaType = strtolower(trim(explode(';', $contentType, 2)[0]));
if ($mediaType !== 'multipart/form-data') {
return $next();
}
if ($this->request->attributes->get('_allows_multipart') === true) {
return $next();
}
return new Response(
'Unsupported Media Type',
Response::HTTP_UNSUPPORTED_MEDIA_TYPE,
['Content-Type' => 'text/plain; charset=UTF-8']
);
}
}
这里使用 getRealMethod() 检查实际 HTTP method,以覆盖实际发送为 POST 的请求。如果应用启用了 HTTP method override,还应明确它与 routing 的配合规则,避免有效 method 的变化使实际 POST 绕过检查。
route 匹配完成后,将对应元数据写入同一个 Request 对象:
$request->attributes->set(
'_allows_multipart',
($matchedRoute['allows_multipart'] ?? false) === true
);
$matchedRoute 代表现有 router 返回的匹配结果,不是 Symfony HttpFoundation 提供的 routing API。不要从 query string 或表单字段读取这个权限值。
如果暂时在 Dispatcher 内接入,且已将后续 controller 调用包装成 callable $invokeController,可以这样调用:
return (new ContentTypeMiddleware($request))->handle($invokeController);
$invokeController 需要按项目现有 dispatch 代码构造。检查失败时应直接返回 Response,不调用它。
为什么要去掉 Content-Type 参数
实际上传请求通常带有 boundary:
Content-Type: multipart/form-data; boundary=example-boundary
直接将整个 header 与 multipart/form-data 比较会漏掉这种正常形式。示例先取分号前的 media type,再去除两端空白并转为小写,因此也能识别大小写不同的表示。
这只是 media type 策略检查,并未完整验证 header 或 multipart 请求体。允许上传的请求仍需要检查 boundary、文件上传错误及其他上传条件。
确保 415 能传回入口
使用 array_reduce 构建 onion-style pipeline 时,外层 middleware 必须返回下层结果:
return $next();
如果某层只调用 $next() 而没有返回,内层生成的 Response 可能丢失。入口收到最终 Response 后再统一发送;其他会给响应添加 header 的 middleware 也应遵循这个约定。
如果现有项目采用直接输出响应的方式,需要按其约定适配错误返回,不能仅复制 new Response() 就假定客户端能够收到 415。
三种方案如何取舍
| 方案 | 覆盖与维护情况 | 建议 |
|---|---|---|
| middleware 硬编码上传 URI allowlist | 需要同步维护 routing 和例外列表,路径处理可能出现差异 | 可作为临时方案 |
| 扩展 isMethodPost() | 会遗漏未调用该方法的约 30 个 handler | 不适合作为统一入口 |
| route 元数据配合统一检查 | 所有经统一 dispatch 的 POST handler 都能覆盖,上传例外随 route 维护 | 推荐 |
当前项目不必为了这项检查先重构全部 controller。可以先让 Dispatcher 在匹配 route 后调用独立组件,再按需要将 routing 拆为独立阶段。
JSON 与严格 allowlist 要分开考虑
上述代码仅禁止未获允许的 multipart/form-data,因此 cart、navigation reorder 等端点的 application/json 请求能够通过这项检查。通过检查只代表请求没有被此策略拒绝,后续解析、认证和业务校验仍按原有逻辑执行。
如果后续需要拒绝所有非预期的 Content-Type,可以将元数据扩展为 accepted_media_types,并按 route 声明:
- 普通表单 route 接受 application/x-www-form-urlencoded。
- JSON route 接受 application/json。
- 上传 route 接受 multipart/form-data。
不要将所有 POST route 一律限制为 application/x-www-form-urlencoded,否则会影响现有 JSON 客户端。扩大策略前,还应明确如何处理缺失、空值以及格式错误的 Content-Type。
验证范围与实际限制
至少验证以下情况,并确认请求被拒绝时 controller 没有执行:
| 请求 | Content-Type | 此检查的预期结果 |
|---|---|---|
| POST /login-submit | multipart/form-data; boundary=example | 415 |
| POST /login-submit | Multipart/Form-Data; boundary=example | 415 |
| POST /login-submit | application/x-www-form-urlencoded | 通过检查 |
| POST /admin/posts/upload-image | multipart/form-data; boundary=example | 通过检查 |
| POST /admin/posts/upload-image?test=1 | multipart/form-data; boundary=example | 匹配上传 route 后通过检查 |
| 已有 JSON POST route | application/json; charset=UTF-8 | 通过检查 |
还应验证外层 middleware 是否保留了 415 状态码,以及错误响应是否带有所需的 CORS 和安全响应 header。这些是建议的验证项目,不代表已经运行过测试。
应用 middleware 能在 controller 执行前拒绝请求,但在通常的 PHP 自动解析配置下,multipart 请求体可能已经由 PHP 解析,上传临时文件也可能已经创建。因此,这项检查不能承诺消除上传解析或临时文件的资源开销。如果需要在 PHP 解析前阻断,应在反向代理或 Web server 层配合请求限制;文件大小、上传权限和 CSRF 等检查仍按各自职责保留。
备注:内容仅供参考。
