PAYATHON 2026

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 等检查仍按各自职责保留。

备注:内容仅供参考。