编辑“︁PHP白名单过滤”︁

= PHP白名单过滤 =

'''PHP白名单过滤'''是一种安全编程技术，用于确保用户输入仅包含预定义的合法值或格式。与黑名单（阻止已知恶意输入）不同，白名单仅允许已知安全的输入，从而提供更强的安全性。这种方法广泛应用于表单验证、文件上传、API参数处理等场景。

== 基本原理 ==
白名单过滤的核心思想是：
# 定义一组允许的值或模式（白名单）。
# 检查用户输入是否完全匹配白名单中的条目。
# 拒绝任何不在白名单中的输入。

数学表达为：给定输入 <math>x</math> 和白名单集合 <math>W = \{w_1, w_2, ..., w_n\}</math>，当且仅当 <math>x \in W</math> 时，输入被接受。

== 实现方法 ==
=== 1. 简单值白名单 ===
适用于固定选项（如下拉菜单、单选按钮）：
<syntaxhighlight lang="php">
$allowed_statuses = ['active', 'pending', 'archived'];
$user_input = $_POST['status'];

if (!in_array($user_input, $allowed_statuses)) {
    die("Invalid status value");
}
// 安全使用 $user_input
</syntaxhighlight>

'''输入/输出示例：'''
* 输入: <code>'active'</code> → 通过验证
* 输入: <code>'deleted'</code> → 触发错误

=== 2. 正则表达式白名单 ===
适用于需要模式匹配的场景（如用户名、邮箱）：
<syntaxhighlight lang="php">
$pattern = '/^[a-z0-9_]{3,16}$/'; // 只允许小写字母、数字和下划线
$username = $_POST['username'];

if (!preg_match($pattern, $username)) {
    die("Username contains invalid characters");
}
</syntaxhighlight>

'''输入/输出示例：'''
* 输入: <code>'valid_user123'</code> → 通过验证
* 输入: <code>'admin<script>'</code> → 触发错误

=== 3. 类型转换白名单 ===
确保输入为特定类型：
<syntaxhighlight lang="php">
$user_id = $_POST['user_id'];
if (!ctype_digit($user_id)) { // 检查是否为纯数字
    die("Invalid user ID");
}
$user_id = (int)$user_id; // 显式转换为整数
</syntaxhighlight>

== 实际案例 ==
=== 案例1：文件上传扩展名检查 ===
<mermaid>
flowchart TD
    A[接收文件] --> B{扩展名在白名单中?}
    B -->|是| C[保存文件]
    B -->|否| D[拒绝上传]
</mermaid>

<syntaxhighlight lang="php">
$allowed_extensions = ['jpg', 'png', 'gif'];
$uploaded_file = 'profile.php';
$file_extension = strtolower(pathinfo($uploaded_file, PATHINFO_EXTENSION));

if (!in_array($file_extension, $allowed_extensions)) {
    die("只允许上传图片文件");
}
</syntaxhighlight>

=== 案例2：API参数过滤 ===
处理REST API中的分类参数：
<syntaxhighlight lang="php">
$valid_categories = ['books', 'electronics', 'clothing'];
$category = $_GET['category'] ?? '';

if (!in_array($category, $valid_categories)) {
    http_response_code(400);
    echo json_encode(['error' => 'Invalid category']);
    exit;
}
</syntaxhighlight>

== 高级技巧 ==
=== 动态白名单生成 ===
从数据库加载合法值（需确保数据源可信）：
<syntaxhighlight lang="php">
$pdo = new PDO($dsn, $user, $pass);
$allowed_countries = $pdo->query("SELECT iso_code FROM countries")->fetchAll(PDO::FETCH_COLUMN);
</syntaxhighlight>

=== 组合验证 ===
白名单与其他验证技术结合：
<syntaxhighlight lang="php">
$email = $_POST['email'];
$allowed_domains = ['example.com', 'trusted.org'];

// 1. 验证邮箱格式
if (!filter_var($email, FILTER_VALIDATE_EMAIL)) {
    die("Invalid email format");
}

// 2. 验证域名在白名单中
$domain = substr(strrchr($email, "@"), 1);
if (!in_array($domain, $allowed_domains)) {
    die("Email domain not allowed");
}
</syntaxhighlight>

== 安全注意事项 ==
* '''永远不要依赖客户端验证'''：白名单必须在服务器端实现
* '''大小写敏感问题'''：使用<code>strtolower()</code>或<code>strtoupper()</code>规范化输入
* '''边界情况'''：空字符串、NULL值、数组输入需要特殊处理
* '''性能考虑'''：大型白名单应使用哈希查找（如<code>array_flip()</code>+<code>isset()</code>）

== 最佳实践总结 ==
# 尽可能使用严格的白名单而非黑名单
# 在最早阶段验证输入（"边界验证"原则）
# 拒绝时提供最小化错误信息（避免信息泄露）
# 记录验证失败的尝试（用于安全审计）
# 定期审查和更新白名单条目

[[Category:编程语言]]
[[Category:PHP]]
[[Category:PHP安全编程]]