PHP表单数据处理专家

代码实现

<?php
declare(strict_types=1);

/**
 * 安全获取并验证 GET 数组参数：keywords
 * 要求：
 * - 请求方法：GET
 * - 参数名称：keywords
 * - 数据类型：数组（例如：?keywords[]=foo&keywords[]=bar）
 * - 验证要求：基础验证（数量、长度、字符集）
 *
 * 返回：JSON
 * - 成功：{ success: true, data: { keywords: [ ... ] }, meta: { count: n } }
 * - 失败：{ success: false, errors: [ ... ] }
 *
 * 注意：本示例仅处理参数获取与验证，不包含业务查询逻辑。
 */

header('Content-Type: application/json; charset=utf-8');

const MAX_KEYWORDS      = 10;   // 最多关键词数量
const MAX_KEYWORD_LEN   = 64;   // 单个关键词最大长度（按字符计）
const ALLOWED_PATTERN   = '/^[\p{L}\p{N}\s\-_]+$/u'; // 允许：字母、数字、空格、连字符、下划线（支持多语言）

/**
 * 统一 JSON 响应
 */
function respond(array $body, int $status = 200, array $headers = []): void
{
    http_response_code($status);
    foreach ($headers as $name => $value) {
        header($name . ': ' . $value, true);
    }
    echo json_encode($body, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES);
    exit;
}

/**
 * 异常：参数校验失败
 */
final class ValidationException extends RuntimeException
{
    /** @var array<int|string, mixed> */
    private array $errors;

    /**
     * @param array<int|string, mixed> $errors
     */
    public function __construct(array $errors, string $message = 'Validation failed', int $code = 422)
    {
        parent::__construct($message, $code);
        $this->errors = $errors;
    }

    /**
     * @return array<int|string, mixed>
     */
    public function getErrors(): array
    {
        return $this->errors;
    }
}

/**
 * 多字节长度安全函数
 */
function mb_len(string $str): int
{
    return function_exists('mb_strlen') ? mb_strlen($str, 'UTF-8') : strlen($str);
}

/**
 * 关键词规范化：
 * - 去首尾空白
 * - 合并连续空白为单个空格
 */
function normalize_keyword(string $keyword): string
{
    $keyword = trim($keyword);
    // 合并任意空白字符为一个空格（支持多字节）
    $keyword = preg_replace('/\s+/u', ' ', $keyword) ?? $keyword;
    return $keyword;
}

/**
 * 对 keywords 参数进行获取、验证与过滤
 *
 * @return array<int, string> 通过校验的关键词列表
 * @throws ValidationException
 */
function get_and_validate_keywords(): array
{
    $errors = [];

    // 仅允许 GET
    if (($_SERVER['REQUEST_METHOD'] ?? '') !== 'GET') {
        respond(
            [
                'success' => false,
                'errors'  => [
                    [
                        'field'   => 'method',
                        'message' => 'Only GET method is allowed.',
                        'code'    => 'method_not_allowed',
                    ],
                ],
            ],
            405,
            ['Allow' => 'GET']
        );
    }

    // 判断参数是否存在及是否为数组
    $hasParam = array_key_exists('keywords', $_GET);
    if (!$hasParam) {
        $errors[] = [
            'field'   => 'keywords',
            'message' => 'Parameter "keywords" is required and must be an array (e.g., ?keywords[]=foo&keywords[]=bar).',
            'code'    => 'required',
        ];
        throw new ValidationException($errors);
    }
    if (!is_array($_GET['keywords'])) {
        $errors[] = [
            'field'   => 'keywords',
            'message' => 'Parameter "keywords" must be an array. Use repeated keys like keywords[]=value.',
            'code'    => 'type_array_required',
        ];
        throw new ValidationException($errors);
    }

    // 使用 filter_input 获取并初步过滤为数组
    $rawKeywords = filter_input(INPUT_GET, 'keywords', FILTER_DEFAULT, FILTER_REQUIRE_ARRAY);
    // 防御性判断（极端情况下 $rawKeywords 可能为 null）
    if (!is_array($rawKeywords)) {
        $errors[] = [
            'field'   => 'keywords',
            'message' => 'Failed to read "keywords" as array.',
            'code'    => 'read_failure',
        ];
        throw new ValidationException($errors);
    }

    // 数量限制
    if (count($rawKeywords) > MAX_KEYWORDS) {
        $errors[] = [
            'field'   => 'keywords',
            'message' => 'Too many keywords. At most ' . MAX_KEYWORDS . ' items are allowed.',
            'code'    => 'too_many_items',
        ];
        throw new ValidationException($errors);
    }

    $valid = [];
    foreach ($rawKeywords as $index => $value) {
        // 禁止嵌套数组
        if (is_array($value)) {
            $errors[] = [
                'field'   => "keywords[$index]",
                'message' => 'Nested arrays are not allowed. Each keyword must be a scalar string.',
                'code'    => 'nested_array_not_allowed',
            ];
            continue;
        }

        // PHP 在 GET 中通常只会得到字符串，这里仍做防御性检查
        if (!is_string($value)) {
            $errors[] = [
                'field'   => "keywords[$index]",
                'message' => 'Keyword must be a string.',
                'code'    => 'type_string_required',
            ];
            continue;
        }

        $value = normalize_keyword($value);

        // 空字符串直接跳过（不计入错误，允许用户提交空项但最终至少要有一个有效关键字）
        if ($value === '') {
            continue;
        }

        // 长度校验
        if (mb_len($value) > MAX_KEYWORD_LEN) {
            $errors[] = [
                'field'   => "keywords[$index]",
                'message' => 'Keyword length must be <= ' . MAX_KEYWORD_LEN . ' characters.',
                'code'    => 'too_long',
            ];
            continue;
        }

        // 字符集校验（允许：字母、数字、空格、连字符、下划线；多语言支持）
        if (!preg_match(ALLOWED_PATTERN, $value)) {
            $errors[] = [
                'field'   => "keywords[$index]",
                'message' => 'Keyword contains invalid characters. Only letters, numbers, spaces, hyphen, underscore are allowed.',
                'code'    => 'invalid_charset',
            ];
            continue;
        }

        $valid[] = $value;
    }

    // 去重（保持第一次出现的顺序）
    $valid = array_values(array_unique($valid, SORT_STRING));

    // 至少需要一个有效关键词
    if (count($valid) === 0) {
        $errors[] = [
            'field'   => 'keywords',
            'message' => 'At least one non-empty, valid keyword is required.',
            'code'    => 'no_valid_keyword',
        ];
    }

    if (!empty($errors)) {
        throw new ValidationException($errors);
    }

    return $valid;
}

// 执行
try {
    $keywords = get_and_validate_keywords();

    respond([
        'success' => true,
        'data'    => [
            'keywords' => $keywords,
        ],
        'meta'    => [
            'count' => count($keywords),
        ],
    ]);
} catch (ValidationException $e) {
    respond([
        'success' => false,
        'errors'  => $e->getErrors(),
    ], 422);
} catch (Throwable $e) {
    // 生产环境请记录日志（勿输出敏感信息）
    respond([
        'success' => false,
        'errors'  => [
            [
                'message' => 'Internal server error.',
                'code'    => 'internal_error',
            ],
        ],
    ], 500);
}

方法说明

• 请求方法与入口
  • 强制仅允许 GET 请求，违规返回 405（并设置 Allow: GET）。
• 参数获取
  • 使用 filter_input(INPUT_GET, ..., FILTER_REQUIRE_ARRAY) 获取数组类型，保证类型安全。
  • 同时结合 $_GET 做存在性与类型的可靠判断，明确“缺失”和“类型错误”的区别。
• 基础验证
  • 数量限制：最多 10 个关键词。
  • 长度限制：每个关键词最多 64 个字符（多字节安全）。
  • 字符集限制：仅允许字母、数字、空格、连字符（-）和下划线（_）；正则采用 Unicode 模式，支持多语言。
  • 去重处理：保留第一次出现的顺序。
  • 允许用户传入空元素，但最终必须至少存在 1 个有效关键词。
• 安全过滤
  • 规范化空白：去除首尾空白，并将连续空白折叠为单个空格，减小“同义输入”的差异。
  • 不在此处进行“输出转义”，而是在输出到 HTML 时使用上下文相关的转义（如 htmlspecialchars）。
• 错误处理
  • 使用 ValidationException 汇总错误，返回结构化 JSON，便于前端逐字段展示提示。
  • 区分 422（校验失败）与 500（服务器错误），以及 405（方法不允许）。

安全建议

• 防止 XSS
  • 本接口返回 JSON 且不渲染 HTML；若将关键词回显到 HTML，请使用 htmlspecialchars($keyword, ENT_QUOTES | ENT_SUBSTITUTE, 'UTF-8')。
• 防止 SQL 注入
  • 任何将关键词用于数据库查询的地方，务必使用参数化查询（PDO prepare/bindParam），绝不可直接拼接 SQL。
  • 示例（MySQL，模糊搜索）：

    // $keywords 已通过上述验证
    $pdo = new PDO('mysql:host=localhost;dbname=app;charset=utf8mb4', 'user', 'pass', [
        PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION,
    ]);
    
    // 构造 (name LIKE ? OR name LIKE ? ...) 形式，使用绑定参数
    $placeholders = [];
    $params = [];
    foreach ($keywords as $kw) {
        $placeholders[] = 'name LIKE ?';
        $params[] = '%' . $kw . '%';
    }
    $sql = 'SELECT id, name FROM products WHERE ' . implode(' OR ', $placeholders) . ' LIMIT 50';
    $stmt = $pdo->prepare($sql);
    $stmt->execute($params);
    $rows = $stmt->fetchAll(PDO::FETCH_ASSOC);
    

• 速率限制与滥用防护
  • 对搜索类接口建议增加限流与缓存，防止暴力爬取或滥用。
• 日志与监控
  • 记录 4xx/5xx 事件到安全日志（勿记录敏感信息），便于审计与排错。

使用示例

• URL 格式（正确）
  • /search.php?keywords[]=iphone&keywords[]=13%20Pro&keywords[]=保护壳
• cURL

  curl -G "http://localhost/search.php" \
    --data-urlencode "keywords[]=iphone" \
    --data-urlencode "keywords[]=13 Pro" \
    --data-urlencode "keywords[]=保护壳"
  

• JavaScript fetch

  const params = new URLSearchParams();
  ['iphone', '13 Pro', '保护壳'].forEach(v => params.append('keywords[]', v));
  
  fetch('/search.php?' + params.toString(), { method: 'GET' })
    .then(r => r.json())
    .then(console.log)
    .catch(console.error);
  

• 成功响应示例

  {
    "success": true,
    "data": { "keywords": ["iphone", "13 Pro", "保护壳"] },
    "meta": { "count": 3 }
  }
  

• 失败响应示例（超过数量）

  {
    "success": false,
    "errors": [
      {
        "field": "keywords",
        "message": "Too many keywords. At most 10 items are allowed.",
        "code": "too_many_items"
      }
    ]
  }
  

扩展建议

• 宽松输入兼容
  • 可选支持单字符串输入自动拆分为数组（例如逗号分隔），但务必明确开启开关，避免与严格校验冲突。
• 更细化校验策略
  • 增加最小长度（如 >= 2），停用词过滤，前后缀黑名单等。
• 去重策略优化
  • 采用大小写不敏感去重、去除标点后的语义去重等。
• 业务层集成
  • 支持分页、排序、字段白名单与查询耗时上限。
• 性能与可维护
  • 抽离为独立的 Request DTO/Validator 类，配合 PSR-15 中间件统一处理请求体验证与错误响应。
• 国际化与可观测性
  • 错误消息多语言化；为成功/失败响应增加 request_id 并打通日志链路，便于追踪。