萬盛學電腦網

您现在的位置: 萬盛學電腦網 >> 程式設計 >  >> 網路程式設計 >> PHP 程式設計

PHP parse_url() 函式完整指南:URL 解析、組件提取、邊界情況與安全應用

前言

parse_url() 是 PHP 解析 URL 的標準工具,能將 URL 分解為 scheme、host、path、query、fragment 等組件。然而,其對不完整 URL、相對路徑、特殊字元的處理行為常導致誤解。本文深入解析函式行為、參數選項、實戰應用與替代方案。

函式簽名與參數

parse_url(string $url, int $component = -1): array|string|int|float|false|null
  • $url:要解析的 URL 字串
  • $component:可選,指定回傳特定組件常數(見下表)
  • 回傳:關聯陣列(預設)、指定組件的字串/整數、失敗回傳 false

URL 組件常數對照表

常數對應組件回傳型別範例值
PHP_URL_SCHEME協定stringhttps
PHP_URL_HOST主機名stringexample.com
PHP_URL_PORT連接埠int443
PHP_URL_USER使用者名稱stringusername
PHP_URL_PASS密碼stringpassword
PHP_URL_PATH路徑string/path/to/resource
PHP_URL_QUERY查詢字串stringid=123&sort=desc
PHP_URL_FRAGMENT片段識別碼stringsection1

完整解析範例

<?php
$url = 'https://user:pass@example.com:443/path/to/page?query=value#section';

$result = parse_url($url);
print_r($result);
/*
Array
(
    [scheme] => https
    [host] => example.com
    [port] => 443
    [user] => user
    [pass] => pass
    [path] => /path/to/page
    [query] => query=value
    [fragment] => section
)
*/

// 取得單一組件
echo parse_url($url, PHP_URL_HOST);    // example.com
echo parse_url($url, PHP_URL_PATH);    // /path/to/page
echo parse_url($url, PHP_URL_QUERY);   // query=value
?>

邊界情況與特殊行為

1. 相對 URL(無 scheme)

<?php
// 無 scheme:path 會包含整個字串
parse_url('example.com/path?query=1');
/*
[
    'path' => 'example.com/path',
    'query' => 'query=1'
]
// host 為空!因為無 scheme 視為相對路徑
*/

// 修正:補上 scheme
parse_url('https://example.com/path?query=1'); // 正確解析 host
?>

2. 僅有路徑

<?php
parse_url('/api/users/123');
// ['path' => '/api/users/123']
?>

3. 包含特殊字元、中文、IPv6

<?php
// 中文路徑(需 URL 編碼)
parse_url('https://example.com/中文路徑');
// ['host' => 'example.com', 'path' => '/中文路徑'] (PHP 會保留原始字元)

// IPv6 主機
parse_url('https://[2001:db8::1]:8080/path');
// ['scheme'=>'http', 'host'=>'2001:db8::1', 'port'=>8080, 'path'=>'/path']

// 使用者資訊含特殊字元
parse_url('ftp://user%40name:pass%23word@ftp.example.com');
// ['user'=>'user@name', 'pass'=>'pass#word'] (自動 URL 解碼)
?>

4. 失敗情況回傳 false

<?php
var_dump(parse_url(''));              // false
var_dump(parse_url('not a url'));     // false (PHP 8.1+ 嚴格模式)
// PHP 8.0 及以前可能回傳部分解析結果
?>

進階應用:查詢字串進一步解析

parse_url() 只回傳原始查詢字串,需搭配 parse_str() 解析為陣列:

<?php
$url = 'https://api.example.com/search?q=php&tag=web&tag=backend&page=2';

$parts = parse_url($url);
$queryString = $parts['query'] ?? '';

parse_str($queryString, $queryArray);
print_r($queryArray);
/*
Array
(
    [q] => php
    [tag] => Array ( [0] => web, [1] => backend )
    [page] => 2
)
*/

// 完整封裝函式
function parseUrlComplete(string $url): array {
    $parts = parse_url($url);
    if ($parts === false) return [];
    
    $query = [];
    if (!empty($parts['query'])) {
        parse_str($parts['query'], $query);
    }
    $parts['query_params'] = $query;
    return $parts;
}
?>

實戰應用場景

1. URL 驗證與正規化

<?php
function normalizeUrl(string $url): string {
    $parts = parse_url($url);
    if ($parts === false || empty($parts['scheme']) || empty($parts['host'])) {
        throw new InvalidArgumentException('Invalid URL');
    }
    
    $normalized = $parts['scheme'] . '://';
    if (!empty($parts['user'])) {
        $normalized .= $parts['user'];
        if (!empty($parts['pass'])) $normalized .= ':' . $parts['pass'];
        $normalized .= '@';
    }
    $normalized .= $parts['host'];
    if (!empty($parts['port'])) $normalized .= ':' . $parts['port'];
    $normalized .= $parts['path'] ?? '/';
    if (!empty($parts['query'])) $normalized .= '?' . $parts['query'];
    if (!empty($parts['fragment'])) $normalized .= '#' . $parts['fragment'];
    
    return $normalized;
}
?>

2. 判斷同源策略

<?php
function isSameOrigin(string $url1, string $url2): bool {
    $p1 = parse_url($url1);
    $p2 = parse_url($url2);
    
    return ($p1['scheme'] ?? '') === ($p2['scheme'] ?? '')
        && ($p1['host'] ?? '') === ($p2['host'] ?? '')
        && ($p1['port'] ?? ($p1['scheme'] === 'https' ? 443 : 80)) 
           === ($p2['port'] ?? ($p2['scheme'] === 'https' ? 443 : 80));
}
?>

3. 安全重導向:防開放重導向漏洞

<?php
function safeRedirect(string $target, array $allowedHosts): void {
    $parts = parse_url($target);
    if ($parts === false) {
        throw new Exception('Invalid redirect URL');
    }
    
    // 僅允許相對路徑或白名單主機
    if (empty($parts['host']) || in_array($parts['host'], $allowedHosts, true)) {
        header('Location: ' . $target, true, 302);
        exit;
    }
    throw new Exception('Redirect to external host not allowed');
}

// 使用
safeRedirect('/dashboard', ['example.com']);        // 允許相對路徑
safeRedirect('https://example.com/path', ['example.com']); // 允許白名單
// safeRedirect('https://evil.com', ['example.com']); // 拋出例外
?>

4. 組合 URL(反向操作)

<?php
function buildUrl(array $parts): string {
    $url = '';
    if (!empty($parts['scheme'])) $url .= $parts['scheme'] . '://';
    if (!empty($parts['user'])) {
        $url .= $parts['user'];
        if (!empty($parts['pass'])) $url .= ':' . $parts['pass'];
        $url .= '@';
    }
    if (!empty($parts['host'])) $url .= $parts['host'];
    if (!empty($parts['port'])) $url .= ':' . $parts['port'];
    if (!empty($parts['path'])) $url .= $parts['path'];
    if (!empty($parts['query'])) $url .= '?' . $parts['query'];
    if (!empty($parts['fragment'])) $url .= '#' . $parts['fragment'];
    return $url;
}

// 也可用 http_build_query 組合 query
$query = http_build_query(['q' => 'php', 'page' => 2]); // q=php&page=2
?>

替代方案:更強大的 URI 處理

League/Uri (推薦現代專案)

<?php
// composer require league/uri
use League\Uri\Http;

$uri = Http::createFromString('https://user:pass@example.com:443/path?query=value#frag');
echo $uri->getHost();        // example.com
echo $uri->getPort();        // 443
$uri = $uri->withPath('/new/path')->withQuery('new=value');
echo (string)$uri;           // 完整 URL 字串
?>

PHP 內建:parse_url + http_build_query 組合

無需外部依賴即可處理 90% 場景。

常見錯誤與注意事項

  1. 不解碼 path:parse_url() 回傳的 path 仍為 URL 編碼狀態,需自行 urldecode()
  2. 查詢字串不自動解析:需手動 parse_str()
  3. 相對 URL 解析不可靠:務必確保輸入為絕對 URL
  4. PHP 版本差異:PHP 8.1+ 對無效 URL 較嚴格,回傳 false 而非部分結果
  5. 效能:單次解析微秒級,高頻場景可快取結果

結語

parse_url() 是 PHP 處理 URL 的基石函式,掌握其組件結構、邊界行為、查詢字串二次解析、安全重導向防護,是後端開發必備技能。現代專案建議引入 league/uri 或 nyholm/psr7 等 PSR-7 相容 URI 物件,獲得型別安全、不可變操作、標準化介面,減少字串操作錯誤。

copyright © 萬盛學電腦網 all rights reserved