异常教程

PHP FILTER_UNSAFE_RAW 过滤器（千字长文）

更新时间:

💡一则或许对你有用的小广告

欢迎加入小哈的星球 ，你将获得：专属的项目实战 / 1v1 提问 / Java 学习路线 / 学习打卡 / 每月赠书 / 社群讨论

  • 新项目:《从零手撸：仿小红书（微服务架构）》 正在持续爆肝中，基于 Spring Cloud Alibaba + Spring Boot 3.x + JDK 17...，点击查看项目介绍 ;
  • 《从零手撸：前后端分离博客项目（全栈开发）》 2 期已完结，演示链接： http://116.62.199.48/ ;

截止目前， 星球 内专栏累计输出 82w+ 字，讲解图 3441+ 张，还在持续爆肝中.. 后续还会上新更多项目，目标是将 Java 领域典型的项目都整一波，如秒杀系统, 在线商城, IM 即时通讯，权限管理，Spring Cloud Alibaba 微服务等等，已有 2900+ 小伙伴加入学习 ，欢迎点击围观

在 PHP 开发中，数据过滤是一个至关重要的环节。它决定了应用程序的安全性、稳定性和用户体验。PHP 自带的过滤器功能为开发者提供了丰富的数据处理工具，而其中 FILTER_UNSAFE_RAW 过滤器是一个容易被误解但又不可或缺的特殊存在。本文将从基础概念、使用场景、实际案例和安全注意事项等多个维度，深入浅出地解析这一过滤器的原理与应用。

一、PHP 过滤器基础：什么是数据过滤？

1.1 过滤器的定义与作用

PHP 过滤器（Filter）是一组预定义的函数和常量，用于对输入数据或输出内容进行标准化处理。它们可以验证数据的有效性、清除无效字符、转换数据格式，甚至直接返回原始数据。例如，FILTER_VALIDATE_EMAIL 可以验证邮箱格式，FILTER_SANITIZE_STRING 可以去除 HTML 标签。

1.2 过滤器的分类

PHP 过滤器分为两大类：

  • 验证型过滤器：判断数据是否符合特定规则（如 FILTER_VALIDATE_URL）。
  • 清理型过滤器：对数据进行清洗或转换（如 FILTER_SANITIZE_NUMBER_INT）。

而 FILTER_UNSAFE_RAW 是一种特殊的过滤器，它既不验证也不清理数据，而是直接返回原始输入。这种“无操作”的特性让它成为了一个“双刃剑”。

二、FILTER_UNSAFE_RAW 的核心特性

2.1 过滤器的官方定义

根据 PHP 官方文档，FILTER_UNSAFE_RAW 的描述是：

"返回未修改的输入数据，但会标记为不可信。"

这里的关键词是“未修改”和“不可信”。它不会对输入进行任何过滤或验证，但明确告知开发者该数据未经过安全处理，需要自行负责后续的安全逻辑。

2.2 与其他过滤器的对比

通过表格对比 FILTER_UNSAFE_RAW 与其他常见过滤器的区别：

过滤器名称功能描述是否修改数据典型用途
FILTER_UNSAFE_RAW返回原始数据，不进行任何处理否需要保留原始数据时
FILTER_SANITIZE_STRING去除 HTML 标签和特殊字符是清洗用户输入的文本
FILTER_VALIDATE_EMAIL验证邮箱格式是否合法否输入验证
FILTER_SANITIZE_ENCODED转义特殊字符（如 URL 编码）是准备数据用于 URL 参数

2.3 为什么需要这个过滤器？

想象一个场景：用户上传了一个文件名，开发者需要保留文件的原始名称（如 report_2023.pdf），但后续会通过其他方式验证文件类型。此时，直接使用 FILTER_UNSAFE_RAW 可以确保文件名不被修改，同时明确标记数据为“不可信”，避免后续逻辑中误用未经验证的数据。

三、FILTER_UNSAFE_RAW 的典型应用场景

3.1 场景 1：保留原始数据格式

案例：表单提交中的文件名处理

假设用户上传了一个文件，但需要保留文件名中的特殊字符（如 2023-财务报告_v2.xlsx）。此时，若使用 FILTER_SANITIZE_STRING，可能会错误地删除下划线或数字。通过 FILTER_UNSAFE_RAW 可以保留原始名称，但需在后续代码中验证文件类型和扩展名。

$originalFilename = filter_input(INPUT_POST, 'filename', FILTER_UNSAFE_RAW);  
// 后续验证文件扩展名  
if (pathinfo($originalFilename, PATHINFO_EXTENSION) !== 'xlsx') {  
    throw new Exception("文件格式不支持");  
}

3.2 场景 2：复杂数据结构的传递

案例：处理 JSON 格式的 POST 数据

当接收一个 JSON 格式的请求体时，若直接使用 FILTER_SANITIZE_STRING 可能会破坏数据结构。通过 FILTER_UNSAFE_RAW 可以完整保留原始数据，再通过 json_decode 解析：

原始请求体：  
{  
    "user": "john_doe",  
    "score": 95  
}  

// 使用过滤器获取原始数据  
$jsonData = filter_input(INPUT_POST, 'data', FILTER_UNSAFE_RAW);  
$parsedData = json_decode($jsonData, true);  

// 验证数据字段  
if (!isset($parsedData['user']) || !is_int($parsedData['score'])) {  
    throw new Exception("数据格式错误");  
}

3.3 场景 3：兼容遗留系统或第三方接口

某些旧系统或第三方 API 可能要求保留数据的原始格式。例如，某个支付接口需要接收未转义的特殊符号（如 & 或 +），此时使用 FILTER_UNSAFE_RAW 可避免 PHP 自动进行 URL 解码：

// 接收未解码的原始数据  
rawData = filter_input(INPUT_GET, 'params', FILTER_UNSAFE_RAW);  
// 直接传递给第三方接口  
sendToLegacySystem($rawData);

四、使用 FILTER_UNSAFE_RAW 的安全注意事项

4.1 核心原则：信任但验证

虽然 FILTER_UNSAFE_RAW 不会修改数据，但它强制开发者主动承担安全责任。必须遵循以下原则：

  1. 始终进行后续验证：即使数据来源可信，也要验证其格式和内容。
  2. 避免直接输出：未经转义的用户输入直接输出到网页可能导致 XSS 攻击。
  3. 结合其他过滤器：在需要时叠加使用其他过滤器（如 FILTER_VALIDATE_IP 验证 IP 地址）。

4.2 高危场景示例：SQL 注入漏洞

假设开发者使用 FILTER_UNSAFE_RAW 接收用户输入的查询参数，并直接拼接 SQL 语句：

// 错误示例：可能导致 SQL 注入  
$searchTerm = filter_input(INPUT_GET, 'search', FILTER_UNSAFE_RAW);  
$query = "SELECT * FROM users WHERE name = '$searchTerm'";  
// 如果用户输入 ' OR 1=1 --，将导致漏洞

4.3 正确实践：使用预处理语句

通过 FILTER_UNSAFE_RAW 获取数据后，应使用 PDO 的预处理语句来防止注入：

$searchTerm = filter_input(INPUT_GET, 'search', FILTER_UNSAFE_RAW);  
$stmt = $pdo->prepare("SELECT * FROM users WHERE name = :name");  
$stmt->execute(['name' => $searchTerm]);

五、FILTER_UNSAFE_RAW 的替代方案与选择逻辑

5.1 替代方案对比

需求推荐过滤器备注
保留原始数据格式FILTER_UNSAFE_RAW需后续验证
清洗 HTML 特殊字符FILTER_SANITIZE_STRING自动移除 <script> 等标签
验证邮箱地址格式FILTER_VALIDATE_EMAIL返回布尔值，需配合 FILTER_FLAG_NO_EMPTY

5.2 选择过滤器的决策树

是否需要修改数据？  
├── 是 → 使用清理型过滤器（如 `FILTER_SANITIZE_ENCODED`）  
└── 否 → 是否需要验证数据？  
    ├── 是 → 使用验证型过滤器（如 `FILTER_VALIDATE_IP`）  
    └── 否 → 使用 `FILTER_UNSAFE_RAW` + 后续验证

六、进阶技巧：结合其他 PHP 安全机制

6.1 与 addslashes 的组合

在极少数情况下，若需兼容旧代码的 addslashes 转义功能，可以结合 FILTER_UNSAFE_RAW：

$rawData = filter_input(INPUT_POST, 'comment', FILTER_UNSAFE_RAW);  
$safeData = addslashes($rawData);

6.2 与 htmlspecialchars 的搭配

输出用户数据到网页时，即使使用了 FILTER_UNSAFE_RAW，也应通过 htmlspecialchars 进行 HTML 转义：

echo htmlspecialchars($rawData, ENT_QUOTES, 'UTF-8');

结论

PHP FILTER_UNSAFE_RAW 过滤器 是一个功能特殊但不可或缺的工具。它要求开发者在保留数据原始性的同时，必须主动承担安全验证的责任。通过合理使用该过滤器，并结合预处理语句、数据验证和转义技术，可以有效提升应用程序的安全性。对于 PHP 开发者而言，理解这一过滤器的原理与边界，是构建健壮、安全系统的必经之路。

最后提醒：在绝大多数情况下，优先选择其他过滤器或组合使用安全机制，避免直接依赖 FILTER_UNSAFE_RAW。只有在必要且可控的场景下，才应使用这一过滤器。

最新发布

查看更多文章