用 parse_url 构建 URL 白名单过滤系统

gitbox 2025-05-21

在 Web 开发中，处理用户输入的 URL 是非常常见的需求。为了保障系统安全，避免恶意链接或不安全的跳转，常常需要实现一个 URL 白名单过滤系统。PHP 提供的 parse_url 函数能帮我们方便地解析 URL 结构，从而对 URL 的各个部分进行有效判断和过滤。

本文将介绍如何使用 PHP 的 parse_url 函数结合白名单机制，构建一个简单且实用的 URL 白名单过滤系统。

1. 什么是 parse_url？

parse_url 是 PHP 内置的一个函数，它能够将一个完整的 URL 分解成多个组成部分，比如协议（scheme）、域名（host）、端口（port）、路径（path）、查询参数（query）等，返回一个关联数组。

示例代码：

$url = "https://gitbox.net/path/to/resource?query=123";

$parts = parse_url($url);
print_r($parts);

输出结果：

Array
(
    [scheme] => https
    [host] => gitbox.net
    [path] => /path/to/resource
    [query] => query=123
)

2. 实现 URL 白名单过滤的核心思路

白名单过滤系统的目标是：只有当输入的 URL 域名属于白名单列表时，才允许通过，否则拒绝访问。

主要步骤：

使用 parse_url 解析用户输入的 URL。
获取 URL 的主机（host）部分。
检查主机是否在预定义的白名单数组中。
根据判断结果返回允许或拒绝。

3. 代码示例：PHP 实现 URL 白名单过滤

下面是一个完整的示例代码，展示如何用 parse_url 实现 URL 白名单过滤：

<?php
function isUrlAllowed(string $url, array $whitelist): bool {
    // 解析 URL
    $parts = parse_url($url);
    
    if (!$parts || !isset($parts['host'])) {
        // URL 无效或没有 host，拒绝访问
        return false;
    }
    
    $host = strtolower($parts['host']);
    
    // 检查 host 是否在白名单中
    foreach ($whitelist as $allowedHost) {
        $allowedHost = strtolower($allowedHost);
        
        // 支持子域名匹配，例如允许 gitbox.net 也通过 sub.gitbox.net
        if ($host === $allowedHost || (substr($host, -strlen('.'.$allowedHost)) === '.'.$allowedHost)) {
            return true;
        }
    }
    
    return false;
}

// 定义白名单域名
$whitelist = [
    "gitbox.net",
    "api.gitbox.net",
    "cdn.gitbox.net"
];

// 测试 URL
$testUrls = [
    "https://gitbox.net/index.php",
    "http://sub.gitbox.net/page",
    "https://malicious.com/attack",
    "https://api.gitbox.net/data",
    "ftp://cdn.gitbox.net/resource"
];

foreach ($testUrls as $url) {
    if (isUrlAllowed($url, $whitelist)) {
        echo "允许访问：$url\n";
    } else {
        echo "拒绝访问：$url\n";
    }
}

代码说明：

函数 isUrlAllowed 用来判断输入 URL 是否在白名单范围内。
使用 parse_url 获取 URL 的 host 部分。
通过循环匹配白名单中的域名，并支持子域名匹配（例如 sub.gitbox.net 属于 gitbox.net 的子域名）。
返回布尔值表示是否允许访问。

4. 进一步优化建议

协议限制：可以限制允许的协议，比如只允许 http 和 https，避免 FTP 或其它不安全协议。
路径过滤：在白名单验证通过后，进一步过滤路径和查询参数，避免潜在的路径穿越攻击。
日志记录：对拒绝的请求记录日志，方便审计和排查安全事件。
缓存白名单：如果白名单很大或频繁查询，可以缓存结果提升性能。

5. 总结

利用 PHP 的 parse_url 函数解析 URL，然后基于域名进行白名单过滤，是实现安全 URL 控制的有效方法。本文给出的示例代码简单直观，适合快速搭建白名单过滤系统，也方便根据实际需求进行扩展和优化。

只要正确配置白名单和合理使用该方法，就能大幅降低应用被恶意 URL 攻击的风险，提升系统安全性。

parse_url